<br />

Added: 7

## **PROTOCOLS**

## Provider

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=16)*

The provider interface which applications must implement and register
with the `TraceRegistry` to participate in tracing.

See //zircon/system/ulib/trace-provider/ for a C++ implementation of
this interface which can easily be configured by an application.
Removed: 31

<br />

### GetKnownCategories

Gets the trace categories that might be produced by this provider.
Added: 11

#### Request

\<EMPTY\>

#### Response

| Name | Type |
|---|---|
| `categories` | `vector<https://fuchsia.dev/reference/fuchsia.tracing//https://fuchsia.dev/reference/fuchsia.tracing#KnownCategory>:5000` |

### Initialize

Initialize tracing and prepare for writing trace records for events in
the specified `categories` into `buffer` using `fifo` for signaling.
Tracing hasn't started yet, a `Start()` call is still required.

At most one trace can be active at a time. Subsequent `Initialize()`
requests received prior to a `Terminate()` call must be ignored.

#### Request

| Name | Type |
|---|---|
| `config` | `https://fuchsia.dev/reference/fidl/fuchsia.tracing.provider#ProviderConfig` |

### Start

Begin tracing.

If tracing has already started the provider must ignore the request.

There is no result. The provider must send a `TRACE_PROVIDER_STARTED`
packet on `fifo` to indicate success/failure of starting.

#### Request

| Name | Type |
|---|---|
| `options` | `https://fuchsia.dev/reference/fidl/fuchsia.tracing.provider#StartOptions` |

### Stop

Stop tracing.

If tracing has already stopped the provider must ignore the request.

Once the provider has finished writing any final events to the trace
buffer, it must send a `TRACE_PROVIDER_STOPPED` packet on `fifo`.
Note that multiple `Start,Stop` requests can be received between
`Initialize,Terminate`.

#### Request

\<EMPTY\>

### Terminate

Terminate tracing.

Tracing is stopped first if not already stopped.
After tracing has fully terminated the provider must close both
`buffer` and `fifo` to indicate to the trace manager that tracing is
finished.

#### Request

\<EMPTY\>

## ProviderV2

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=70)*

The provider interface which applications must implement and register
with the `TraceRegistry` to participate in tracing.
Added: 31

<br />

### Flush

Requests the provider its buffer to be read out, regardless of it is
full or not.

Normally streaming mode only sends data once it has enough data to
require a buffer swap and data flush. This produces fewer, but larger
and bursty data transfers.

Some clients may want more regular smaller data transfers. These clients
may instead manually invoke Flush whenever they are ready for
data.

#### Request

\<EMPTY\>

### GetKnownCategories

Gets the trace categories that might be produced by this provider.

#### Request

\<EMPTY\>

#### Response

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.tracing.provider#ProviderV2_GetKnownCategories_Result` |

### Initialize

Initialize tracing and prepare for writing trace records for events in
the specified `categories` into `buffer`.
Tracing hasn't started yet, a `Start()` call is still required.

At most one trace can be active at a time. Subsequent `Initialize()`
requests received prior to a `Terminate()` call must be ignored.

#### Request

| Name | Type |
|---|---|
| `config` | `https://fuchsia.dev/reference/fidl/fuchsia.tracing.provider#ProviderConfigV2` |

### NotifyBufferSaved

A buffer has been saved (streaming mode only).

#### Request

| Name | Type |
|---|---|
| `wrapped_count` | `uint32` |
| `durable_data_end` | `uint64` |

### OnAlert

Sends an alert.

#### Response

| Name | Type |
|---|---|
| `name` | `string:14` |

### OnSaveBuffer

A buffer is full and needs to be saved (streaming mode only).

#### Response

| Name | Type |
|---|---|
| `wrapped_count` | `uint32` |
| `durable_data_end` | `uint64` |

### Start

Begin tracing.

If tracing has already started the provider must ignore the request.

#### Request

| Name | Type |
|---|---|
| `options` | `https://fuchsia.dev/reference/fidl/fuchsia.tracing.provider#StartOptions` |

#### Response

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.tracing.provider#ProviderV2_Start_Result` |

### Stop

Stop tracing.

If tracing has already stopped the provider must ignore the request.

Once the provider has finished writing any final events to the trace
buffer, it must send an `OnStopped()` event.
Note that multiple `Start,Stop` requests can be received between
`Initialize,Terminate`.

#### Request

\<EMPTY\>

#### Response

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.tracing.provider#ProviderV2_Stop_Result` |

### Terminate

Terminate tracing.

Tracing is stopped first if not already stopped.

#### Request

\<EMPTY\>

#### Response

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.tracing.provider#ProviderV2_Terminate_Result` |

## Registry

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=150)*

The service which trace providers use to register themselves with
the tracing system.
Note that one property of this interface is that once registration is made
the provider can drop this connection.

<br />

### RegisterProvider

Registers the trace provider.
Note: Registration is asynchronous, it's only at some point after this
returns that the provider is actually registered.
To unregister, simply close the Provider pipe.
`pid` is the process id of the provider, `name` is the name of the
provider. Both of these are used in logging and diagnostic messages.

# Deprecation

Use "RegisterV2" instead to use the FIDL-based coordination protocol.
Removed: 31

#### Request

| Name | Type |
|---|---|
| `provider` | `client_end:https://fuchsia.dev/reference/fidl/fuchsia.tracing.provider#Provider` |
| `pid` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/zx#Koid` |
| `name` | `string:100` |

### RegisterProviderSynchronously

