Accessing Logs

Like other diagnostics, logs are available to read from the Archivist's ArchiveAccessor protocol. See the ArchiveAccessor reference for general information on the API and its usage.

Parameters

StreamParameters are passed to the StreamDiagnostics method to initialize a BatchIterator.

DataType

Send the LOGS datatype to request logs from the Archivist.

StreamMode

Logs are available over SNAPSHOT, SNAPSHOT_THEN_SUBSCRIBE, and SUBSCRIBE modes.

Format

Only JSON is currently supported.

ClientSelectorConfiguration

Only select_all=true is currently supported.

batch_retrieval_timeout_seconds

This 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

Results are returned as a vector<FormattedContent> with each entry's variant matching the requested Format, although JSON is the only currently supported format.

Buffer contents

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.

JSON object contents

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": "core/network/netstack",
    "metadata": {
        "timestamp": 1234567890,
        "severity": "INFO",
        "component_url": "fuchsia-pkg://fuchsia.com/network#meta/netstack.cm",
        "size_bytes": 123
    },
    "payload": {
        "root": {
            "pid": 78,
            "tid": 78,
            "tag": "netstack",
            "message": "something happened!"
        }
    }
}

Timestamps

Time in logs is recorded using the kernel's monotonic clock and conveyed without modification as an unsigned integer.

Dropped logs

Dropped logs are conveyed in the metadata.errors field of the results object, which is an array when present:

{
    "metadata": {
        ...
        "errors": [
            {
                "dropped_logs": {
                    "count": 3
                }
            }
        ]
    }
}

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 that 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.

Legacy APIs

Archivist serves the fuchsia.logger.Log protocol that allows clients to read logs in a text format. This API is superseded by fuchsia.diagnostics.ArchiveAccessor and will be deleted in the future.