PROTOCOLS

Provider

Defined in fuchsia.tracing.provider/provider.fidl

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.

GetKnownCategories

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

Request

<EMPTY>

Response

Name	Type
categories	vector<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	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	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

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

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	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	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	StartOptions

Response

Name	Type
payload	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	ProviderV2_Stop_Result

Terminate

Terminate tracing.

Tracing is stopped first if not already stopped.

Request

<EMPTY>

Response

Name	Type
payload	ProviderV2_Terminate_Result

Registry

Defined in fuchsia.tracing.provider/provider.fidl

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.

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.

Request

Name	Type
provider	client_end:Provider
pid	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.

Request

Name	Type
provider	client_end:Provider
pid	zx/Koid
name	string:100

Response

Name	Type
s	zx/Status
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.

Request

Name	Type
provider	client_end:ProviderV2
pid	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.

Request

Name	Type
provider	client_end:ProviderV2
pid	zx/Koid
name	string:100

Response

Name	Type
payload	Registry_RegisterV2Synchronously_Result

STRUCTS

ProviderConfig resource

Defined in fuchsia.tracing.provider/provider.fidl

Trace provider configuration.

Field	Type	Description	Default
buffering_mode	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

Field	Type	Description	Default
categories	vector<fuchsia.tracing/KnownCategory>:5000		No default

ProviderV2_Start_Response

Defined in fuchsia.tracing.provider/provider.fidl

<EMPTY>

ProviderV2_Stop_Response

Defined in fuchsia.tracing.provider/provider.fidl

<EMPTY>

ProviderV2_Terminate_Response

Defined in fuchsia.tracing.provider/provider.fidl

<EMPTY>

Registry_RegisterV2Synchronously_Response

Defined in fuchsia.tracing.provider/provider.fidl

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

Additional options to control tracing at start.

Field	Type	Description	Default
buffer_disposition	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

Defined in fuchsia.tracing.provider/provider.fidl

Trace provider configuration.

Ordinal	Field	Type	Description
1	buffering_mode	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

Defined in fuchsia.tracing.provider/provider.fidl

Ordinal	Variant	Type	Description
1	response	ProviderV2_GetKnownCategories_Response
3	framework_err	internal

ProviderV2_Start_Result strict

Defined in fuchsia.tracing.provider/provider.fidl

Ordinal	Variant	Type	Description
1	response	ProviderV2_Start_Response
3	framework_err	internal

ProviderV2_Stop_Result strict

Defined in fuchsia.tracing.provider/provider.fidl

Ordinal	Variant	Type	Description
1	response	ProviderV2_Stop_Response
3	framework_err	internal

ProviderV2_Terminate_Result strict

Defined in fuchsia.tracing.provider/provider.fidl

Ordinal	Variant	Type	Description
1	response	ProviderV2_Terminate_Response
3	framework_err	internal

Registry_RegisterV2Synchronously_Result strict

Defined in fuchsia.tracing.provider/provider.fidl

Ordinal	Variant	Type	Description
1	response	Registry_RegisterV2Synchronously_Response
2	err	zx/Status
3	framework_err	internal

CONSTANTS

Name	Value	Type	Description
MAX_ALERT_NAME_LENGTH	14	uint32	The maximum length of an alert name. Added: HEAD