fuchsia.diagnostics

PROTOCOLS

Archive

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
result_stream request<BatchIterator>
stream_parameters StreamParameters

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 return no data.

  • 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

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.

NameTypeDescriptionDefault
component_selector ComponentSelector

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

No default
tree_selector TreeSelector

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

No default

ENUMS

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.

AccessorError

Type: uint32

Defined in fuchsia.diagnostics/reader.fidl

Enum describing the potential failure states of configuring diagnostics streams.

NameValueDescription
INVALID_SELECTOR 1

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
BACKLOG_BUFFER_EXCEEDED 2

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.

DataType

Type: uint8

Defined in fuchsia.diagnostics/reader.fidl

NameValueDescription
INSPECT 1

Complete inspect hierarchies on the system.

TABLES

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 selectors vector<SelectorArgument>

A vector of [fuchsia.diagnostics/SelectorArgument] which provide additional filters to scope data streams with. If the argument is not provided, or the vector is empty, all available results are returned.

ComponentSelector

Defined in fuchsia.diagnostics/selector.fidl

ComponentSelector encodes path to a component that is being selected for. The component_moniker specifies a pattern of component relative monikers which identify components being selected for.

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. TODO(4601): Investigate options for introduction of recursive wildcards.

TreeSelector

Defined in fuchsia.diagnostics/selector.fidl

TreeSelector represents a selection request on a nested structure where each nested node has properties that can be retrieved. The node_path specifies which nodes we search through, and the target_properties specify which properties to look for on the matched nodes.

Given that a Tree Selector has two sections, :, in the absence of an optional property_selector, we return the subtree of all nodes specified by the object node selector.

OrdinalNameTypeDescription
1 node_path vector<StringSelector>[100]

A vector of StringSelectors which serve as a pattern matcher for paths through a hierarchy of named nodes.

This field is required.

2 target_properties StringSelector

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

This field is optional. Without a property selector, the TreeSelector will select the entire subtree of all nodes selected by the node_path.

UNIONS

BatchIterator_GetNext_Result

Defined in fuchsia.diagnostics/reader.fidl

NameTypeDescription
response BatchIterator_GetNext_Response
err ReaderError

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.

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.

StringSelector

Defined in fuchsia.diagnostics/selector.fidl

StringSelector is an xunion 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.

CONSTANTS

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

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_STRING_SELECTOR_LENGTH 100 uint16
MAXIMUM_MONIKER_SEGMENTS 25 uint16
MAXIMUM_DATA_HIERARCHY_DEPTH 100 uint16