Registers the trace provider synchronously. The call doesn't return
until the provider is registered.
On return `s` is `ZX_OK` if registration was successful.
`started` is true if tracing has already started, which is a hint to
the provider to wait for the Start() message before continuing if it
wishes to not drop trace records before Start() is received.
To unregister, simply close the Provider pipe.
`pid` is the process id of the provider, `name` is the name of the
provider. Both of these are used in logging and diagnostic messages.

# Deprecation

Use "RegisterV2Synchronously" instead to use the FIDL-based coordination protocol.
Removed: 31

#### Request

| Name | Type |
|---|---|
| `provider` | `client_end:https://fuchsia.dev/reference/fidl/fuchsia.tracing.provider#Provider` |
| `pid` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/zx#Koid` |
| `name` | `string:100` |

#### Response

| Name | Type |
|---|---|
| `s` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/zx#Result` |
| `started` | `bool` |

### RegisterV2

Registers the trace provider using the V2 protocol.

Note: Registration is asynchronous, it's only at some point after this
returns that the provider is actually registered.

To unregister, close the `provider` connection.
Added: 31

#### Request

| Name | Type |
|---|---|
| `provider` | `client_end:https://fuchsia.dev/reference/fidl/fuchsia.tracing.provider#ProviderV2` |
| `pid` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/zx#Koid` |
| `name` | `string:100` |

### RegisterV2Synchronously

Registers the trace provider synchronously using the V2 protocol.

The call doesn't return until the provider is registered. Most callers
should use RegisterV2 unless they need to synchronize with they tracing
system to ensure that specific events are captured.

To unregister, close the `provider` connection.
Added: 31

#### Request

| Name | Type |
|---|---|
| `provider` | `client_end:https://fuchsia.dev/reference/fidl/fuchsia.tracing.provider#ProviderV2` |
| `pid` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/zx#Koid` |
| `name` | `string:100` |

#### Response

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.tracing.provider#Registry_RegisterV2Synchronously_Result` |

## **STRUCTS**

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

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=236)*

Trace provider configuration.
Removed: 31

<br />

| Field | Type | Description | Default |
|---|---|---|---|
| `buffering_mode` | `https://fuchsia.dev/reference/fuchsia.tracing//https://fuchsia.dev/reference/fuchsia.tracing#BufferingMode` | `buffering_mode` specifies what happens when the buffer fills. Added: 11 | No default |
| `buffer` | `handle<vmo>` | The buffer to write trace records into. | No default |
| `fifo` | `handle<fifo>` | When the trace provider observes `ZX_FIFO_PEER_CLOSED` on `fifo`, it must assume the trace manager has terminated abnormally (since `Stop` was not received as usual) and stop tracing automatically, discarding any in-flight trace data. | No default |
| `categories` | `vector<string:100>:5000` | What trace categories to collect data for. Added: 11 | No default |

### ProviderV2_GetKnownCategories_Response

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=105)*

| Field | Type | Description | Default |
|---|---|---|---|
| `categories` | `vector<https://fuchsia.dev/reference/fuchsia.tracing//https://fuchsia.dev/reference/fuchsia.tracing#KnownCategory>:5000` |   | No default |

### ProviderV2_Start_Response

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=87)*

\<EMPTY\>

### ProviderV2_Stop_Response

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=97)*

\<EMPTY\>

### ProviderV2_Terminate_Response

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=102)*

\<EMPTY\>

### Registry_RegisterV2Synchronously_Response

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=222)*

| Field | Type | Description | Default |
|---|---|---|---|
| `started` | `bool` | true if tracing has already started, which is a hint to the provider to wait for the Start() message before continuing if it wishes to not drop trace records before Start() is received. | No default |

### StartOptions

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=271)*

Additional options to control tracing at start.

<br />

| Field | Type | Description | Default |
|---|---|---|---|
| `buffer_disposition` | `https://fuchsia.dev/reference/fuchsia.tracing//https://fuchsia.dev/reference/fuchsia.tracing#BufferDisposition` | Whether and how to clear the buffer when starting data collection. This allows, for example, multiple Start/Stop trace runs to be collected in the same buffer. Added: 11 | No default |
| `additional_categories` | `vector<string:100>:5000` | The trace categories to add to the initial set provided in `ProviderConfig`. Added: 11 | No default |

## **TABLES**

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

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=258)*

Trace provider configuration.
Added: 31

<br />

| Ordinal | Field | Type | Description |
|---|---|---|---|
| ### 1 | `buffering_mode` | `https://fuchsia.dev/reference/fuchsia.tracing//https://fuchsia.dev/reference/fuchsia.tracing#BufferingMode` | `buffering_mode` specifies what happens when the buffer fills. |
| ### 2 | `buffer` | `handle<vmo>` | The buffer to write trace records into. |
| ### 3 | `categories` | `vector<string:100>:5000` | What trace categories to collect data for. |

## **UNIONS**

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

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=105)*

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

<br />

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

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=87)*

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

<br />

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

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=97)*

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

<br />

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

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=102)*

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

<br />

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

*Defined in [fuchsia.tracing.provider/provider.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=222)*

| Ordinal | Variant | Type | Description |
|---|---|---|---|
| ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.tracing.provider#Registry_RegisterV2Synchronously_Response` |   |
| ### 2 | `err` | `https://fuchsia.dev/reference/zx//https://fuchsia.dev/reference/zx#Status` |   |
| ### 3 | `framework_err` | `internal` |   |

<br />

## **CONSTANTS**

| Name | Value | Type | Description |
|---|---|---|---|
| [MAX_ALERT_NAME_LENGTH](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.tracing.provider/provider.fidl;l=65) | `14` | `uint32` | The maximum length of an alert name. Added: 31 |