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

fuchsia.diagnostics

PROTOCOLS

ArchiveAccessor

Defined in fuchsia.diagnostics/reader.fidl

Outer protocol for interacting with the different diagnostics data sources.

StreamDiagnostics

Creates an iterator over diagnostics data on the system.

  • The iterator may be finite by streaming in SNAPSHOT mode, serving only the current state of diagnostics data on the system.
  • The iterator may be infinite by streaming in either SNAPSHOT_THEN_SUBSCRIBE or SUBSCRIBE mode; the prior first provides iteration over the current state of the sytem, and then both provide ongoing iteration over newly arriving diagnostics data.
  • request result stream a [fuchsia.diagnostics/BatchIterator] that diagnostic records are exposed to the client over.

    • epitaphs:
      • INVALID_ARGS: A required argument in the StreamParameters struct was missing.
      • WRONG_TYPE: A selector provided by the StreamParameters struct was incorrectly formatted.
  • request stream_parameters is a [fuchsia.diagnostics/StreamParameter] which specifies how to configure the stream.

Request

NameType
stream_parameters StreamParameters
result_stream request<BatchIterator>

BatchIterator

Defined in fuchsia.diagnostics/reader.fidl

Conceptually, a directory iterator, where each element in the iterator is a single complete file that can be concatenated with other results.

GetNext

Returns a vector of [fuchsia.diagnostics/FormattedContent] structs with a format dictated by the format_settings argument provided to the Reader protocol which spawned this BatchIterator.

An empty vector implies that the data hierarchy has been fully iterated, and subsequent GetNext calls will always return the empty vector.

When the BatchIterator is serving results via subscription model, calls to GetNext will hang until there is new data available, it will not return an empty vector.

  • returns a vector of FormattedContent structs. Clients connected to a Batch are expected to call GetNext() until an empty vector is returned, denoting that the entire data hierarchy has been read.
  • error a [fuchsia.diagnostics/ReaderError] value indicating that there was an issue reading the underlying data hierarchies or formatting those hierarchies to populate the batch. Note, these issues do not include a single component's data hierarchy failing to be read. The iterator is tolerant of individual component data sources failing to be read, whether that failure is a timeout or a malformed binary file. In the event that a GetNext call fails, that subset of the data hierarchy results is dropped, but future calls to GetNext will provide new subsets of FormattedDataHierarchies.

Request

NameType

Response

NameType
result BatchIterator_GetNext_Result

STRUCTS

BatchIterator_GetNext_Response

Defined in fuchsia.diagnostics/reader.fidl

NameTypeDescriptionDefault
batch vector<FormattedContent>[64] No default

PropertySelector

Defined in fuchsia.diagnostics/selector.fidl

A selector defining a set of nodes to match, and on those matched nodes a set of named propperties to match.

NameTypeDescriptionDefault
node_path vector<StringSelector>[100]

A vector of StringSelectors which serve as a pattern matcher for paths through a hierarchy of named nodes. Each entry in the vector is a selector for a single named node in a data hierarchy. The vector of selectors for named nodes, then, defines a selector on paths through the data hierarchy.

Node paths support wildcarding, which will glob a single level of a node hierarchy. eg: root/a/b//d will match all nodes named d which are below some child of node b. root/a/b/c will match all nodes below b which start with the character "c".

No default
target_properties StringSelector

A StringSelector which serves as a pattern matcher for string-named properties on a node in a data hierarchy.

target_properties supports wildcarding, which will match against all properties on any node matched by node_path.

No default

SubtreeSelector

Defined in fuchsia.diagnostics/selector.fidl

A selector defining a set of nodes to match, for which the entire subtree including those nodes are selected.

NameTypeDescriptionDefault
node_path vector<StringSelector>[100]

A vector of StringSelectors which serve as a pattern matcher for paths through a hierarchy of named nodes. Each entry in the vector is a selector for a single named node in a data hierarchy. The vector of selectors for named nodes, then, defines a selector on paths through the data hierarchy.

Node paths support wildcarding, which will glob a single level of a node hierarchy. eg: root/a/b//d will match all nodes named d which are below some child of node b. root/a/b/c will match all nodes below b which start with the character "c".

