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 |
---|---|---|
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 |
---|---|---|---|
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 |
2 | additional_categories |
vector<string>[100]
|
The trace categories to add to the initial set provided in
|
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 |
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. |