一个简单且高性能的 Rust 库,可帮助解析 Apple 的 Unified Log 文件。
Unified Logs 于 macOS 10.12(Sierra,2016)引入,是 Apple 跨 macOS、iOS、watchOS 和 tvOS 的统一日志系统的一部分。该库可以解析二进制 tracev3 文件并输出结构化日志条目。
每个条目包含:格式化消息(以及原始消息和原始日志项)、时间戳(Intel 和 ARM)、事件和日志类型、进程和库路径及其 UUID、子系统、类别、PID、线程 ID、EUID、活动 ID(及其父级)、启动 UUID 和时区。
示例二进制文件位于 examples/ 中:
unifiedlog_iterator - 将 logarchive(或实时 macOS 系统上的日志)解析为 JSONL 或 CSV 文件,支持书签/恢复功能。输出文件会相当大。cargo run --release --manifest-path examples/Cargo.toml -p unifiedlog_iterator -- --mode log-archive --input system_logs.logarchive
有关更多用法、如何创建 logarchive 以及预期警告,请参阅 RUNNING.md。
核心类型是 LogEntry<'a, 'b> —— 一个零拷贝的日志条目,直接借用已解析的文件缓冲区。消息按需通过 .message() 惰性格式化,避免在明确需要之前进行堆分配。UUIDText 和共享缓存(DSC)字符串文件在日志条目引用它们时被惰性读取,使内存占用与日志实际使用的数据量成正比;关于急切模式,请参阅 cache::StringStorage::preload。对于长时间运行的进程,logarchive::VisitOptions::memory_budget 通过在 tracev3 文件之间回收字符串数据来限制已加载的字符串数据量(默认关闭)。完整流水线请参阅 ARCHITECTURE.md。
[dependencies]
macos-unifiedlogs = "0.8"
use macos_unifiedlogs::logarchive::visit_logarchive;
use std::path::Path;
visit_logarchive(Path::new("system_logs.logarchive"), |entry| {
let timestamp = entry.timestamp().to_rfc3339();
let process = entry.process.unwrap_or("");
let message = entry.message();
println!("{timestamp} [{process}] {message}");
}).unwrap();
use macos_unifiedlogs::logarchive::visit_live_system;
visit_live_system(|entry| {
let timestamp = entry.timestamp().to_rfc3339();
let process = entry.process.unwrap_or("");
let message = entry.message();
println!("{timestamp} [{process}] {message}");
}).unwrap();
对于已挂载的镜像或非标准根目录,请使用 filesystem::LiveSystemProvider::with_roots
配合 logarchive::visit_provider。
use macos_unifiedlogs::logarchive::visit_logarchive_tracev3_file;
use std::path::Path;
visit_logarchive_tracev3_file(
Path::new("system_logs.logarchive"),
"Persist/0000000000000004.tracev3",
|entry| {
let message = entry.message();
println!("{:?} {:?} {message}", entry.event_type, entry.log_type);
},
)
.unwrap();
实现 traits::FileProvider,即可从任意位置向解析器提供数据——挂载的镜像、证据容器或纯内存。filesystem::InMemoryProvider 是一个现成的内存实现:
use macos_unifiedlogs::filesystem::InMemoryProvider;
use macos_unifiedlogs::logarchive::visit_provider;
let mut provider = InMemoryProvider::default();
provider.tracev3.push(("mem://persist-1.tracev3".into(), tracev3_bytes));
provider.timesync.push(("mem://boot.timesync".into(), timesync_bytes));
provider.uuidtext.insert(some_uuid, uuidtext_bytes);
provider.dsc.insert(dsc_uuid, dsc_bytes);
visit_provider(&provider, |entry| {
println!("{}", entry.message());
})
.unwrap();
UUIDText/DSC 数据由 UUID 按需请求,因为条目会引用它。请改用
logarchive::visit_provider_preloaded 预先加载所有内容
(以最大内存换取最大吞吐量)。
不支持 printf 风格的错误码查找(%m)。该库输出原始错误编号,而非 macOS log 命令提供的可读字符串。
不支持的定制日志对象会以 base64 编码输出,而非解码。