fuchsia.tracing.controller

PROTOCOLS

Controller

Defined in fuchsia.tracing.controller/trace_controller.fidl

The controller interface used by the trace tool to initialize/start/stop/terminate tracing.

The trace controller may lightly validate the structure of trace records as it copies them from trace buffers into the output. In particular, it may verify the size of each record header to ensure that the framing of trace records in the data stream is maintained.

The trace controller does not validate the contents of the trace records themselves. For example, it does not try to check argument lengths in events. This ensures that the trace format can be extended without needing to modify the trace controller.

GetKnownCategories

Request

Name	Type

Response

Name	Type
`categories`	`vector<KnownCategory>[100]`

GetProviders

Return the set of registered providers.

Request

Name	Type

Response

Name	Type
`providers`	`vector<ProviderInfo>[100]`

InitializeTracing

Requests to initialize tracing with the specified config.

A bad request will terminate the connection.

The trace controller emits trace data to output as a sequence of binary formatted trace records. Traces obtained from different providers are delimited by metadata records within the stream.

Request

Name	Type
`config`	`TraceConfig`
`output`	`handle<socket>`

OnSessionStateChange

Event sent when the session state changes.

Response

Name	Type
`state`	`SessionState`

StartTracing

Requests to start tracing with the specified options.

If tracing has already started then the request is ignored, except to send back an error code.

The trace controller acknowledges the request when all registered providers have been started or after TraceConfig.start_timeout_milliseconds milliseconds. One useful reason for the has-started acknowledgement is that the trace program can start a program to trace knowing that all the providers are started.

Request

Name	Type
`options`	`StartOptions`

Response

Name	Type
`result`	`Controller_StartTracing_Result`

StopTracing

Requests to stop tracing.

If tracing has already stopped then this does nothing. Returning a result lets callers know when it's ok to, for example, start tracing again.

Request

Name	Type
`options`	`StopOptions`

Response

Name	Type

TerminateTracing

Requests to terminate tracing.

If tracing has not yet stopped it is stopped first. If options.write_results is true, then the trace controller continues to transfer any remaining data to the output socket until finished, then closes the output.

Request

Name	Type
`options`	`TerminateOptions`

Response

Name	Type
`result`	`TerminateResult`

WatchAlert

Returns the next alert when it arrives.

Request

Name	Type

Response

Name	Type
`alert_name`	`string[14]`

STRUCTS

Controller_StartTracing_Response

Defined in fuchsia.tracing.controller/trace_controller.fidl

Name	Type	Description	Default

KnownCategory

Defined in fuchsia.tracing.controller/trace_controller.fidl

Result of GetKnownCategories.

Name	Type	Description	Default
`name`	`string[100]`		No default
`description`	`string[400]`		No default

ENUMS

BufferDisposition

Type: uint8

Defined in fuchsia.tracing.controller/trace_controller.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.

Name Value Description

Name	Value	Description
`CLEAR_ALL`	`1`	Clear the entire buffer, including durable buffer contents. N.B. If this is done mid-session, then string and thread references from prior to this point will become invalid - the underlying data will be gone. To prevent this save buffer contents before clearing. This is typically used when buffer contents were saved after the preceding Stop.
`CLEAR_NONDURABLE`	`2`	Clear the non-durable portion of the buffer, retaining the durable portion. This is typically used when buffer contents were not saved after the preceding Stop and the current contents are to be discarded.
`RETAIN`	`3`	Retain buffer contents. New trace data is added whether the previous trace run left off. This is typically used when buffer contents were not saved after the preceding Stop and the current contents are to be retained.

CLEAR_ALL

1

Clear the entire buffer, including durable buffer contents. N.B. If this is done mid-session, then string and thread references from prior to this point will become invalid - the underlying data will be gone. To prevent this save buffer contents before clearing.

This is typically used when buffer contents were saved after the preceding Stop.

CLEAR_NONDURABLE

2

Clear the non-durable portion of the buffer, retaining the durable portion.

This is typically used when buffer contents were not saved after the preceding Stop and the current contents are to be discarded.

RETAIN

3

Retain buffer contents. New trace data is added whether the previous trace run left off.

This is typically used when buffer contents were not saved after the preceding Stop and the current contents are to be retained.

BufferingMode

Type: uint8

Defined in fuchsia.tracing.controller/trace_controller.fidl

Name	Value	Description
`ONESHOT`	`0`
`CIRCULAR`	`1`
`STREAMING`	`2`

SessionState

Type: uint32

Defined in fuchsia.tracing.controller/trace_controller.fidl

The state of the tracing session. A "session" is everything between Initialize and Terminate.

