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.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/objects/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.
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 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.
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());
The primary userspace tool is iquery, which has its own manual page.
You can use the fx iquery command to dump out data for the entire system, or fx bugreport to generate a directory of diagnostic information from the system (which includes inspect).