Fuchsia component inspection overview

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.

Quick links

Not sure where to start?

Quickstart – A get-started guide for component inspection.
ffx inspect – The ffx command for inspecting components.
Codelab – A full codelab in C++ and Rust.
API reference for C++, Rust.
Health checks – Describes the health check subsystem.

Concepts

Components may expose a tree of Nodes, each of which has a set of Properties.

Figure: A tree of Nodes

Node

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.

Figure: A Node

Property

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:

Numeric Types

UintProperty - 64-bit unsigned integer.
IntProperty - 64-bit signed integer.
DoubleProperty - 64-bit floating point value.
BoolProperty - A boolean value.

String Types

StringProperty - UTF-8 string.
ByteVectorProperty - Vector of bytes.

Array Types

UintArray, IntArray, DoubleArray - An array of the corresponding numeric type.

Histogram Types

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.

Inspect File Format

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.

Filesystem Interface

Top-level nodes are exposed as VmoFiles in a component's outgoing directory ending in the extension .inspect. It is customary for components to expose their primary or root tree as out/diagnostics/root.inspect.

Language Libraries

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 inspect_component 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.

Reading Support

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 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.

Testing

Validator Architecture describes an integration test framework for Inspect language libraries.

Userspace tools

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