No default

ENUMS

DataType

Type: uint8

Defined in fuchsia.diagnostics/reader.fidl

NameValueDescription
INSPECT 1

Complete inspect hierarchies on the system.

LIFECYCLE 2

Start|Stop|Running|DiagnosticsReady events on the system.

Format

Type: uint32

Defined in fuchsia.diagnostics/format.fidl

Enum used to specify the output format for Reader results.

NameValueDescription
JSON 1

Dump read results per the Diagnostics Json Schema specifications.

TEXT 2

Dump read results per the Iquery text specifications.

ReaderError

Type: uint32

Defined in fuchsia.diagnostics/reader.fidl

Enum describing the potential failure states of the streaming protocol when serving results to the client over the result iterator.

NameValueDescription
IO 1

Severity

Type: uint8

Defined in fuchsia.diagnostics/severity.fidl

The severity of a given record.

NameValueDescription
TRACE 16

Trace records include detailed information about program execution.

DEBUG 32

Debug records include development-facing information about program execution.

INFO 48

Info records include general information about program execution. (default)

WARN 64

Warning records include information about potentially problematic operations.

ERROR 80

Error records include information about failed operations.

FATAL 96

Fatal records convey information about operations which cause a program's termination.

StreamMode

Type: uint8

Defined in fuchsia.diagnostics/reader.fidl

Enum specifying the modes by which a user can connect to and stream diagnostics metrics.

NameValueDescription
SNAPSHOT 1

The stream will serve a snapshot of the diagnostics data at the time of connection, then end.

SNAPSHOT_THEN_SUBSCRIBE 2

The stream will serve a snapshot of the diagnostics data at the time of connection, then subsequent calls to the stream will hang until new diagnostics data is available.

SUBSCRIBE 3

Calls to the stream will hang until new diagnostics data is available. Between calls to the stream, newly arrived data is buffered.

TABLES

ComponentSelector

Defined in fuchsia.diagnostics/selector.fidl

Specifies a pattern of component relative monikers which identify components being selected for.

