fuchsia.diagnostics

Added: 7

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 server_end: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

<EMPTY>

Response

NameType
payload BatchIterator_GetNext_Result

WaitForReady

Indiciates that the BatchIterator has been connected. If the BatchIterator hasn't been connected, this method will hang until it is.

Added: 18

Request

<EMPTY>

Response

NameType
payload BatchIterator_WaitForReady_Result

LogSettings

Defined in fuchsia.diagnostics/log_settings.fidl

This protocol allows clients to modify the logging behavior of components in the system.

RegisterInterest

Removed: 18 Deprecated: 12

Request

NameType
selectors vector<LogInterestSelector>:64

SetInterest

Requests a change in interest for the matched components.

Each component holds a set of requested interests.

When a new request on LogSettings#SetInterest is received, the sets for matched components receive the new minimum interest. If the interest is less than the previous minimum interest, then a SetInterest request is sent with the new minimum interest.

If a connection to LogSettings sends another SetInterest request, its previous interest request will be undone.

When the connection to LogSettings is finished, the interests are undone. Each matched component minimum interest is updated with the new minimum interest in the set.

Added: 12

Request

NameType
selectors vector<LogInterestSelector>:64

Response

<EMPTY>

STRUCTS

All

Defined in fuchsia.diagnostics/selector.fidl

<EMPTY>

BatchIterator_GetNext_Response resource

Defined in fuchsia.diagnostics/reader.fidl

FieldTypeDescriptionDefault
batch vector<FormattedContent>:64 No default

BatchIterator_WaitForReady_Response

Defined in fuchsia.diagnostics/reader.fidl

<EMPTY>

LogInterestSelector

Defined in fuchsia.diagnostics/log_settings.fidl

A specified Interest coupled with its designated target,

FieldTypeDescriptionDefault
selector ComponentSelector

Matches the components for which the interest will be requested.

 No default
interest Interest

The interest level that will be sent to components matching the selector.

 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 properties to match.

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

FieldTypeDescriptionDefault
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 strict

Type: uint8

Defined in fuchsia.diagnostics/reader.fidl

NameValueDescription
1

Complete inspect hierarchies on the system.
3

Log streams on the system.

Format strict

Type: uint32

Defined in fuchsia.diagnostics/format.fidl

Enum used to specify the output format for Reader results.

NameValueDescription
1

Dump read results per the Diagnostics Json Schema specifications.
2

Dump read results per the Iquery text specifications.
3

Dump read results per the Diagnostics CBOR Schema specifications.

Added: HEAD

ReaderError strict

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
1

Severity strict

Type: uint8

Defined in fuchsia.diagnostics/severity.fidl

The severity of a given record.

NameValueDescription
16

Trace records include detailed information about program execution.
32

Debug records include development-facing information about program execution.
48

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

Warning records include information about potentially problematic operations.
80

Error records include information about failed operations.
96

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

StreamMode strict

Type: uint8

Defined in fuchsia.diagnostics/reader.fidl

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

NameValueDescription
1

The stream will serve a snapshot of the diagnostics data at the time of connection, then end.
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.
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 monikers which identify components being selected for.

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