Name	Value	Description
`READY`	`1`	The tracing system is ready for a new session. There can be only one session at a time.
`INITIALIZED`	`2`	A new tracing session has been initialized.
`STARTING`	`3`	Tracing is in the midst of starting.
`STARTED`	`4`	Tracing has started.
`STOPPING`	`5`	Tracing is in the midst of being stopped.
`STOPPED`	`6`	Tracing has fully stopped.
`TERMINATING`	`7`	Tracing is in the midst of being terminated. Once the system has completely terminated the session it goes back to the READY state.

StartErrorCode

Type: uint32

Defined in fuchsia.tracing.controller/trace_controller.fidl

Error codes from Start operations.

Name	Value	Description
`NOT_INITIALIZED`	`1`	Tracing hasn't been initialized, not ready to start.
`ALREADY_STARTED`	`2`	Tracing has already been started.
`STOPPING`	`3`	Tracing is currently being stopped.
`TERMINATING`	`4`	Tracing is currently being terminated.

TABLES

ProviderInfo

Defined in fuchsia.tracing.controller/trace_controller.fidl

Result of GetProviders.

Ordinal	Name	Type	Description
1	`id`	`uint32`	The provider's ID, assigned by trace-manager.
2	`pid`	`zx/koid`	The provider's pid.
3	`name`	`string[100]`	The name of the provider.

ProviderSpec

Defined in fuchsia.tracing.controller/trace_controller.fidl

Ordinal	Name	Type	Description
1	`name`	`string[100]`
2	`buffer_size_megabytes_hint`	`uint32`

StartOptions

Defined in fuchsia.tracing.controller/trace_controller.fidl

Additional options to control trace data collection.

Ordinal Name Type Description

Ordinal	Name	Type	Description
1	`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. If the preceding `Stop()` request had `save_after_stopped=true` then this value is overridden to CLEAR_ENTIRE_BUFFER to avoid duplicate data being saved.
2	`additional_categories`	`vector<string>[100]`	The trace categories to add to the initial set provided in `TraceConfig`. If the combined number of categories goes over the limit then the extra categories past the limit are discarded.

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.

If the preceding Stop() request had save_after_stopped=true then this value is overridden to CLEAR_ENTIRE_BUFFER to avoid duplicate data being saved.

additional_categories

vector<string>[100]

The trace categories to add to the initial set provided in TraceConfig. If the combined number of categories goes over the limit then the extra categories past the limit are discarded.

StopOptions

Defined in fuchsia.tracing.controller/trace_controller.fidl

Additional options to control stopping of a trace.

Ordinal	Name	Type	Description
1	`write_results`	`bool`	If true then write all collected data after tracing has stopped. This is useful in situations where one wants to clear the buffer before starting the next trace, without having to first terminate the trace and start a new one.

TerminateOptions

Defined in fuchsia.tracing.controller/trace_controller.fidl

Terminate options.

Ordinal	Name	Type	Description
1	`write_results`	`bool`	If true then write trace results. If false then discard trace results.

TerminateResult

Defined in fuchsia.tracing.controller/trace_controller.fidl

Result of a terminate request.

Ordinal	Name	Type	Description

TraceConfig

Defined in fuchsia.tracing.controller/trace_controller.fidl

Provides options for the trace.

Ordinal	Name	Type	Description
1	`categories`	`vector<string>[100]`	The trace categories to record, or an empty array for all.
2	`buffer_size_megabytes_hint`	`uint32`	Suggested size of trace buffer which each provider should receive.
3	`start_timeout_milliseconds`	`uint64`	Acknowledge start request after at most `start_timeout_milliseconds`.
4	`buffering_mode`	`BufferingMode`
5	`provider_specs`	`vector<ProviderSpec>[100]`	Overrides for particular providers.

UNIONS

Controller_StartTracing_Result

Defined in fuchsia.tracing.controller/trace_controller.fidl

Name	Type	Description
`response`	`Controller_StartTracing_Response`
`err`	`StartErrorCode`

CONSTANTS

Name	Value	Type	Description
MAX_ALERT_NAME_LENGTH	`14`	`uint32`	The maximum length of an alert name.
MAX_CATEGORY_DESCRIPTION_LENGTH	`400`	`uint32`	The maximum length of a category description.
MAX_CATEGORY_NAME_LENGTH	`100`	`uint32`	The maximum length of a category name.
MAX_NUM_CATEGORIES	`100`	`uint32`	The maximum number of categories supported.
MAX_NUM_PROVIDERS	`100`	`uint32`	The maximum number of providers supported.
MAX_PROVIDER_NAME_LENGTH	`100`	`uint32`	The maximum length of a provider's name.