Expand description
§fuchsia-inspect
Components in Fuchsia may expose structured information about themselves conforming to the Inspect API. This crate is the core library for writing inspect data in Rust components.
For a comprehensive guide on how to start using inspect, please refer to the codelab.
§Library concepts
There’s two types of inspect values: nodes and properties. These have the following characteristics:
- A Node may have any number of key/value pairs called Properties.
- A Node may have any number of children, which are also Nodes.
- Properties and nodes are created under a parent node. Inspect is already initialized with a root node.
- The key for a value in a Node is always a UTF-8 string, the value may be one of the supported types (a node or a property of any type).
- Nodes and properties have strict ownership semantics. Whenever a node or property is created, it is written to the backing VMO and whenever it is dropped it is removed from the VMO.
- Inspection is best effort, if an error occurs, no panic will happen and nodes and properties might become No-Ops. For example, when the VMO becomes full, any further creation of a property or a node will result in no changes in the VMO and a silent failure. However, mutation of existing properties in the VMO will continue to work.
- All nodes and properties are thread safe.
§Creating vs Recording
There are two functions each for initializing nodes and properties:
create_*
: returns the created node/property and it’s up to the caller to handle its lifetime.record_*
: creates the node/property but doesn’t return it and ties its lifetime to the node where the function was called.
§Lazy value support
Lazy (or dynamic) values are values that are created on demand, this is, whenever they are read. Unlike regular nodes, they don’t take any space on the VMO until a reader comes and requests its data.
There’s two ways of creating lazy values:
- Lazy node: creates a child node of root with the given name. The callback returns a
future for an
Inspector
whose root node is spliced into the parent node when read. - Lazy values: works like the previous one, except that all properties and nodes under the future root node node are added directly as children of the parent node.
§Quickstart
Add the following to your component main:
use fuchsia_inspect::component;
use inspect_runtime;
let _inspect_server_task = inspect_runtime::publish(
component::inspector(),
inspect_runtime::PublishOptions::default(),
);
// Now you can create nodes and properties anywhere!
let child = component::inspector().root().create_child("foo");
child.record_uint("bar", 42);
Modules§
- component
- Component inspection utilities
- health
- Health-checking inspect node.
- hierarchy
- reader
- Reading inspect data
- stats
- Inspect stats node.
- types
Structs§
- Bool
Property - Inspect API Bool Property data type.
- Bytes
Property - Inspect Bytes Property data type.
- Double
Array Property - Inspect double array data type.
- Double
Exponential Histogram Property - An exponential histogram property for double values.
- Double
Linear Histogram Property - A linear histogram property for double values.
- Double
Property - Inspect double property type.
- Exponential
Histogram Params - The parameters of an exponential histogram.
- Inspector
- Root of the Inspect API. Through this API, further nodes can be created and inspect can be served.
- Inspector
Config - Classic builder pattern object for constructing an
Inspector
. - IntArray
Property - Inspect int array data type.
- IntExponential
Histogram Property - An exponential histogram property for int values.
- IntLinear
Histogram Property - A linear histogram property for integer values.
- IntProperty
- Inspect int property data type.
- Lazy
Node - Inspect Lazy Node data type. NOTE: do not rely on PartialEq implementation for true comparison. Instead leverage the reader.
- Linear
Histogram Params - The parameters of a linear histogram.
- Node
- Inspect Node data type.
- Stats
- Statistics about the current inspect state.
- String
Array Property - String
Property - Inspect String Property data type.
- String
Reference - StringReference is a type that can be constructed and passed into the Inspect API as a name of a Node. If this is done, only one reference counted instance of the string will be allocated per Inspector. They can be safely used with LazyNodes.
- Uint
Array Property - Inspect uint array data type.
- Uint
Exponential Histogram Property - An exponential histogram property for uint values.
- Uint
Linear Histogram Property - A linear histogram property for unsigned integer values.
- Uint
Property - Inspect uint property data type.
- Value
List - Holds a list of inspect types that won’t change.
Enums§
- Error
- Errors that Inspect API functions can return.
Constants§
- DIAGNOSTICS_
DIR - Directiory within the outgoing directory of a component where the diagnostics service should be added.
Traits§
- Arithmetic
Array Property - Array
Property - Trait implemented by all array properties providing common operations on arrays.
- Diagnostics
Hierarchy Getter - A type which can function as a “view” into a diagnostics hierarchy, optionally allocating a new instance to service a request.
- Histogram
Property - Trait implemented by all histogram properties providing common operations.
- Inspect
Type - Trait implemented by all inspect types.
- Inspect
Type Reparentable - Trait allowing a
Node
to adopt any Inspect type as its child, removing it from the original parent’s tree. - Inspector
Introspection Ext - Length
- Get the usable length of a type.
- Numeric
Property - Trait implemented by numeric properties providing common operations.
- Property
- Trait implemented by properties.
Functions§
- unique_
name - Generates a unique name that can be used in inspect nodes and properties that will be prefixed
by the given
prefix
.