
Apple UnifiedLogs用のクロスプラットフォームパーサー!
AppleのUnified Logファイルを解析するのに役立つ、シンプルで高性能なRustライブラリです。
Unified Logsは、macOS、iOS、watchOS、tvOSにまたがるAppleの統合ログシステムの一部として、macOS 10.12(Sierra、2016年)で導入されました。このライブラリはバイナリのtracev3ファイルを解析し、構造化されたログエントリを出力できます。
各エントリは以下を公開します:フォーマット済みメッセージ(および生メッセージと生ログアイテム)、タイムスタンプ(IntelおよびARM)、イベントとログの種類、UUID付きのプロセスおよびライブラリのパス、サブシステム、カテゴリ、PID、スレッドID、EUID、アクティビティID(および親)、ブートUUID、タイムゾーン。
サンプルのバイナリは examples/ にあります:
unifiedlog_iterator - ログアーカイブ(または稼働中の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();
マウントされたイメージや非標準のルートの場合は、logarchive::visit_provider と共に filesystem::LiveSystemProvider::with_roots を使用してください。
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 エンコードされます。