fuchsia.inspect

PROTOCOLS

InspectSink

Defined in fuchsia.inspect/inspect_sink.fidl

Escrow

Instructs the server to store the VMO provided to make its data available to Inspect readers, even when the component that published this VMO isn't running.

This is meant to be used when integrating with Component Framework's Escrow APIs to enable stopping when IDLE but still ensure that some useful diagnostics information is available.

The client must provide a token that will be used as a unique identifier to this VMO by the the server. This token is an event pair, a client must provide one end of this event pair and hold to the other end (or escrow the handle it using Component APIs). If the server sees a PEER_CLOSED on the handle it received, it will drop the VMO associated with this token.

If any of the required arguments isn't passed the connection will be closed.

To learn more about stopping IDLE components, please refer to: https://fuchsia.dev/fuchsia-src/development/components/stop_idle

Request

Name	Type
payload	InspectSinkEscrowRequest

FetchEscrow

Instructs the server to return (and stop tracking) the VMO associated with the given token.

This is meant to be used when a component restarts and wants to fetch Inspect data that it escrowed.

To learn more about stopping IDLE components, please refer to: https://fuchsia.dev/fuchsia-src/development/components/stop_idle

Request

Name	Type
payload	InspectSinkFetchEscrowRequest

Response

Name	Type
payload	InspectSink_FetchEscrow_Result

Publish

Publishes a handle to the fuchsia.inspect.Tree protocol that the server can use to read Inspect data, including lazy nodes.

Request

Name	Type
payload	InspectSinkPublishRequest

Tree

Defined in fuchsia.inspect/tree.fidl

The Tree protocol represents a hierarchy of Inspect VMOs.

Link values stored in an Inspect file contain references to new named files that contain a continuation of the data for the overall hierarchy. Protocol Tree allows clients to request these named files so long as the hosting component is still alive.

Connecting to a particular tree keeps the content for that Tree resident in memory. Clients are recommended to traverse the trees in depth-first order to reduce memory usage. Serving components are free to deny connections to avoid unbounded memory usage.

GetContent

Get the content for the Inspect VMO backing this tree.

So long as the Tree connection is still maintained, the contents of the tree are guaranteed to still be live. Once the connection is lost, the serving component is free to clear the contents of returned shared buffers.

Serving components may return different buffers to GetContent requests for the same Tree.

Request

<EMPTY>

Response

Name	Type
content	TreeContent

ListChildNames

Iterate over the names of Trees that are children of this Tree.

The underlying list of children may change in between calls to ListChildNames and OpenChild.

Request

Name	Type
tree_iterator	server_end<TreeNameIterator>

OpenChild

Open a child Tree by name.

If the child cannot be opened, the given request is closed.

Request

Name	Type
child_name	TreeName
tree	server_end<Tree>

TreeNameIterator

Defined in fuchsia.inspect/tree.fidl

Iterator protocol for listing the names of children of a particular Tree.

GetNext

Get the next batch of names.

Returns an empty vector and closes the channel when no more names are present. Implementors may eagerly close the channel after sending the last batch.

Request

<EMPTY>

Response

Name	Type
name	vector<string>

STRUCTS

EscrowToken resource

Defined in fuchsia.inspect/inspect_sink.fidl

Field	Type	Description	Default
token	handle<eventpair>		No default

TABLES

InspectSinkEscrowRequest resource

Defined in fuchsia.inspect/inspect_sink.fidl

Ordinal	Field	Type	Description
1	vmo	EscrowedVmo	The VMO containing Inspect data that the server will store. Required
2	token	EscrowToken	The token identifying this VMO and also serving as a controller to stop storing this VMO in the server. Required
3	name	string[4096]	An optional name to identify this VMO, that can be human readable. Optional
4	tree	zx/Koid	An optional reference to the Tree that was previously provided to the server using Publish. The server will drop the handle associated with that tree connection, triggering a peer closed on the tree server. This enables the client to ensure the following: Tree data and escrowed data won't be present twice in snapshots. The caller can know when to stop serving the tree, preventing data missing from snapshots. If name isn't provided, the name of this Inspect will be the one associated with this tree. If the server isn't tracking any handle associated with the source component with this koid, this will be ignored and treated as if nothing had been provided. Optional

InspectSinkFetchEscrowRequest resource

Defined in fuchsia.inspect/inspect_sink.fidl

Ordinal	Field	Type	Description
1	token	EscrowToken	The token associated with the VMO taht we want to fetch. If this token isn't associated with any VMO the response will be empty. Required
2	tree	Tree	A handle that the server can use to continue reading data associated with this VMO. The previous name that the component had given to this VMO will be maintained. This would be equivalent to calling Publish with the return VMO, except that it removes the race that can happen if Inspect data is read, between the time that the component fetches the VMO and publishes a tree for it. Optional

InspectSinkPublishRequest resource

Defined in fuchsia.inspect/inspect_sink.fidl

Ordinal	Field	Type	Description
1	tree	Tree	The Tree that the server will use to fetch Inspect data. The connection will be closed if this isn't provided. Required
2	name	string[4096]	A name to identify this tree from the client perspective. This name isn't required to be unique across multiple trees. Multiple trees published under the same name are accepted and will not overwrite previously published trees. Optional

InspectSink_FetchEscrow_Response resource

Defined in fuchsia.inspect/inspect_sink.fidl

Ordinal	Field	Type	Description
1	vmo	EscrowedVmo

TreeContent resource

Defined in fuchsia.inspect/tree.fidl

The content of a specific Inspect Tree.

Ordinal	Field	Type	Description
1	buffer	fuchsia.mem/Buffer	Buffer containing the bytes of a tree in Inspect format.

UNIONS

InspectSink_FetchEscrow_Result strict resource

Defined in fuchsia.inspect/inspect_sink.fidl

Ordinal	Variant	Type	Description
1	response	InspectSink_FetchEscrow_Response
3	framework_err	internal

CONSTANTS

Name	Value	Type	Description
DEFAULT_TREE_NAME	root	String	Added: NEXT
MAX_NAME_LENGTH	4096	uint64	Added: 16
MAX_TREE_NAME_LENGTH	2040	uint64	Maximum length of an Inspect Tree, specified by the format.

ALIASES

Name	Value	Description
EscrowedVmo	zx/Handle	Added: HEAD
TreeName	string[MAX_TREE_NAME_LENGTH]