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.
Objects may have any number of properties. A property has a key and a value which are both strings.
Nodes may have any number of metrics. A metric has a string key and numeric value.
There are three types of metric values:
UINT
, a 64-bit unsigned integer.INT
, a 64-bit signed integer.DOUBLE
, a 64-bit floating point value.WORK IN PROGRESS: Streaming events are planned to be supported in the future.
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
.
For the deprecated FIDL interface, a component exposes its root tree as a fuchsia.inspect.Inspect
service file at out/objects
. Both FIDL and VMO reading are currently supported by the iquery
tool.
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.
Class Inspector
is the main entrypoint into using the Inspect API. Method CreateTree
returns a new Tree
object that wraps a VMO.
Each Tree
has a root Object
(Node
) that can be obtained with GetRoot
.
New children can be created underneath the root node, and each node may contain any number of metrics and properties. Creation methods return an RAII wrapper around the value. This wrapper owns the value stored in the VMO, and it automatically removes the wrapped value when deleted.
The C++ interface supports wrapping the deprecated FIDL interface using a compatibility mode.
Instead of using CreateTree
and Inspector
, you may instead construct an object directly with a name to retrieve an exposable object using FIDL.
This interface supports exposing objects using the fuchsia.inspect.Inspect FIDL interface. The main feature this supports over the VMO solution is dynamic children and values, though these features are planned for VMO.
Class Object
is the implementation of an object in C++. It implements the Vnode
and Inspect
interfaces to expose the object through the filesystem and raw FIDL protocols respectively.
Helper classes Property
and Metric
wrap the functionality of dealing with their respective values and serializing to FIDL.
Property values, metric values, and even the set of children may be set on-demand through callbacks.
Properties and metrics utilizing a callback will only get their value by callback until they are set to an explicit value.
The set of children for an object is the union of its explicitly set children and on-demand children provided by callback.
Metric
allows for typed addition and subtraction. The Set*
methods set the type of the metric, and arithmetic operations do not modify this type.
Class ObjectDir
is a lightweight wrapper around a refcounted pointer to an Object
. ObjectDirs
are safe to copy, and provide a stable reference to a single object.
ObjectDir
simplifies traversing a tree of objects by name and setting properties/metrics on those objects with a STL-style wrapper.
Class ExposedObject
is a base class simplifying management of complex persistent hierarchies of objects. It is the recommended implementation point for exposing objects from your components.
An ExposedObject
is not an object itself, rather it contains a reference to the object itself as well as a reference to the (optional) parent for the object. On destruction, the ExposedObject
automatically removes itself from its parent without invalidating underlying references to the object. This enables developers to expose complex, rapidly changing hierarchies of objects without worrying about object lifetime.
The primary userspace tool is iquery, which has its own manual page.