Inspect is a powerful diagnostics feature for Fuchsia Components.
This document describes the details about how components host their Inspect data and how various tools discover that data.
Hosting Inspect data
A component may expose Inspect data in the following ways:
Components do not need to reach out to other services in order to expose Inspect data.
Components generally do not need to be concerned with which method is
being used, client libraries abstract out the specific mechanism for
hosting. Nearly all implementations will eventually use
|Non-lazy values||Yes||Yes||Yes||Components may record values such as strings and integers.|
|Lazy values||Yes||No||Yes||Components may generate values dynamically at read time.|
|Mutable tree||Yes||Yes||Yes||Components may modify the values stored in their output.|
|Post-mortem inspection||Yes||Yes||No||The values recorded by a component are available after that component exits.|
|Low-latency snapshots||Yes||Yes||No||A full snapshot of the data can be obtained with low-latency.|
|Consistent snapshots||Yes*||Yes||No||The snapshot of the tree is guaranteed to represent its state at one point in time.|
(*: Each tree's snapshot is consistent, but inter-tree consistency is not guaranteed)
fuchsia.inspect.Tree supports all features of the Inspect API, and it
is the recommended way to expose Inspect data from components.
Components host a single service file named
a subdirectory called "diagnostics". Multiple such files may exist,
but they must be in separate subdirectories under "diagnostics".
fuchsia.inspect.Tree FIDL File defines the protocol
that is hosted by components to expose their Inspect data.
Tree protocol links together multiple Inspect VMOs
in a "tree of trees."
In the above figure, the tree named "root" handles protocol
fuchsia.inspect.Tree for connections on the top-level service hosted
diagnostics/fuchsia.inspect.Tree. Child trees may be enumerated
and opened using methods on the protocol. For example, "child B" may
not exist in memory until opened and read.
The protocol supports this behavior in the following ways:
This method obtains the content of the tree, currently in the form of an Inspect VMO. By convention, calling this method on the root tree should return a VMO that will be continually updated with new data. The client should not need to re-read the content of the tree to read new values.
This method accepts an iterator over which the names of children of the tree will be returned. For example, the tree in the figure above will return names "child A" and "child B" when run on the root tree.
This method accepts a request for
fuchsia.inspect.Treethat will be bound to the tree specified by a given name. Using this method a client may iterate through all trees exposed over the root iterface.
Components may expose any number of [Inspect VMOs][inspect-vmo]
out/diagnostics directory ending in the file extension
.inspect. By convention, components expose their "root" inspect tree at
Components may choose to generate the content of the VMO when the file is opened if they choose, however, there exists no mechanism to link multiple trees created this way together. For this reason, lazy values are not supported in the context of a single tree, either the entire tree is generated dynamically or none of it is.
This deprecated interface is used by Go to expose Inspect data. While
fuchsia.inspect.Tree exposes a "tree of trees," this interface exposes
only a single tree where subtrees may be dynamically instantiated.
This interface is deprecated in favor of the VMO format hosted by Inspect tree for the following reasons:
- VMO format supports low-latency snapshots without communicating with the hosting program.
- VMO format snapshots are always consistent for the whole tree.
- VMO format supports postmortem inspection, all Inspect data using the deprecated interface dies with the component.
Treeprotocol supports the same dynamic features as the deprecated interface.
Reading Inspect data
The two primary ways to read Inspect data are:
iquery (Inspect Query) is the CLI for interacting with Inspect data.
iquery's primary mode of operation takes a list of locations for Inspect
data and prints out the contains information. A location consists either
of the path to a
.inspect file, or the path to a directory containing
iquery's secondary mode of operation (triggered by
identifies locations for Inspect data from the given directorry path. The
two modes may be used together as follows:
iquery --recursive `iquery --find /hub | grep -v system_objects | grep component_name`
In the example above,
iquery is run to find a list of Inspect
locations that do not contain "system_objects" and that do contain
iquery is run on the result of the first
filter to recursively list data in the matching locations. Internally,
this is how the
fx iquery tool is implemented. You may instead write:
fx iquery component_name
The Fuchsia Diagnostics Platform, hosted by the Archivist, is responsible for monitoring and aggregating Inspect data on demand.
Collection under appmgr
When a component is running under appmgr, diagnostics
data is collected from its
A connection to this directory is provided to Archivist by the
A separate component, called
observer.cmx, serves the same purpose as
the Archivist but may be injected into tests. Observer allows tests to
find only their own diagnostics data, helping to make tests hermitic.
Collection under component_manager
When running under component manager, diagnostics data will be made available to the Archivist through a new event system. This mechanism is still a work in progress.
TODO(47865): Update details when done.
Reading Inspect from the Archivist
The Archivist (and observer) host
fuchsia.diagnostics.Archive, which provides the
method to obtain Inspect data from running components.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2020-03-11.