Google Git
Sign in
fuchsia / reference-docs / main / . / f10n / sdk / fidl / fuchsia.diagnostics / README.md
blob: f5ac65cbb0722ee98b8695355d34eb4694586262 [file] [log] [blame] [view]
<link rel="stylesheet" href="../style.css" />
[TOC]
# fuchsia.diagnostics
<div class="fidl-version-div"><span class="fidl-attribute fidl-version">Added: 7</span></div>
## **PROTOCOLS**
## ArchiveAccessor {#ArchiveAccessor}
*Defined in [fuchsia.diagnostics/reader.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/reader.fidl;l=151)*
<p>Outer protocol for interacting with the different diagnostics data sources.</p>
### StreamDiagnostics {#ArchiveAccessor.StreamDiagnostics}
<p>Creates an iterator over diagnostics data on the system.</p>
<ul>
<li>The iterator may be finite by streaming in SNAPSHOT mode, serving only the
current state of diagnostics data on the system.</li>
<li>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.</li>
</ul>
<ul>
<li>
<p>request <code>result stream</code> a [fuchsia.diagnostics/BatchIterator] that diagnostic
records are exposed to the client over.</p>
<ul>
<li>epitaphs:
<ul>
<li>INVALID_ARGS: A required argument in the StreamParameters struct was missing.</li>
<li>WRONG_TYPE: A selector provided by the StreamParameters struct was incorrectly
formatted.</li>
</ul>
</li>
</ul>
</li>
<li>
<p>request <code>stream_parameters</code> is a [fuchsia.diagnostics/StreamParameter] which
specifies how to configure the stream.</p>
</li>
</ul>
#### Request {#ArchiveAccessor.StreamDiagnostics_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>stream_parameters</code></td>
<td>
<code><a class='link' href='#StreamParameters'>StreamParameters</a></code>
</td>
</tr>
<tr>
<td><code>result_stream</code></td>
<td>
<code>server_end&lt;<a class='link' href='#BatchIterator'>BatchIterator</a>&gt;</code>
</td>
</tr>
</table>
## BatchIterator {#BatchIterator}
*Defined in [fuchsia.diagnostics/reader.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/reader.fidl;l=177)*
<p>Conceptually, a directory iterator, where each element in the iterator is a single
complete file that can be concatenated with other results.</p>
### GetNext {#BatchIterator.GetNext}
<p>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.</p>
<p>An empty vector implies that the data hierarchy has been fully iterated, and subsequent
GetNext calls will always return the empty vector.</p>
<p>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.</p>
<ul>
<li>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.</li>
</ul>
<ul>
<li>error a [fuchsia.diagnostics/ReaderError]
value indicating that there was an issue reading the underlying data hierarchies
or formatting those hierarchies to populate the <code>batch</code>. 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.</li>
</ul>
#### Request {#BatchIterator.GetNext_Request}
&lt;EMPTY&gt;
#### Response {#BatchIterator.GetNext_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#BatchIterator_GetNext_Result'>BatchIterator_GetNext_Result</a></code>
</td>
</tr>
</table>
## LogSettings {#LogSettings}
*Defined in [fuchsia.diagnostics/log_settings.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/log_settings.fidl;l=22)*
<p>This protocol allows clients to modify the logging behavior of components
in the system.</p>
### RegisterInterest {#LogSettings.RegisterInterest}
<p>Requests a change in interest for the matched components.</p>
<p>Each component holds a set of requested interests.</p>
<p>When a new request on LogSettings#RegisterInterest is received,
the sets for matched components receive the new minimum interest.
If the interest is less than the previous minimum interest, then a
<code>RegisterInterest</code> request is sent with the new minimum interest.</p>
<p>If a connection to <code>LogSettings</code> sends another <code>RegisterInterest</code>
request, its previous interest request will be undone.</p>
<p>When the connection to <code>LogSettings</code> is finished, the interests are
undone. Each matched component minimum interest is updated with the
new minimum interest in the set.</p>
#### Request {#LogSettings.RegisterInterest_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>selectors</code></td>
<td>
<code>vector&lt;<a class='link' href='#LogInterestSelector'>LogInterestSelector</a>&gt;[64]</code>
</td>
</tr>
</table>
## **STRUCTS**
### BatchIterator_GetNext_Response [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#BatchIterator_GetNext_Response data-text="BatchIterator_GetNext_Response"}
*Defined in [fuchsia.diagnostics/reader.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/reader.fidl;l=202)*
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="BatchIterator_GetNext_Response.batch">
<td><code>batch</code></td>
<td>
<code>vector&lt;<a class='link' href='#FormattedContent'>FormattedContent</a>&gt;[64]</code>
</td>
<td></td>
<td>No default</td>
</tr>
</table>
### LogInterestSelector {#LogInterestSelector data-text="LogInterestSelector"}
*Defined in [fuchsia.diagnostics/log_settings.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/log_settings.fidl;l=11)*
<p>A specified Interest coupled with its designated target,</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="LogInterestSelector.selector">
<td><code>selector</code></td>
<td>
<code><a class='link' href='#ComponentSelector'>ComponentSelector</a></code>
</td>
<td><p>Matches the components for which the interest will be requested.</p>
</td>
<td>No default</td>
</tr>
<tr id="LogInterestSelector.interest">
<td><code>interest</code></td>
<td>
<code><a class='link' href='#Interest'>Interest</a></code>
</td>
<td><p>The interest level that will be sent to components matching the selector.</p>
</td>
<td>No default</td>
</tr>
</table>
### PropertySelector {#PropertySelector data-text="PropertySelector"}
*Defined in [fuchsia.diagnostics/selector.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/selector.fidl;l=96)*
<p>A selector defining a set of nodes to match, and on those matched nodes a set of named
properties to match.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="PropertySelector.node_path">
<td><code>node_path</code></td>
<td>
<code>vector&lt;<a class='link' href='#StringSelector'>StringSelector</a>&gt;[100]</code>
</td>
<td><p>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.</p>
<p>Node paths support wildcarding, which will glob a single level of a
node hierarchy. eg:
root/a/b/<em>/d
will match all nodes named d which are below some child of node b.
root/a/b/c</em>
will match all nodes below b which start with the character &quot;c&quot;.</p>
</td>
<td>No default</td>
</tr>
<tr id="PropertySelector.target_properties">
<td><code>target_properties</code></td>
<td>
<code><a class='link' href='#StringSelector'>StringSelector</a></code>
</td>
<td><p>A StringSelector which serves as a pattern matcher for
string-named properties on a node in a data hierarchy.</p>
<p>target_properties supports wildcarding, which will match against all properties
on any node matched by node_path.</p>
</td>
<td>No default</td>
</tr>
</table>
### SubtreeSelector {#SubtreeSelector data-text="SubtreeSelector"}
*Defined in [fuchsia.diagnostics/selector.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/selector.fidl;l=78)*
<p>A selector defining a set of nodes to match, for which the entire subtree including
those nodes are selected.</p>
<table>
<tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
<tr id="SubtreeSelector.node_path">
<td><code>node_path</code></td>
<td>
<code>vector&lt;<a class='link' href='#StringSelector'>StringSelector</a>&gt;[100]</code>
</td>
<td><p>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.</p>
<p>Node paths support wildcarding, which will glob a single level of a
node hierarchy. eg:
root/a/b/<em>/d
will match all nodes named d which are below some child of node b.
root/a/b/c</em>
will match all nodes below b which start with the character &quot;c&quot;.</p>
</td>
<td>No default</td>
</tr>
</table>
## **ENUMS**
### DataType [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#DataType data-text="DataType"}
Type: <code>uint8</code>
*Defined in [fuchsia.diagnostics/reader.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/reader.fidl;l=70)*
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="DataType.INSPECT">
<td><h3 id="DataType.INSPECT" class="add-link hide-from-toc">INSPECT</h3></td>
<td><code>1</code></td>
<td><p>Complete inspect hierarchies on the system.</p>
</td>
</tr>
<tr id="DataType.LOGS">
<td><h3 id="DataType.LOGS" class="add-link hide-from-toc">LOGS</h3></td>
<td><code>3</code></td>
<td><p>Log streams on the system.</p>
</td>
</tr>
</table>
### Format [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#Format data-text="Format"}
Type: <code>uint32</code>
*Defined in [fuchsia.diagnostics/format.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/format.fidl;l=9)*
<p>Enum used to specify the output format for
Reader results.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="Format.JSON">
<td><h3 id="Format.JSON" class="add-link hide-from-toc">JSON</h3></td>
<td><code>1</code></td>
<td><p>Dump read results per the Diagnostics Json
Schema specifications.</p>
</td>
</tr>
<tr id="Format.TEXT">
<td><h3 id="Format.TEXT" class="add-link hide-from-toc">TEXT</h3></td>
<td><code>2</code></td>
<td><p>Dump read results per the Iquery text specifications.</p>
</td>
</tr>
</table>
### ReaderError [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#ReaderError data-text="ReaderError"}
Type: <code>uint32</code>
*Defined in [fuchsia.diagnostics/reader.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/reader.fidl;l=19)*
<p>Enum describing the potential failure states of the streaming protocol when serving results
to the client over the result iterator.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="ReaderError.IO">
<td><h3 id="ReaderError.IO" class="add-link hide-from-toc">IO</h3></td>
<td><code>1</code></td>
<td></td>
</tr>
</table>
### Severity [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#Severity data-text="Severity"}
Type: <code>uint8</code>
*Defined in [fuchsia.diagnostics/severity.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/severity.fidl;l=16)*
<p>The severity of a given record.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="Severity.TRACE">
<td><h3 id="Severity.TRACE" class="add-link hide-from-toc">TRACE</h3></td>
<td><code>16</code></td>
<td><p>Trace records include detailed information about program execution.</p>
</td>
</tr>
<tr id="Severity.DEBUG">
<td><h3 id="Severity.DEBUG" class="add-link hide-from-toc">DEBUG</h3></td>
<td><code>32</code></td>
<td><p>Debug records include development-facing information about program execution.</p>
</td>
</tr>
<tr id="Severity.INFO">
<td><h3 id="Severity.INFO" class="add-link hide-from-toc">INFO</h3></td>
<td><code>48</code></td>
<td><p>Info records include general information about program execution. (default)</p>
</td>
</tr>
<tr id="Severity.WARN">
<td><h3 id="Severity.WARN" class="add-link hide-from-toc">WARN</h3></td>
<td><code>64</code></td>
<td><p>Warning records include information about potentially problematic operations.</p>
</td>
</tr>
<tr id="Severity.ERROR">
<td><h3 id="Severity.ERROR" class="add-link hide-from-toc">ERROR</h3></td>
<td><code>80</code></td>
<td><p>Error records include information about failed operations.</p>
</td>
</tr>
<tr id="Severity.FATAL">
<td><h3 id="Severity.FATAL" class="add-link hide-from-toc">FATAL</h3></td>
<td><code>96</code></td>
<td><p>Fatal records convey information about operations which cause a program's termination.</p>
</td>
</tr>
</table>
### StreamMode [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#StreamMode data-text="StreamMode"}
Type: <code>uint8</code>
*Defined in [fuchsia.diagnostics/reader.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/reader.fidl;l=55)*
<p>Enum specifying the modes by which a user can connect to and stream diagnostics metrics.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="StreamMode.SNAPSHOT">
<td><h3 id="StreamMode.SNAPSHOT" class="add-link hide-from-toc">SNAPSHOT</h3></td>
<td><code>1</code></td>
<td><p>The stream will serve a snapshot of the diagnostics data at the time of
connection, then end.</p>
</td>
</tr>
<tr id="StreamMode.SNAPSHOT_THEN_SUBSCRIBE">
<td><h3 id="StreamMode.SNAPSHOT_THEN_SUBSCRIBE" class="add-link hide-from-toc">SNAPSHOT_THEN_SUBSCRIBE</h3></td>
<td><code>2</code></td>
<td><p>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.</p>
</td>
</tr>
<tr id="StreamMode.SUBSCRIBE">
<td><h3 id="StreamMode.SUBSCRIBE" class="add-link hide-from-toc">SUBSCRIBE</h3></td>
<td><code>3</code></td>
<td><p>Calls to the stream will hang until new diagnostics data is available. Between calls to
the stream, newly arrived data is buffered.</p>
</td>
</tr>
</table>
## **TABLES**
### ComponentSelector {#ComponentSelector data-text="ComponentSelector"}
*Defined in [fuchsia.diagnostics/selector.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/selector.fidl;l=65)*
<p>Specifies a pattern of component relative monikers which
identify components being selected for.</p>
<p>Component selectors support wildcarding, which will glob a single &quot;level&quot; of a
component moniker. eg:
core/*/echo
will match all echo instances running only in realms directly under core, but none
nested further.</p>
<p>Component selectors also support a recursive wildcard, which will glob multiple
&quot;levels&quot; 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.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="ComponentSelector.moniker_segments">
<td><h3 id="ComponentSelector.moniker_segments" class="add-link hide-from-toc">1</h3></td>
<td><code>moniker_segments</code></td>
<td>
<code>vector&lt;<a class='link' href='#StringSelector'>StringSelector</a>&gt;[25]</code>
</td>
<td><p>Vector encoding the a pattern for monikers of components being selected for.
These monikers are child-monikers relative to a &quot;root&quot; hierarchy that the archivist
is aware of.</p>
<p>There must be at least one StringSelector provided, which
specifies the component names that are matched by
the current selector.</p>
</td>
</tr>
</table>
### Interest {#Interest data-text="Interest"}
*Defined in [fuchsia.diagnostics/interest.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/interest.fidl;l=8)*
<p>Interest expresses the scope of clients' desired diagnostics data,
e.g. for filtering messages or controlling their generation.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="Interest.min_severity">
<td><h3 id="Interest.min_severity" class="add-link hide-from-toc">1</h3></td>
<td><code>min_severity</code></td>
<td>
<code><a class='link' href='#Severity'>Severity</a></code>
</td>
<td><p>Minimum desired severity. Components should include records at or
above this severity.</p>
<p>If not present, interpreted as Severity.INFO.</p>
</td>
</tr>
</table>
### PerformanceConfiguration {#PerformanceConfiguration data-text="PerformanceConfiguration"}
*Defined in [fuchsia.diagnostics/reader.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/reader.fidl;l=92)*
<p>Parameters which configure a diagnostics stream's performance properties.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="PerformanceConfiguration.max_aggregate_content_size_bytes">
<td><h3 id="PerformanceConfiguration.max_aggregate_content_size_bytes" class="add-link hide-from-toc">1</h3></td>
<td><code>max_aggregate_content_size_bytes</code></td>
<td>
<code>uint64</code>
</td>
<td><p>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</p>
</td>
</tr>
<tr id="PerformanceConfiguration.batch_retrieval_timeout_seconds">
<td><h3 id="PerformanceConfiguration.batch_retrieval_timeout_seconds" class="add-link hide-from-toc">2</h3></td>
<td><code>batch_retrieval_timeout_seconds</code></td>
<td>
<code>int64</code>
</td>
<td><p>Configuration specifying max number of seconds to wait for a single
component to have its diagnostics data &quot;pumped&quot;. 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</p>
</td>
</tr>
</table>
### Selector {#Selector data-text="Selector"}
*Defined in [fuchsia.diagnostics/selector.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/selector.fidl;l=144)*
<p>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.</p>
<p>These selectors are represented in text form as three segments, colon delimited,
specifying:
&lt;component_moniker&gt;:&lt;node_selector&gt;:&lt;property_selector&gt;
Examples:
Property selection:
realm1/realm2/echo.cmx:root/active_users:user_count</p>
<pre><code>Subtree selection:
realm1/realm2/echo.cmx:root/active_users
</code></pre>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="Selector.component_selector">
<td><h3 id="Selector.component_selector" class="add-link hide-from-toc">1</h3></td>
<td><code>component_selector</code></td>
<td>
<code><a class='link' href='#ComponentSelector'>ComponentSelector</a></code>
</td>
<td><p>The selector defining a pattern of component monikers to match
against.</p>
</td>
</tr>
<tr id="Selector.tree_selector">
<td><h3 id="Selector.tree_selector" class="add-link hide-from-toc">2</h3></td>
<td><code>tree_selector</code></td>
<td>
<code><a class='link' href='#TreeSelector'>TreeSelector</a></code>
</td>
<td><p>The selector defining data hierarchy properties to match against
within the data hierarchies owned by components matched by
<code>component_selector</code>.</p>
</td>
</tr>
</table>
### StreamParameters {#StreamParameters data-text="StreamParameters"}
*Defined in [fuchsia.diagnostics/reader.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/reader.fidl;l=112)*
<p>Parameters needed to configure a stream of diagnostics information.</p>
<table>
<tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
<tr id="StreamParameters.data_type">
<td><h3 id="StreamParameters.data_type" class="add-link hide-from-toc">1</h3></td>
<td><code>data_type</code></td>
<td>
<code><a class='link' href='#DataType'>DataType</a></code>
</td>
<td><p>A [fuchsia.diagnostics/DataType] that specifies the diagnostics data type
to stream to the client.
NOTE: REQUIRED</p>
</td>
</tr>
<tr id="StreamParameters.stream_mode">
<td><h3 id="StreamParameters.stream_mode" class="add-link hide-from-toc">2</h3></td>
<td><code>stream_mode</code></td>
<td>
<code><a class='link' href='#StreamMode'>StreamMode</a></code>
</td>
<td><p>A [fuchsia.diagnostics/StreamMode] that specifies how the
streaming server provides streamed results.
NOTE: REQUIRED</p>
</td>
</tr>
<tr id="StreamParameters.format">
<td><h3 id="StreamParameters.format" class="add-link hide-from-toc">3</h3></td>
<td><code>format</code></td>
<td>
<code><a class='link' href='#Format'>Format</a></code>
</td>
<td><p>A [fuchsia.diagnostics/Format] that specifies how to format the returned
diagnostics data.
NOTE: REQUIRED</p>
</td>
</tr>
<tr id="StreamParameters.client_selector_configuration">
<td><h3 id="StreamParameters.client_selector_configuration" class="add-link hide-from-toc">4</h3></td>
<td><code>client_selector_configuration</code></td>
<td>
<code><a class='link' href='#ClientSelectorConfiguration'>ClientSelectorConfiguration</a></code>
</td>
<td><p>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</p>
</td>
</tr>
<tr id="StreamParameters.batch_retrieval_timeout_seconds">
<td><h3 id="StreamParameters.batch_retrieval_timeout_seconds" class="add-link hide-from-toc">5</h3></td>
<td><code>batch_retrieval_timeout_seconds</code></td>
<td>
<code>int64</code>
</td>
<td><p>Configuration specifying max number of seconds to wait for a single
component to have its diagnostics data &quot;pumped&quot;. 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</p>
</td>
</tr>
<tr id="StreamParameters.performance_configuration">
<td><h3 id="StreamParameters.performance_configuration" class="add-link hide-from-toc">6</h3></td>
<td><code>performance_configuration</code></td>
<td>
<code><a class='link' href='#PerformanceConfiguration'>PerformanceConfiguration</a></code>
</td>
<td><p>Parameters which configure a diagnostics stream's performance properties.
NOTE: OPTIONAL</p>
</td>
</tr>
</table>
## **UNIONS**
### BatchIterator_GetNext_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#BatchIterator_GetNext_Result data-text="BatchIterator_GetNext_Result"}
*Defined in [fuchsia.diagnostics/reader.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/reader.fidl;l=202)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="BatchIterator_GetNext_Result.response">
<td><h3 id="BatchIterator_GetNext_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#BatchIterator_GetNext_Response'>BatchIterator_GetNext_Response</a></code>
</td>
<td></td>
</tr>
<tr id="BatchIterator_GetNext_Result.err">
<td><h3 id="BatchIterator_GetNext_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#ReaderError'>ReaderError</a></code>
</td>
<td></td>
</tr>
</table>
### ClientSelectorConfiguration [flexible](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#ClientSelectorConfiguration data-text="ClientSelectorConfiguration"}
*Defined in [fuchsia.diagnostics/reader.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/reader.fidl;l=80)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="ClientSelectorConfiguration.selectors">
<td><h3 id="ClientSelectorConfiguration.selectors" class="add-link hide-from-toc">1</h3></td>
<td><code>selectors</code></td>
<td>
<code>vector&lt;<a class='link' href='#SelectorArgument'>SelectorArgument</a>&gt;</code>
</td>
<td><p>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.</p>
</td>
</tr>
<tr id="ClientSelectorConfiguration.select_all">
<td><h3 id="ClientSelectorConfiguration.select_all" class="add-link hide-from-toc">2</h3></td>
<td><code>select_all</code></td>
<td>
<code>bool</code>
</td>
<td><p>select_all must be true if set, and specifies that the client wants to retrieve
all data that their connection is able to expose.</p>
</td>
</tr>
</table>
### FormattedContent [flexible](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} [resource](/fuchsia-src/reference/fidl/language/language.md#value-vs-resource){:.fidl-attribute} {#FormattedContent data-text="FormattedContent"}
*Defined in [fuchsia.diagnostics/reader.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/reader.fidl;l=43)*
<p>A fidl union containing a complete hierarchy of structured diagnostics
data, such that the content can be parsed into a file by itself.</p>
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="FormattedContent.json">
<td><h3 id="FormattedContent.json" class="add-link hide-from-toc">1</h3></td>
<td><code>json</code></td>
<td>
<code><a class='link' href='../fuchsia.mem/'>fuchsia.mem</a>/<a class='link' href='../fuchsia.mem/#Buffer'>Buffer</a></code>
</td>
<td><p>A diagnostics schema encoded as json.
The VMO will contain up to 1mb of diagnostics data.</p>
</td>
</tr>
<tr id="FormattedContent.text">
<td><h3 id="FormattedContent.text" class="add-link hide-from-toc">2</h3></td>
<td><code>text</code></td>
<td>
<code><a class='link' href='../fuchsia.mem/'>fuchsia.mem</a>/<a class='link' href='../fuchsia.mem/#Buffer'>Buffer</a></code>
</td>
<td><p>A diagnostics schema encoded as text.
The VMO will contain up to 1mb of diagnostics data.</p>
</td>
</tr>
</table>
### SelectorArgument [flexible](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#SelectorArgument data-text="SelectorArgument"}
*Defined in [fuchsia.diagnostics/reader.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/reader.fidl;l=27)*
<p>Argument used for Archive selectors, can be either the pre-parsed
fidl struct or string representation.</p>
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="SelectorArgument.structured_selector">
<td><h3 id="SelectorArgument.structured_selector" class="add-link hide-from-toc">1</h3></td>
<td><code>structured_selector</code></td>
<td>
<code><a class='link' href='#Selector'>Selector</a></code>
</td>
<td><p>A Selector defining a pattern-matcher which selects for components within a hierarchy
and properties in a data hierarchy namespaced by component.</p>
</td>
</tr>
<tr id="SelectorArgument.raw_selector">
<td><h3 id="SelectorArgument.raw_selector" class="add-link hide-from-toc">2</h3></td>
<td><code>raw_selector</code></td>
<td>
<code>string[1024]</code>
</td>
<td><p>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</p>
</td>
</tr>
</table>
### StringSelector [flexible](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#StringSelector data-text="StringSelector"}
*Defined in [fuchsia.diagnostics/selector.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/selector.fidl;l=20)*
<p>StringSelector is an union defining different ways to describe a pattern to match
strings against.</p>
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="StringSelector.string_pattern">
<td><h3 id="StringSelector.string_pattern" class="add-link hide-from-toc">1</h3></td>
<td><code>string_pattern</code></td>
<td>
<code>string[100]</code>
</td>
<td><p>This is a provided string that defines a pattern to
match against. The parser treats asterisks (*), colons (:) and backslashes
() as special characters.</p>
<p>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.</p>
<p>eg: abc will match any string with the exact name &quot;abc&quot;.
eg: a* will match any string with the exact name &quot;a*&quot;.
eg: a\* will match any that starts with exactly &quot;a&quot;.
eg: a* will match any string that starts with &quot;a&quot;.
eg: a<em>b will match any string that starts with a and ends with b.
eg: a</em>b*c will match any string that starts with a and ends with c, with <code>b</code>
in the middle.</p>
<p>In addition, the &quot;**&quot; literal is treated as a special sequence that may match
multiple levels in a component selector only. See |ComponentSelector| for
details.</p>
</td>
</tr>
<tr id="StringSelector.exact_match">
<td><h3 id="StringSelector.exact_match" class="add-link hide-from-toc">2</h3></td>
<td><code>exact_match</code></td>
<td>
<code>string[100]</code>
</td>
<td><p>This is a provided string that defines an exact string to match against. No
characters are treated as special, or carry special syntax.</p>
</td>
</tr>
</table>
### TreeSelector [flexible](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#TreeSelector data-text="TreeSelector"}
*Defined in [fuchsia.diagnostics/selector.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/selector.fidl;l=121)*
<p>TreeSelector represents a selection request on a hierarchy of named nodes, with
named properties on those nodes.</p>
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="TreeSelector.subtree_selector">
<td><h3 id="TreeSelector.subtree_selector" class="add-link hide-from-toc">1</h3></td>
<td><code>subtree_selector</code></td>
<td>
<code><a class='link' href='#SubtreeSelector'>SubtreeSelector</a></code>
</td>
<td><p>A selector defining a set of nodes to match, for which the entire subtree including
those nodes are selected.</p>
</td>
</tr>
<tr id="TreeSelector.property_selector">
<td><h3 id="TreeSelector.property_selector" class="add-link hide-from-toc">2</h3></td>
<td><code>property_selector</code></td>
<td>
<code><a class='link' href='#PropertySelector'>PropertySelector</a></code>
</td>
<td><p>A selector defining a set of nodes to match, and on those matched nodes a set of named
propperties to match.</p>
</td>
</tr>
</table>
## **CONSTANTS**
<table>
<tr><th>Name</th><th>Value</th><th>Type</th><th>Description</th></tr>
<tr id="MAXIMUM_ENTRIES_PER_BATCH">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/reader.fidl;l=14">MAXIMUM_ENTRIES_PER_BATCH</a></td>
<td>
<code>64</code>
</td>
<td><code>uint16</code></td>
<td><p>The size 64 was chosen because entries in batches are handles to
VMOs and there is a limit of 64 handles per fidl message.</p>
</td>
</tr>
<tr id="MAXIMUM_RAW_SELECTOR_LENGTH">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/reader.fidl;l=10">MAXIMUM_RAW_SELECTOR_LENGTH</a></td>
<td>
<code>1024</code>
</td>
<td><code>uint16</code></td>
<td><p>The size bound of 1024 is a reasonably low size restriction that meets most
canonical selectors we've ecountered.</p>
</td>
</tr>
<tr id="MAX_DATA_HIERARCHY_DEPTH">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/selector.fidl;l=16">MAX_DATA_HIERARCHY_DEPTH</a></td>
<td>
<code>100</code>
</td>
<td><code>uint16</code></td>
<td></td>
</tr>
<tr id="MAX_LOG_SELECTORS">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/log_settings.fidl;l=8">MAX_LOG_SELECTORS</a></td>
<td>
<code>64</code>
</td>
<td><code>uint8</code></td>
<td><p>Max number of LogInterestSelectors that can be specified via a listener.</p>
</td>
</tr>
<tr id="MAX_MONIKER_SEGMENTS">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/selector.fidl;l=12">MAX_MONIKER_SEGMENTS</a></td>
<td>
<code>25</code>
</td>
<td><code>uint16</code></td>
<td></td>
</tr>
<tr id="MAX_STRING_SELECTOR_LENGTH">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.diagnostics/selector.fidl;l=8">MAX_STRING_SELECTOR_LENGTH</a></td>
<td>
<code>100</code>
</td>
<td><code>uint16</code></td>
<td></td>
</tr>
</table>