# fuchsia.inspect

<br />

Added: 7

## **PROTOCOLS**

## InspectSink

*Defined in [fuchsia.inspect/inspect_sink.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/inspect_sink.fidl;l=25)*
Added: 16

<br />

### 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
Added: HEAD

#### Request

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.inspect#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
Added: HEAD

#### Request

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.inspect#InspectSinkFetchEscrowRequest` |

#### Response

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.inspect#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` | `https://fuchsia.dev/reference/fidl/fuchsia.inspect#InspectSinkPublishRequest` |

## Tree

*Defined in [fuchsia.inspect/tree.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/tree.fidl;l=46)*

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.

<br />

### 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` | `https://fuchsia.dev/reference/fidl/fuchsia.inspect#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:https://fuchsia.dev/reference/fidl/fuchsia.inspect#TreeNameIterator` |

### OpenChild

Open a child Tree by name.

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

#### Request

| Name | Type |
|---|---|
| `child_name` | `https://fuchsia.dev/reference/fidl/fuchsia.inspect#TreeName` |
| `tree` | `server_end:https://fuchsia.dev/reference/fidl/fuchsia.inspect#Tree` |

## TreeNameIterator

*Defined in [fuchsia.inspect/tree.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/tree.fidl;l=24)*

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

<br />

### 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<https://fuchsia.dev/reference/fidl/fuchsia.inspect#TreeName>` |

## **STRUCTS**

### EscrowToken [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource)

*Defined in [fuchsia.inspect/inspect_sink.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/inspect_sink.fidl;l=9)*
Added: HEAD

<br />

| Field | Type | Description | Default |
|---|---|---|---|
| `token` | `handle<eventpair>` |   | No default |

## **TABLES**

### InspectSinkEscrowRequest [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource)

*Defined in [fuchsia.inspect/inspect_sink.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/inspect_sink.fidl;l=66)*

| Ordinal | Field | Type | Description |
|---|---|---|---|
| ### 1 | `vmo` | `https://fuchsia.dev/reference/fidl/fuchsia.inspect#EscrowedVmo` | The VMO containing Inspect data that the server will store. Required |
| ### 2 | `token` | `https://fuchsia.dev/reference/fidl/fuchsia.inspect#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` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/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](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource)

*Defined in [fuchsia.inspect/inspect_sink.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/inspect_sink.fidl;l=110)*

| Ordinal | Field | Type | Description |
|---|---|---|---|
| ### 1 | `token` | `https://fuchsia.dev/reference/fidl/fuchsia.inspect#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` | `client_end:https://fuchsia.dev/reference/fidl/fuchsia.inspect#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](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource)

*Defined in [fuchsia.inspect/inspect_sink.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/inspect_sink.fidl;l=28)*

| Ordinal | Field | Type | Description |
|---|---|---|---|
| ### 1 | `tree` | `client_end:https://fuchsia.dev/reference/fidl/fuchsia.inspect#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](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource)

*Defined in [fuchsia.inspect/inspect_sink.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/inspect_sink.fidl;l=126)*

| Ordinal | Field | Type | Description |
|---|---|---|---|
| ### 1 | `vmo` | `https://fuchsia.dev/reference/fidl/fuchsia.inspect#EscrowedVmo` |   |

### TreeContent [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource)

*Defined in [fuchsia.inspect/tree.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/tree.fidl;l=18)*

The content of a specific Inspect Tree.

<br />

| Ordinal | Field | Type | Description |
|---|---|---|---|
| ### 1 | `buffer` | `https://fuchsia.dev/reference/fuchsia.mem//https://fuchsia.dev/reference/fuchsia.mem#Buffer` | Buffer containing the bytes of a tree in Inspect format. |

## **UNIONS**

### InspectSink_FetchEscrow_Result [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible) [resource](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#value-vs-resource)

*Defined in [fuchsia.inspect/inspect_sink.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/inspect_sink.fidl;l=126)*

| Ordinal | Variant | Type | Description |
|---|---|---|---|
| ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.inspect#InspectSink_FetchEscrow_Response` |   |
| ### 3 | `framework_err` | `internal` |   |

<br />

## **CONSTANTS**

| Name | Value | Type | Description |
|---|---|---|---|
| [DEFAULT_TREE_NAME](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/inspect_sink.fidl;l=21) | `root` | `String` | Added: 22 |
| [MAX_NAME_LENGTH](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/inspect_sink.fidl;l=18) | `4096` | `uint64` | Added: 16 |
| [MAX_TREE_NAME_LENGTH](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/tree.fidl;l=9) | `2040` | `uint64` | Maximum length of an Inspect Tree, specified by the format. |

## **ALIASES**

| Name | Value | Description |
|---|---|---|
| [EscrowedVmo](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/inspect_sink.fidl;l=14) | `zx/Handle` | Added: HEAD |
| [TreeName](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.inspect/tree.fidl;l=15) | `string`\[`https://fuchsia.dev/reference/fidl/fuchsia.inspect#MAX_TREE_NAME_LENGTH`\] |   |