docs/reference/diagnostics/logs/access.md

# 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](https://fxbug.dev/42141067).

### `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>`][FormattedContent] with each entry's variant
matching the requested [Format], although JSON is the only currently supported format.

### Buffer contents

<!-- TODO(https://fxbug.dev/42143930) link to JSON schema when available -->

Each buffer contains a top-level array with all of its elements as objects:

```json
[
    {
        "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

<!-- TODO(https://fxbug.dev/42143930) link to JSON schema when available -->

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:

```json
{
    "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!"
        }
    }
}
```

Note: version 1 of this format is [not yet stable](https://fxbug.dev/42142433) and taking a dependency
on it may require some small migrations in the future. These migrations will be transparent to users
of the [Rust](/src/lib/diagnostics/reader/rust) client library.

Caution: messages with multiple tags [currently have the `tag` field repeated](https://fxbug.dev/42142433)
in the same object. Most JSON parsers consider this invalid by default, and will be resolved soon.

#### Timestamps

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.

#### Dropped logs

<!-- TODO(https://fxbug.dev/42143930) link to JSON schema when available -->

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

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

Note: version 1 of this format is [not yet stable](https://fxbug.dev/42142433) and taking a dependency
on it may require some small migrations in the future. These migrations will be transparent to users
of the [Rust](/src/lib/diagnostics/reader/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 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.

Note: Prefer `Log.ListenSafe` and `Log.DumpLogsSafe` to avoid channel overflow issues. Deletion of
the unsafe `fuchsia.logger.LogListener` API is [planned](https://fxbug.dev/42125650).

[ArchiveAccessor]: https://fuchsia.dev/reference/fidl/fuchsia.diagnostics#ArchiveAccessor
[ArchiveAccessor reference]: /src/diagnostics/docs/reference/access.md
[attribution]: /docs/concepts/components/diagnostics/logs/attribution.md
[BatchIterator]: https://fuchsia.dev/reference/fidl/fuchsia.diagnostics#BatchIterator
[ClientSelectorConfiguration]: https://fuchsia.dev/reference/fidl/fuchsia.diagnostics#ClientSelectorConfiguration
[DataType]: https://fuchsia.dev/reference/fidl/fuchsia.diagnostics#DataType
[Format]: https://fuchsia.dev/reference/fidl/fuchsia.diagnostics#Format
[FormattedContent]: https://fuchsia.dev/reference/fidl/fuchsia.diagnostics#FormattedContent
[monotonic clock]: /reference/syscalls/clock_get_monotonic.md
[StreamMode]: https://fuchsia.dev/reference/fidl/fuchsia.diagnostics#StreamMode
[StreamParameters]: https://fuchsia.dev/reference/fidl/fuchsia.diagnostics#StreamParameters