tree: 94e34da9e625ea18e9c5e4d7f68083ba07de3fed [path history] [tgz]
  1. codelab/
  2. ceo.png
  3. dataexport.png
  4. employee.png
  5. health.md
  6. node.png
  7. quickstart.md
  8. README.md
  9. relations.png
  10. rust.md
  11. tree.png
docs/development/diagnostics/inspect/README.md

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++, Rust, and Dart.

  • API reference for C++, Rust, and Dart.

  • 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

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.

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

    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 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());
    

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