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.

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

NameType
config TraceConfig
output handle<socket>

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

NameType
options TerminateOptions

Response

NameType
result TerminateResult

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

NameType
options StartOptions

Response

NameType
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

NameType
options StopOptions

Response

NameType

GetProviders

Return the set of registered providers.

Request

NameType

Response

NameType
providers vector<ProviderInfo>[100]

GetKnownCategories

Request

NameType

Response

NameType
categories vector<KnownCategory>[100]

OnSessionStateChange

Event sent when the session state changes.

Response

NameType
state SessionState

STRUCTS

Controller_StartTracing_Response

Defined in fuchsia.tracing.controller/trace_controller.fidl

NameTypeDescriptionDefault

KnownCategory

Defined in fuchsia.tracing.controller/trace_controller.fidl

Result of GetKnownCategories.

NameTypeDescriptionDefault
name string[100] No default
description string[400] No default

ENUMS

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.

NameValueDescription
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.

BufferingMode

Type: uint8

Defined in fuchsia.tracing.controller/trace_controller.fidl

NameValueDescription
ONESHOT 0
CIRCULAR 1
STREAMING 2

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.

NameValueDescription
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.

StartErrorCode

Type: uint32

Defined in fuchsia.tracing.controller/trace_controller.fidl

Error codes from Start operations.

NameValueDescription
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

ProviderSpec

Defined in fuchsia.tracing.controller/trace_controller.fidl

OrdinalNameTypeDescription
1 name string[100]
2 buffer_size_megabytes_hint uint32

TraceConfig

Defined in fuchsia.tracing.controller/trace_controller.fidl

Provides options for the trace.

OrdinalNameTypeDescription
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.

TerminateOptions

Defined in fuchsia.tracing.controller/trace_controller.fidl

Terminate options.

OrdinalNameTypeDescription
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.

OrdinalNameTypeDescription

StartOptions

Defined in fuchsia.tracing.controller/trace_controller.fidl

Additional options to control trace data collection.

OrdinalNameTypeDescription
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.

StopOptions

Defined in fuchsia.tracing.controller/trace_controller.fidl

Additional options to control stopping of a trace.

OrdinalNameTypeDescription
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.

ProviderInfo

Defined in fuchsia.tracing.controller/trace_controller.fidl

Result of GetProviders.

OrdinalNameTypeDescription
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.

UNIONS

Controller_StartTracing_Result

Defined in fuchsia.tracing.controller/trace_controller.fidl

NameTypeDescription
response Controller_StartTracing_Response
err StartErrorCode

CONSTANTS

NameValueTypeDescription
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.

MAX_NUM_CATEGORIES 100 uint32

The maximum number of categories supported.

MAX_CATEGORY_NAME_LENGTH 100 uint32

The maximum length of a category name.

MAX_CATEGORY_DESCRIPTION_LENGTH 400 uint32

The maximum length of a category description.