
Ein plattformübergreifender Parser für Apple UnifiedLogs!
Eine einfache und leistungsstarke Rust-Bibliothek, die beim Parsen von Apples Unified-Log-Dateien helfen kann.
Unified Logs wurden in macOS 10.12 (Sierra, 2016) als Teil von Apples einheitlichem Protokollierungssystem für macOS, iOS, watchOS und tvOS eingeführt. Diese Bibliothek kann die binären tracev3-Dateien parsen und strukturierte Log-Einträge ausgeben.
Jeder Eintrag liefert: die formatierte Nachricht (sowie die Roh-Nachricht und die Roh-Log-Elemente), den Zeitstempel (Intel und ARM), den Ereignis- und Log-Typ, Prozess- und Bibliothekspfade mit ihren UUIDs, Subsystem, Kategorie, PID, Thread-ID, EUID, Aktivitäts-ID (und übergeordnete ID), Boot-UUID und Zeitzone.
Beispiel-Binaries befinden sich in examples/:
unifiedlog_iterator – Parst ein Logarchiv (oder die Logs auf einem laufenden macOS-System)
in eine JSONL- oder CSV-Datei, mit Unterstützung für Lesezeichen/Fortsetzen. Die Ausgabedatei wird
recht groß sein.cargo run --release --manifest-path examples/Cargo.toml -p unifiedlog_iterator -- --mode log-archive --input system_logs.logarchive
Siehe RUNNING.md für weitere Nutzungshinweise, das Erstellen eines Logarchivs und zu erwartende Warnungen.
Der Kerntyp ist LogEntry<'a, 'b> — ein Zero-Copy-Log-Eintrag, der direkt aus den geparsten Dateipuffern entlehnt. Nachrichten werden bei Bedarf lazy über .message() formatiert, wodurch Heap-Allokationen vermieden werden, bis sie explizit benötigt werden. UUIDText- und Shared-Cache-(DSC-)String-Dateien werden lazy gelesen, während Log-Einträge auf sie verweisen, sodass der Speicherbedarf proportional zu dem bleibt, was die Logs tatsächlich nutzen; siehe cache::StringStorage::preload für den Eager-Modus. Für langlaufende Prozesse begrenzt logarchive::VisitOptions::memory_budget die geladenen String-Daten, indem sie zwischen tracev3-Dateien zurückgewonnen werden (standardmäßig deaktiviert). Siehe ARCHITECTURE.md für die vollständige Pipeline.
[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();
Für eingebundene Images oder nicht standardmäßige Roots verwenden Sie filesystem::LiveSystemProvider::with_roots
mit 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();
Implementieren Sie traits::FileProvider, um den Parser von überall aus zu speisen — einem eingebundenen
Image, einem Beweis-Container oder einfach aus dem Speicher. filesystem::InMemoryProvider
ist eine fertige In-Memory-Implementierung:
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-Daten werden lazy per UUID angefordert, wenn Einträge darauf verweisen. Verwenden Sie stattdessen logarchive::visit_provider_preloaded, um alles im Voraus zu laden (maximaler Durchsatz bei maximalem Speicher).
Keine printf-artige Fehlercode-Auflösung (%m). Die Bibliothek gibt die rohe Fehlernummer aus, nicht die menschenlesbare Zeichenkette, die der macOS-Befehl log liefert.
Nicht unterstützte benutzerdefinierte Log-Objekte werden base64-kodiert statt dekodiert.