fuchsia.diagnostics

PROTOCOLS

Archive

Defined in fuchsia.diagnostics/reader.fidl

Outer protocol for interacting with the different diagnostics data sources.

ReadInspect

Creates a Reader for interacting with Inspect data. The resulting interface can be used to analyze Inspect hierarchy data scoped to the components specified by the static configurations of the Accessor pipeline that the client connects to, and the provided selectors vector argument.

  • request inspect_reader is a [fuchsia.diagnostics/Reader] that processes Reader requests, sitting on top of inspect data.
  • request selectors is a vector of [fuchsia.diagnostics/SelectorArgument] which provide additional filters to scope data with. If the vector is empty, all available results are returned. .
  • error a [fuchsia.diagnostics/AccessorError] value indicating that the provided selectors failed to verify.

Request

NameType
inspect_reader request<Reader>
selectors vector<SelectorArgument>

Response

NameType
result Archive_ReadInspect_Result

ReadLogs

Creates a Reader for interacting with structured Log data. The resulting interface can be used to analyze structured Log data scoped to the components specified by the static configurations of the Accessor pipeline that the client connects to, and the provided selectors vector argument.

  • request log_reader is a [fuchsia.diagnostics/Reader] that processes Reader requests, sitting on top of Log data.
  • request selectors is a vector of [fuchsia.diagnostics/SelectorArgument] which provide additional filters to scope data with. If the vector is empty, all available results are returned.
  • error a [fuchsia.diagnostics/AccessorError] value indicating that the provided selectors failed to verify.

Request

NameType
log_reader request<Reader>
selectors vector<SelectorArgument>

Response

NameType
result Archive_ReadLogs_Result

ReadLifecycleEvents

Creates a Reader for interacting with lifecycle event data. The resulting interface can be used to analyze lifecycle event data scoped to the components specified by the static configurations of the Accessor pipeline that the client connects to, and the provided selectors vector argument.

  • request lifecycle_reader is a [fuchsia.diagnostics/Reader] that processes Reader requests, sitting on top of lifecycle event data.
  • request selectors is a vector of [fuchsia.diagnostics/SelectorArgument] which provide additional filters to scope data with. If the vector is empty, all available results are returned.
  • error a [fuchsia.diagnostics/AccessorError] value indicating that the provided selectors failed to verify.

Request

NameType
lifecycle_reader request<Reader>
selectors vector<SelectorArgument>

Response

NameType
result Archive_ReadLifecycleEvents_Result

Reader

Defined in fuchsia.diagnostics/reader.fidl

A protocol to access data from a particular data source.

GetSnapshot

Filters the data hierarchies of components based on the statically provided allowlists and the selectors provided by the accessor request, formats these filtered data hierarchies according to the specified [fuchsia.diagnostics/FormatSettings] argument, then serves the resulting data hierarchies over a BatchIterator.

  • request format_settings the [fuchsia.diagnostics/FormatSettings] that specifies the format of data returned by the BatchIterator.
  • request result_iterator is a [fuchsia.diagnostics.BatchIterator] that processes client requests to fetch [fuchsia.diagnostics/FormattedContent] structs from the current snapshot.
  • error a [fuchsia.diagnostics/ReaderError] value indicating that there was an issue configuring the BatchIterator connection.

Request

NameType
format Format
result_iterator request<BatchIterator>

Response

NameType
result Reader_GetSnapshot_Result

ReadStream

Creates a Stream for polling a Reader data sources for new data. The resulting interface can be used retrieve the next batch of data matching which is within the ComponentSelector and TreeSelector scopes defined by the Archive and Reader protocols through which this stream was created, in addition to the static configurations that define the allowlist of data the reader has access to.

  • request format_settings the [fuchsia.diagnostics/FormatSettings] that specifies the format of data returned by the Batch during FormatBatch calls.
  • request stream_mode is a [fuchsia.diagnostics/StreamMode] that specifies how the streaming server provides streamed results.

Request

