Like other diagnostics, logs are availble to read from the Archivist's ArchiveAccessor protocol. See the ArchiveAccessor reference for general information on the API and its usage.
StreamParameters are passed to the StreamDiagnostics method to initialize a BatchIterator.
Send the LOGS datatype to request logs from the Archivist.
Logs are available over SNAPSHOT, SNAPSHOT_THEN_SUBSCRIBE, and SUBSCRIBE modes.
Only JSON is currently supported.
Only select_all=true is currently supported.
batch_retrieval_timeout_secondsThis option has no effect when requesting logs, as there is no point during log queries where the Archivist has to wait for components producing logs.
Results are returned as a vector<FormattedContent> with each entry's variant matching the requested Format, although JSON is the only currently supported format.
Each buffer contains a top-level array with all of its elements as objects:
[ { "metadata": { ... }, "payload": { ... } }, { "metadata": { ... }, "payload": { ... } }, ... ]
The second level of nesting allows the Archivist to pack log messages efficiently while also using the same API to serve Inspect results where there is a 1:1 mapping between parsed VMOs and returned VMOs.
Each JSON object in the array is one log message or event. Like other data types in ArchiveAccessor, each object consists of several fields, although the contents of metadata and payload differ from other sources:
{ "version": 1, "moniker": "netstack.cmx", "metadata": { "timestamp": 1234567890, "severity": "Info", "component_url": "fuchsia-pkg://fuchsia.com/netstack#meta/netstack.cmx", "size_bytes": 123 }, "payload": { "root": { "pid": 78, "tid": 78, "tag": "netstack", "message": "something happened!" } } }
Note: version 1 of this format is not yet stable and taking a dependency on it may require some small migrations in the future. These migrations will be transparent to users of the Rust client library.
Caution: messages with multiple tags currently have the tag field repeated in the same object. Most JSON parsers consider this invalid by default, and will be resolved soon.
Time in logs is recorded using the kernel's monotonic clock and conveyed without modification as an unsigned integer.
Note: Archivist has limited ability to verify the accuracy of timestamps reported by components in their log records. Efforts are taken to ensure correctness of common libraries in use, but it is not possible in today's system to guarantee the timestamps in the metadata of logs records.
Logs from components run by appmgr and Component Manager are identical.
However, there are two systems for reporting LogSink connections to Archivist. As a result, v1 monikers from appmgr come as a realm path starting from appmgr plus the manifest filename, sys/netstack.cmx for example. In v2, an explicit component name replaces the manifest filename and all realms are included.
Caution: Due to an issue with CapabilityRequested events the v2 monikers returned start at the archivist rather than the topology root. For components in the same realm, this results in a slightly confusing moniker like .\\archivist:0/driver_manager:0. For components with a different parent realm it is even more confusing: .\\archivist:0\\bootstrap:0/core:0/system-update-committer:0.
Dropped logs are conveyed in the metadata.errors field of the results object, which is an array when present:
{ "metadata": { ... "errors": [ { "DroppedLogs": { "count": 3 } } ] } }
Note: version 1 of this format is not yet stable and taking a dependency on it may require some small migrations in the future. These migrations will be transparent to users of the Rust client library.
A message with dropped logs in the errors may or may not have a payload associated, depending on where the message was dropped.
When a producing component overflows its log socket, it increments a counter which is used on subsequent successful sends to populate a field in the log metadata. The Archivist tracks this metadata but isn't able to learn about a component dropping log records except through later log records from that component. The metadata is passed on to clients in the same form, as an error field in a populated log record.
If the message was dropped by the Archivist due to buffer limits, the error is sent in a synthesized message without a payload to ensure clients are notified even if the given producer does not log again.
Archivist serves the fuchsia.logger.Log protocol which allows clients to read logs in a text format. This API is superceded by fuchsia.diagnostics.ArchiveAccessor and will be deleted in the future.
Note: Prefer Log.ListenSafe and Log.DumpLogsSafe to avoid channel overflow issues. Deletion of the unsafe fuchsia.logger.LogListener API is planned.