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
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
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
| Name | Type |
|---|---|
buffer |
zx/koid
|
STRUCTS
Argument
Defined in fuchsia.diagnostics.stream/record.fidl
A named key-value pair in the diagnostic record.
| Field | Type | Description | Default |
|---|---|---|---|
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.
| Field | Type | Description | Default |
|---|---|---|---|
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 flexible
Defined in fuchsia.diagnostics.stream/record.fidl
An argument value which can be one of several types.
| Ordinal | |||
|---|---|---|---|
| Variant | Type | Description | |
| 1 | signed_int |
int64
|
A signed integral argument. |
| 2 | unsigned_int |
uint64
|
An unsigned integral argument. |
| 3 | floating |
float64
|
A double-precision floating-point argument. |
| 4 | text |
string[32768]
|
A UTF8 text argument. |
CONSTANTS
| Name | Value | Type | Description |
|---|---|---|---|
| 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. |