Component selectors also support a recursive wildcard, which will glob multiple "levels" of a component moniker. eg: core/* will match all component instances running under core/ and all descendants of it. Note that the wildcard does not select core itself. Clients that wish to choose a subtree including the root should pass two selectors, eg: core core/** The recursive wildcard is only allowed as the final segment of the selector.

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

OrdinalFieldTypeDescription
min_severity Severity

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

If not present, interpreted as Severity.INFO.

PerformanceConfiguration

Defined in fuchsia.diagnostics/reader.fidl

Parameters which configure a diagnostics stream's performance properties.

OrdinalFieldTypeDescription

1

 max_aggregate_content_size_bytes uint64

Maximum aggregate size of all formatted contents returned by the batch iterator for a diagnostics stream. If this value is set for a stream configured in subscribe mode, the stream will terminate when the max size has been reached. NOTE: OPTIONAL
batch_retrieval_timeout_seconds int64

Configuration specifying max number of seconds to wait for a single component to have its diagnostics data "pumped". This value can used for testing or if you know the component you are interested is in under heavy load. If not provided, then PER_COMPONENT_ASYNC_TIMEOUT_SECONDS as defined in https://fuchsia.googlesource.com/fuchsia/+/refs/heads/master/src/diagnostics/archivist/src/constants.rs will be used. NOTE: OPTIONAL

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:root/active_users:user_count

Subtree selection:
     realm1/realm2/echo:root/active_users

OrdinalFieldTypeDescription
component_selector ComponentSelector

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

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

A set of fuchsia.inspect.Tree names to filter with before applying hierarchy/property selectors.

Currently, leaving this field out is equivalent to TreeNames::all. This is a soft transition; eventually it will be equivalent to TreeNames::some(["root"]), where "root" is the default tree name. https://fxbug.dev/355732696 tracks this transition.

Added: 22

StreamParameters

Defined in fuchsia.diagnostics/reader.fidl

Parameters needed to configure a stream of diagnostics information.

OrdinalFieldTypeDescription
data_type DataType

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

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

A [fuchsia.diagnostics/Format] that specifies how to format the returned diagnostics data. NOTE: REQUIRED
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
batch_retrieval_timeout_seconds int64

Configuration specifying max number of seconds to wait for a single component to have its diagnostics data "pumped". This value can used for testing or if you know the component you are interested is in under heavy load. If not provided, then PER_COMPONENT_ASYNC_TIMEOUT_SECONDS as defined in https://fuchsia.googlesource.com/fuchsia/+/refs/heads/master/src/diagnostics/archivist/src/constants.rs will be used. NOTE: OPTIONAL
performance_configuration PerformanceConfiguration

Parameters which configure a diagnostics stream's performance properties. NOTE: OPTIONAL

UNIONS

BatchIterator_GetNext_Result strict resource

Defined in fuchsia.diagnostics/reader.fidl

OrdinalVariantTypeDescription
response BatchIterator_GetNext_Response
err ReaderError
framework_err internal

BatchIterator_WaitForReady_Result strict

Defined in fuchsia.diagnostics/reader.fidl

OrdinalVariantTypeDescription
response BatchIterator_WaitForReady_Response
framework_err internal

ClientSelectorConfiguration flexible

Defined in fuchsia.diagnostics/reader.fidl

OrdinalVariantTypeDescription
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 flexible resource

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.

OrdinalVariantTypeDescription
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.
cbor handle<vmo>

A diagnostics schema encoded as cbor. The VMO will contain up to 1mb of diagnostics data. The size will be in ZX_PROP_VMO_CONTENT_SIZE.

Added: HEAD

SelectorArgument flexible

Defined in fuchsia.diagnostics/reader.fidl

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

OrdinalVariantTypeDescription
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 interpreted in string_pattern mode, giving significance to special characters. See https://fuchsia.dev/fuchsia-src/reference/diagnostics/selectors for more information

StringSelector flexible

Defined in fuchsia.diagnostics/selector.fidl

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

OrdinalVariantTypeDescription
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: abc will match any string that starts with a and ends with c, with b in the middle.

In addition, the "*" literal is treated as a special sequence that may match multiple levels in a component selector only. See |ComponentSelector| for details.
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.

TreeNames flexible

Defined in fuchsia.diagnostics/selector.fidl

TreeNames are the set of names of fuchsia.inspect.Trees for a component that were parsed out of a selector. The hierarchy and property selector portions will only be applied to trees that match this set.

Added: 22
OrdinalVariantTypeDescription
some vector<string:100>

A specified subset of tree names.
all All

All of the available trees. Equivalent to listing all of the names of trees.

TreeSelector flexible

Defined in fuchsia.diagnostics/selector.fidl

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

OrdinalVariantTypeDescription
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_LOG_SELECTORS 64 uint8

Max number of LogInterestSelectors that can be specified via a listener.
MAX_MONIKER_SEGMENTS 25 uint16
MAX_STRING_SELECTOR_LENGTH 100 uint16