Components in Fuchsia may expose structured information about themselves conforming to the Inspect API. This document describes the concepts of Component Inspection, the interface, the C++ language implementation of the interface, and user-facing tools for interacting with components that expose information.
Not sure where to start? Quick Start
Components may expose a tree of Nodes, each of which has a set of Properties.
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, LinearDoubleHistogramA histogram with fixed-size buckets stored in an array.
ExponentialUintHistogram, ExponentialIntHistogram, ExponentialDoubleHistogramA 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. Hierarchys contain NodeValues and PropertyValues, which are the parsed versions of Nodes and Propertys respectively.
The Hierarchy's NodeValue is returned by node() and child Hierarchys 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_inspect_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.
The primary userspace tool is iquery, which has its own manual page.
You can use the fx iquery show command to dump out data for the entire system, or fx snapshot to generate a directory of diagnostic information from the system (which includes inspect).