fuchsia.tracing.controller

PROTOCOLS

Provisioner

Defined in fuchsia.tracing.controller/trace_controller.fidl

The provisioner interface used to initialize a trace Session, that can then be started and stopped.

The provisioner is required to start a trace Session and bind the control to the client. It can also perform tasks like getting the list of registered providers and known categories, which can be performed without a existing trace Session.

GetKnownCategories

Request

<EMPTY>

Response

Name	Type
payload	Provisioner_GetKnownCategories_Result

GetProviders

Return the set of registered providers.

Request

<EMPTY>

Response

Name	Type
payload	Provisioner_GetProviders_Result

InitializeTracing

Requests to initialize tracing with the specified config.

A bad request will terminate the connection.

Dropping the socket connection will abort and terminate the existing trace Session.

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
controller	server_end:Session
config	TraceConfig
output	handle<socket>

Session

Defined in fuchsia.tracing.controller/trace_controller.fidl

The session interface used by the trace tool to start/stop/terminate a trace Session.

The trace Session 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 Session 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 Session.

The trace Session must be initialized from the provisioner. It can then be used to start/stop tracing as many times as needed. Dropping the Session will terminate tracing.

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

Response

Name	Type
payload	Session_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
payload	StopOptions

Response

Name	Type
payload	Session_StopTracing_Result

WatchAlert

Returns the next alert when it arrives.

Alerts received by the Session are queued until a WatchAlert request is received. Alerts are sent to the caller in the order they were received.

WatchAlert requests are also queued until an alert is received and the requests are serviced in the order they were received.

Request

<EMPTY>

Response

Name	Type
payload	Session_WatchAlert_Result

STRUCTS

Provisioner_GetKnownCategories_Response

Defined in fuchsia.tracing.controller/trace_controller.fidl

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

Provisioner_GetProviders_Response

Defined in fuchsia.tracing.controller/trace_controller.fidl

Field	Type	Description	Default
providers	vector<ProviderInfo>:100		No default

Session_StartTracing_Response

Defined in fuchsia.tracing.controller/trace_controller.fidl

<EMPTY>

Session_WatchAlert_Response

Defined in fuchsia.tracing.controller/trace_controller.fidl

Field	Type	Description	Default
alert_name	AlertName		No default

ENUMS

SessionState flexible

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.

StartError flexible

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.

StopError flexible

Type: uint32

Defined in fuchsia.tracing.controller/trace_controller.fidl

Error codes from Stop operations.

Name	Value	Description
NOT_INITIALIZED	1	Trace controller is unavailable. Nothing to stop.
NOT_STARTED	2	Tracing has not started or is currently stoppped.
ABORTED	3	Tracing aborted due to error.

TABLES

FxtVersion

Defined in fuchsia.tracing.controller/trace_controller.fidl

Version of trace record format.

Default to the latest available version, which is currently 0.1.

More information about the format of trace records can be found here: https://fuchsia.dev/fuchsia-src/reference/tracing/trace-format

Ordinal	Field	Type	Description
1	major	uint32	Defaults to 0.
2	minor	uint32	Defaults to 1

ProviderInfo

Defined in fuchsia.tracing.controller/trace_controller.fidl

Result of GetProviders.

Ordinal	Field	Type	Description
1	id	fuchsia.tracing/ProviderId	The provider's ID, assigned by trace-manager.
2	pid	zx/Koid	The provider's pid.
3	name	fuchsia.tracing/ProviderName	The name of the provider.

ProviderSpec

Defined in fuchsia.tracing.controller/trace_controller.fidl

Ordinal	Field	Type	Description
1	name	fuchsia.tracing/ProviderName
2	buffer_size_megabytes_hint	uint32
3	categories	fuchsia.tracing/EnabledCategoryList

ProviderStats

Defined in fuchsia.tracing.controller/trace_controller.fidl

Statistics data per provider collected over the course of the tracing session

Ordinal	Field	Type	Description
1	name	fuchsia.tracing/ProviderName
2	pid	zx/Koid
3	buffering_mode	fuchsia.tracing/BufferingMode
4	buffer_wrapped_count	uint32
5	records_dropped	uint64
6	percentage_durable_buffer_used	float32
7	non_durable_bytes_written	uint64

StartOptions

Defined in fuchsia.tracing.controller/trace_controller.fidl

Additional options to control trace data collection.

Ordinal	Field	Type	Description
1	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. 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	fuchsia.tracing/EnabledCategoryList	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	Field	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.

StopResult

Defined in fuchsia.tracing.controller/trace_controller.fidl

Result of a terminate request.

Ordinal	Field	Type	Description
1	provider_stats	vector<ProviderStats>:100

TraceConfig

Defined in fuchsia.tracing.controller/trace_controller.fidl

Provides options for the trace.

Ordinal	Field	Type	Description
1	categories	fuchsia.tracing/EnabledCategoryList	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	fuchsia.tracing/BufferingMode
5	provider_specs	vector<ProviderSpec>:100	Overrides for particular providers.
6	version	FxtVersion	Maximum trace format version supported byt the client. If not set, this defaults to the latest available trace format version.
7	defer_transfer	bool	When true, the session will buffer the trace within the fuchsia.tracing.controller server and only send the trace over the output socket to the client once the trace completes. It is recommended that defering the trace transfer be set to true when using streaming mode and the fuchsia.tracing.controller client is across the host-device boundary, such as with ffx. In this, or other cases where sending the trace data could cause exess cpu overhead, the disk writing cost is preferrable to the cost of sending to the client. NOTE: defer_transfer only has effect during BufferingMode.STREAMING as other modes don't otherwise send trace data to the client during a trace. Added: 28

UNIONS

Provisioner_GetKnownCategories_Result strict

Defined in fuchsia.tracing.controller/trace_controller.fidl

Ordinal	Variant	Type	Description
1	response	Provisioner_GetKnownCategories_Response
3	framework_err	internal

Provisioner_GetProviders_Result strict

Defined in fuchsia.tracing.controller/trace_controller.fidl

Ordinal	Variant	Type	Description
1	response	Provisioner_GetProviders_Response
3	framework_err	internal

Session_StartTracing_Result strict

Defined in fuchsia.tracing.controller/trace_controller.fidl

Ordinal	Variant	Type	Description
1	response	Session_StartTracing_Response
2	err	StartError
3	framework_err	internal

Session_StopTracing_Result strict

Defined in fuchsia.tracing.controller/trace_controller.fidl

Ordinal	Variant	Type	Description
1	response	StopResult
2	err	StopError
3	framework_err	internal

Session_WatchAlert_Result strict

Defined in fuchsia.tracing.controller/trace_controller.fidl

Ordinal	Variant	Type	Description
1	response	Session_WatchAlert_Response
3	framework_err	internal

CONSTANTS

Name	Value	Type	Description
MAX_ALERT_NAME_LENGTH	14	uint32	The maximum length of an alert name.
MAX_NUM_PROVIDERS	100	uint32	The maximum number of providers supported.

ALIASES

Name	Value	Description
AlertName	string[MAX_ALERT_NAME_LENGTH]	aliases