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.

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++ and 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 bounded list feature supports recording rolling event histories in fixed-capacity FIFO node buffers.

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 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 contrib crate provides BoundedListNode, inspect_log!, and time utilities for timestamped event logging.

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

ffx inspect

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

ffx inspect show also does fuzzy matching on its inputs. For example:

ffx inspect show archivist.cm

This prints all of the Inspect for bootstrap/archivist as long as this is the only component that exposes Inspect in the system whose URL ends with archivist.cm.

Fuzzy matching will fail if the input is insufficiently specific to identify an individual component; in that case, the tool will print a list of monikers that matched the query.

In general, this command accepts the following:

  • A component moniker, for example, core/network/netstack. If only the moniker is passed, collection markers don't need to be escaped, though they optionally can be.

  • A fuzzy search parameter, corresponding to a URL fragment, manifest fragment, or moniker fragment. Ie ffx inspect show archivist.cm for bootstrap/archivist with the manifest archivist.cm.

  • A component selector, for example, core/network/*.

  • A full diagnostics selector, for example, core/network/netstack:root/path/to/*:property. In the full selector case, escaping must be performed to create a valid selector.

Suppose you have the component bootstrap/driver-hosts:driver-host-337. An ergonomic way to avoid escaping things as much as possible when you want a specific property might look like the following:

ffx inspect driver-host-337 --data root/stats:my_stat

ffx target snapshot

ffx target snapshot generates a ZIP archive that contains the system's diagnostic information, which includes inspect:

ffx target snapshot

Best practices

Avoid nesting metrics from other components

When you design component diagnostics, keep each component's Inspect hierarchy scoped strictly to the data produced by that component. Avoid forwarding or nesting Inspect metrics from client or subordinate components under an intermediary component's Inspect tree.

Forwarding or nesting Inspect metrics under a foreign component creates several problems for tooling, debugging, and privacy compliance:

  • Developer experience and tooling attribution: Inspect data is attributed by component moniker. Diagnostic tools such as ffx inspect show and automated snapshot triage query Inspect hierarchies using component monikers (for example, core/network/netstack). When you nest metrics from multiple components inside a single intermediary service, querying the producer component's moniker returns no data, while querying the intermediary returns an unmanageable aggregated hierarchy.

  • Privacy reviews and allowlist enforcement: Fuchsia diagnostic pipelines and snapshot exporters enforce privacy controls using moniker-based selectors. Placing metrics from multiple producers under a foreign moniker obscures data origin, prevents granular data redaction, and complicates privacy review verification.

  • Lifecycle and failure isolation: An intermediary component holding metrics on behalf of other components can outlive or terminate independently of the actual metric producers. This creates stale diagnostics or causes data loss if the intermediary crashes.

Each component should publish its own Inspect tree directly under its own moniker.