Component selectors support wildcarding, which will glob a single "level" of a component moniker. eg: hub/*/echo.cmx will match all echo.cmx instances running only in realms directly under hub, but none nested further.

OrdinalNameTypeDescription
1 moniker_segments vector<StringSelector>[25]

Vector encoding the a pattern for monikers of components being selected for. These monikers are child-monikers relative to a "root" hierarchy that the archivist is aware of.

There must be at least one StringSelector provided, which specifies the component names that are matched by the current selector.

Interest

Defined in fuchsia.diagnostics/interest.fidl

Interest expresses the scope of clients' desired diagnostics data, e.g. for filtering messages or controlling their generation.

OrdinalNameTypeDescription
1 min_severity Severity

Minimum desired severity. Components should include records at or above this severity.

The default is INFO.

Selector

Defined in fuchsia.diagnostics/selector.fidl

Structured selector containing all required information for pattern-matching onto string-named properties owned by nodes in a data hierarchy, where data hierarchies belong to specific components.

These selectors are represented in text form as three segments, colon delimited, specifying: <component_moniker>:<node_selector>:<property_selector> Examples: Property selection: realm1/realm2/echo.cmx:root/active_users:user_count

Subtree selection:
     realm1/realm2/echo.cmx:root/active_users
OrdinalNameTypeDescription
1 component_selector ComponentSelector

The selector defining a pattern of component monikers to match against.

2 tree_selector TreeSelector

The selector defining data hierarchy properties to match against within the data hierarchies owned by components matched by component_selector.

StreamParameters

Defined in fuchsia.diagnostics/reader.fidl

Parameters needed to configure a stream of diagnostics information.

OrdinalNameTypeDescription
1 data_type DataType

A [fuchsia.diagnostics/DataType] that specifies the diagnostics data type to stream to the client. NOTE: REQUIRED

2 stream_mode StreamMode

A [fuchsia.diagnostics/StreamMode] that specifies how the streaming server provides streamed results. NOTE: REQUIRED

3 format Format

A [fuchsia.diagnostics/Format] that specifies how to format the returned diagnostics data. NOTE: REQUIRED

4 client_selector_configuration ClientSelectorConfiguration

Configuration specifying what results the client wants returned from their connection. The client can request a specific subset of data using a vector of provided selectors, or can specify that they want all available data. NOTE: REQUIRED

UNIONS

BatchIterator_GetNext_Result

Defined in fuchsia.diagnostics/reader.fidl

NameTypeDescription
response BatchIterator_GetNext_Response
err ReaderError

ClientSelectorConfiguration

Defined in fuchsia.diagnostics/reader.fidl

NameTypeDescription
selectors vector<SelectorArgument>

A vector of [fuchsia.diagnostics/SelectorArgument] which provide additional filters to scope data streams with. An empty vector is considered a misconfiguration and will result in an epitaph signaling incorrect parameters.

select_all bool

select_all must be true if set, and specifies that the client wants to retrieve all data that their connection is able to expose.

FormattedContent

Defined in fuchsia.diagnostics/reader.fidl

A fidl union containing a complete hierarchy of structured diagnostics data, such that the content can be parsed into a file by itself.

NameTypeDescription
json fuchsia.mem/Buffer

A diagnostics schema encoded as json. The VMO will contain up to 1mb of diagnostics data.

text fuchsia.mem/Buffer

A diagnostics schema encoded as text. The VMO will contain up to 1mb of diagnostics data.

SelectorArgument

Defined in fuchsia.diagnostics/reader.fidl

Argument used for Archive selectors, can be either the pre-parsed fidl struct or string representation.

NameTypeDescription
structured_selector Selector

A Selector defining a pattern-matcher which selects for components within a hierarchy and properties in a data hierarchy namespaced by component.

raw_selector string[1024]

A raw string representing a [fuchsia.diagnostics/Selector]. The Selector defines a pattern-matcher which selects for components within a hierarchy and properties in a data hierarchy namespaced by component. NOTE: All StringSelectors parsed from the raw_selector will be interperetted in string_pattern mode, giving significance to special characters. TODO(4601): Link to in-tree documentation for raw selector strings.

StringSelector

Defined in fuchsia.diagnostics/selector.fidl

StringSelector is an union defining different ways to describe a pattern to match strings against.

NameTypeDescription
string_pattern string[100]

This is a provided string that defines a pattern to match against. The parser treats asterisks (*), colons (:) and backslashes () as special characters.

If you wish to match against literal asterisks (*), they must be escaped. If you wish to match against literal backslashes (), they must be escaped. If you wish to match against literal colons (:), they must be escaped.

eg: abc will match any string with the exact name "abc". eg: a* will match any string with the exact name "a*". eg: a\* will match any that starts with exactly "a". eg: a* will match any string that starts with "a". eg: ab will match any string that starts with a and ends with b. eg: ab*c will match any string that starts with a and ends with c, with b in the middle.

exact_match string[100]

This is a provided string that defines an exact string to match against. No characters are treated as special, or carry special syntax.

TreeSelector

Defined in fuchsia.diagnostics/selector.fidl

TreeSelector represents a selection request on a hierarchy of named nodes, with named properties on those nodes.

NameTypeDescription
subtree_selector SubtreeSelector

A selector defining a set of nodes to match, for which the entire subtree including those nodes are selected.

property_selector PropertySelector

A selector defining a set of nodes to match, and on those matched nodes a set of named propperties to match.

CONSTANTS

NameValueTypeDescription
MAXIMUM_ENTRIES_PER_BATCH 64 uint16

The size 64 was chosen because entries in batches are handles to VMOs and there is a limit of 64 handles per fidl message.

MAXIMUM_RAW_SELECTOR_LENGTH 1024 uint16

The size bound of 1024 is a reasonably low size restriction that meets most canonical selectors we've ecountered.

MAX_DATA_HIERARCHY_DEPTH 100 uint16
MAX_MONIKER_SEGMENTS 25 uint16
MAX_STRING_SELECTOR_LENGTH 100 uint16