fuchsia.tracing.provider

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.

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

NameType
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

NameType
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

NameType

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

NameType

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.

Request

NameType
provider Provider
pid uint64
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.

Request

NameType
provider Provider
pid uint64
name string[100]

Response

NameType
s int32
started bool

STRUCTS

ProviderConfig

Defined in fuchsia.tracing.provider/provider.fidl

Trace provider configuration.

NameTypeDescriptionDefault
buffering_mode BufferingMode `buffering_mode` specifies what happens when the buffer fills. 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] What trace categories to collect data for. No default

StartOptions

Defined in fuchsia.tracing.provider/provider.fidl

Additional options to control tracing at start.

NameTypeDescriptionDefault
buffer_disposition 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. No default
additional_categories vector<string>[100] The trace categories to add to the initial set provided in `ProviderConfig`. No default

ENUMS

BufferingMode

Type: uint8

Defined in fuchsia.tracing.provider/provider.fidl

The trace buffering mode.

NameValueDescription
ONESHOT 1
CIRCULAR 2
STREAMING 3

BufferDisposition

Type: uint8

Defined in fuchsia.tracing.provider/provider.fidl

Choices for clearing/retaining trace buffer contents at Start. A brief summary of buffer contents: The trace buffer is divided into two main pieces: durable and non-durable. The durable portion contains things like the string and thread data for their respective references (trace_encoded_string_ref_t and trace_encoded_thread_ref_t). The non-durable portion contains the rest of the trace data like events); this is the portion that, for example, is discarded in circular buffering mode when the (non-durable) buffer fills.

NameValueDescription
CLEAR_ENTIRE 1
CLEAR_NONDURABLE 2
RETAIN 3

CONSTANTS

NameValueTypeDescription
MAX_PROVIDER_NAME_LENGTH 100 uint32 The maximum length of a provider's name.
MAX_NUM_CATEGORIES 100 uint32 The maximum number of categories supported.
MAX_CATEGORY_NAME_LENGTH 100 uint32 The maximum length of a category name.