Google is committed to advancing racial equity for Black communities. See how.

fuchsia.diagnostics.stream

PROTOCOLS

Source

Defined in fuchsia.diagnostics.stream/source.fidl

A component with records for the Diagnostics system to retrieve.

To record diagnostics, a component allocates a VMO and begins writing records into the buffer, incrementing a header value after each write to inform readers how much of the buffer has been filled.

If any retrievers are connected, the Source sends them OnBufferInit events for each diagnostic buffer created.

When the buffer fills, the Source sends OnBufferDone to the retrievers, and will wait for all notified retrievers to reply with RetireBuffer when they have finished reading from the buffer.

When all readers of the buffer have finished, the Source may recycle the buffer by zeroing it and sending OnBufferInit again to connected retrievers.

Once a Source has sent OnBufferDone to a retriever, it is up to the Source to handle new records that are generated while the retriever drains the buffer. Double buffering is recommended to prevent excessive blocking, but this protocol does not mandate a specific approach to handling records generated while buffers are full.

OnBufferDone

Asks the connected retriever to finish working with buffer, usually because the Source does not intend to write further records.

Response

NameType
buffer zx/koid

OnBufferInit

Notifies the connected retriever of a new stream buffer. Should be emitted as soon as each buffer is (re)initialized.

latest should be read-only.

Response

NameType
latest handle<vmo>

RetireBuffer

Notifies the Source that the retriever is done reading from the buffer. If the Source wishes it should zero the buffer's contents and recycle it for future records. Buffers must be re-sent via OnBufferInit after they're zeroed.

Request

NameType
buffer zx/koid

STRUCTS

Argument

Defined in fuchsia.diagnostics.stream/record.fidl

A named key-value pair in the diagnostic record.

NameTypeDescriptionDefault
name string[256]

The name of the argument.

No default
value Value

The value of the argument.

No default

Record

Defined in fuchsia.diagnostics.stream/record.fidl

A record in the diagnostic stream.

NameTypeDescriptionDefault
timestamp zx/time

The monotonic time at which the record was generated.

No default
severity fuchsia.diagnostics/Severity

Severity of the record.

No default
arguments vector<Argument>[15]

The key-value pairs which make up this record.

No default

UNIONS

Value

Defined in fuchsia.diagnostics.stream/record.fidl

An argument value which can be one of several types.

NameTypeDescription
signed_int int64

A signed integral argument.

unsigned_int uint64

An unsigned integral argument.

floating float64

A double-precision floating-point argument.

text string[32768]

A UTF8 text argument.

CONSTANTS

NameValueTypeDescription
MAX_ARGS 15 uint32

Maximum number of arguments that can be encoded per record, as specified by the tracing format:

https://fuchsia.dev/fuchsia-src/development/tracing/trace-format#arguments

MAX_ARG_NAME_LENGTH 256 uint32

A small(ish) limit on the length of argument names is used because argument names are expected to be used repeatedly, many times.

MAX_TEXT_ARG_LENGTH 32768 uint32

The maximum string length which we can encode into the tracing format.