NameType
stream_mode StreamMode
format Format
formatted_stream request<Stream>

Stream

Defined in fuchsia.diagnostics/reader.fidl

Protocol offering an API for batch-retrieving all newly updated diagnostics data sincee the last call.

GetBatch

Retrieves the batch of data which has appeared since the last GetNext call and matches the configured ComponentSelector and TreeSelector scopes, in addition to the static configurations that define the allowlist of data the reader has access to.

The batch of data which has appeared since the last FormatNext call is formatted according to the FormatSettings provided to the ReadStream call which created the connection and then is served over a BatchIterator.

If no new data has appeared since the last FormatBatch call, the BatchIterator that starts serving over batch_iterator will just serve an empty vector, and then close.

  • request batch_iterator is a [fuchsia.diagnostics.BatchIterator] that processes client requests to fetch [fuchsia.diagnostics/FormattedContent] structs encoding newly available data from the data hierarchies the Reader that spawned this stream is sitting upon.
  • error a [fuchsia.diagnostics/ReaderError] value indicating that there was an issue configuring the Batch connection for the stream data.

Request

NameType
batch_iterator request<BatchIterator>

Response

NameType
result Stream_GetBatch_Result

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

Archive_ReadInspect_Response

generated

NameTypeDescriptionDefault

Archive_ReadLogs_Response

generated

NameTypeDescriptionDefault

Archive_ReadLifecycleEvents_Response

generated

NameTypeDescriptionDefault

Reader_GetSnapshot_Response

generated

NameTypeDescriptionDefault

Stream_GetBatch_Response

generated

NameTypeDescriptionDefault

BatchIterator_GetNext_Response

generated

NameTypeDescriptionDefault
batch vector<FormattedContent> 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 fail-states of the Accessor service.

NameValueDescription
INVALID_SELECTOR 1

ReaderError

Type: uint32

Defined in fuchsia.diagnostics/reader.fidl

Enum describing the potential fail-states of the Accessor service due to issues reading the data.

NameValueDescription
IO 1

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
REPLAY_ONLY 1

The first call to FormatBatch will serve the historical polling records of metrics configured to store state in buffers, then the server will close.

REPLAY_THEN_ONGOING 2

The first call to FormatBatch will serve the historical polling records of metrics configured to store state in buffers, then will close. Subsequent calls to FormatBatch will return newly polled records that were taken since the last FormatBatch call.

ONGOING_ONLY 3

The first call to FormatBatch will return newly polled records that were taken since the client connection was established. Subsequent calls to FormatBatch will return newly polled records that were taken since the last FormatBatch call.

TABLES

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

Archive_ReadInspect_Result

generated

NameTypeDescription
response Archive_ReadInspect_Response
err AccessorError

Archive_ReadLogs_Result

generated

NameTypeDescription
response Archive_ReadLogs_Response
err AccessorError

Archive_ReadLifecycleEvents_Result

generated

NameTypeDescription
response Archive_ReadLifecycleEvents_Response
err AccessorError

Reader_GetSnapshot_Result

generated

NameTypeDescription
response Reader_GetSnapshot_Response
err ReaderError

Stream_GetBatch_Result

generated

NameTypeDescription
response Stream_GetBatch_Response
err ReaderError

BatchIterator_GetNext_Result

generated

NameTypeDescription
response BatchIterator_GetNext_Response
err ReaderError

XUNIONS

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]

The Archive protocol parses the raw_selector into a structured [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
formatted_json_hierarchy fuchsia.mem/Buffer

A complete formatted data hierarchy encoded as json. Data hierarchies are the hierarchical representation of the structured diagnostics data on the system. The VMO will contain up to 1mb of diagnostics data, with dropped subtrees if the hierarchy is too large.

formatted_text_hierarchy fuchsia.mem/Buffer

A complete formatted data hierarchy encoded as text. The VMO will contain up to 1mb of diagnostics data, with dropped subtrees if the hierarchy is too large.

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