A node is an exported entity within a component that may have 0 or more children. Each node has a name, and each child of a node must have a unique name among the children.
Nodes may have any number of properties. A property has a string key and a value which may be any one of a number of types:
UintProperty
- 64-bit unsigned integer.IntProperty
- 64-bit signed integer.DoubleProperty
- 64-bit floating point value.BoolProperty
- A boolean value.StringProperty
- UTF-8 string.ByteVectorProperty
- Vector of bytes.UintArray
, IntArray
, DoubleArray
- An array of the corresponding numeric type.LinearUintHistogram
, LinearIntHistogram
, LinearDoubleHistogram
A histogram with fixed-size buckets stored in an array.
ExponentialUintHistogram
, ExponentialIntHistogram
, ExponentialDoubleHistogram
A histogram with exponentially sized buckets stored in an array.
The Inspect File Format is a binary format that supports efficient insertion, modification, and deletion of Nodes and Properties at runtime. Readers take a consistent snapshot of the contents without communicating with writers.
Components by default obtain a reference to their out/
directory in their hub.
Top-level nodes are exposed as VmoFiles in the Hub ending in the extension .inspect
. It is customary for components to expose their primary or root tree as out/diagnostics/root.inspect
.
The manager for a component's environment may expose its own information about the component to the hub. For instance, appmgr exposes system_objects
for each component.
{C++}
The C++ Inspect Library provides full writing and reading support for the Inspect File Format.
Components that write inspect data should refrain from reading that data. Reading requires traversing the entire buffer, which is very expensive.
The Inspector
class provides a wrapper around creating a new buffer with one root Node that can be added to. Nodes and Properties have typed wrappers that automatically delete the underlying data from the buffer when they go out of scope.
The sys_inspect library provides a simple ComponentInspector
singleton interface to help with the common case of exposing a single hierarchy from the component.
The health feature supports exposing structured health information in a format known by health checking tools.
The test matchers library provides GMock matchers for verifying data that is read out of an Inspect hierarchy in tests.
The reading library supports parsing an Inspect File into a Hierarchy. Hierarchy
s contain NodeValue
s and PropertyValues
, which are the parsed versions of Node
s and Property
s respectively.
The Hierarchy
's NodeValue
is returned by node()
and child Hierarchy
s are returned in a vector by children()
. The GetByPath
function supports reading a specific child hierarchy by path.
The properties for a particular NodeValue
are available through the properties()
accessor. You may determine if a property contains a certain type by passing the corresponding PropertyValue
type as the template parameter to the Contains<T>()
method:
// Returns true if the first property of the hierarchy's node is an INT value. if (hierarchy.node().properties()[0].Contains<IntPropertyValue>()) { // ... }
Use the Get<T>()
method to obtain the property:
// Get the IntPropertyValue of the first property on the node. // Note: This causes a runtime exception if the property does not contain // the given type, crashing the program. hierarchy.node().properties()[0].Get<IntPropertyValue>();
You may also switch based on the different possible format types:
const auto& property = hierarchy.node().properties()[0]; switch (property.format()) { case FormatType::INT: const auto& value = property.Get<IntPropertyValue>(); /* ... */ break; /* ... */ }
Array types may be specially formatted to contain histograms. The GetBuckets()
method supports returning an array of histogram buckets from {Int,Uint,Double}ArrayValue
types. The array will be empty if the underlying array is not a specially formatted histogram.
{Rust}
The Rust Inspect Library provides full writing and reading support for the Inspect File Format.
Components that write inspect data should refrain from reading that data. Reading requires traversing the entire buffer, which is very expensive.
The Inspector
class provides a wrapper around creating a new buffer with one root Node that can be added to. Nodes and Properties have typed wrappers that automatically delete the underlying data from the buffer when they go out of scope.
The component module supports a simple inspector
function to handle the common use of exposing a single hierarchy from the component.
The health module supports exposing structured health information in a format known by health checking tools.
The testing module supports the assert_data_tree!
macro to match Inspect data for testing.
{Dart}
The Dart Inspect Library provides write support for the Inspect File Format.
The Inspect
class provides a wrapper around exposing and writing to named Inspect files on the Hub. Nodes and Properties have typed wrappers.
Node children and properties are deduplicated automatically by the library, so creating the same named property twice simply returns a reference to the previously existing property.
Deletion is manual, but it is compatible with Futures and callbacks in Dart:
var item = parent.child('item'); itemDeletedFuture.then(() => item.delete());
Validator Architecture describes an integration test framework for Inspect language libraries.
To examine the inspect hierarchies of components, you can use the ffx inspect show
command:
Print all inspect hierarchies:
ffx inspect show
Print the inspect hierarchy of a specific component (for example, core/font_provider
):
ffx inspect show core/font_provider
Or run ffx target snapshot
to generate a ZIP archive containing the system's diagnostic information, which includes inspect:
ffx target snapshot