| // Copyright 2016 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| library fuchsia.tracing.controller; |
| |
| using fuchsia.tracing; |
| using zx; |
| |
| /// The maximum number of providers supported. |
| const MAX_NUM_PROVIDERS uint32 = 100; |
| |
| /// The maximum length of an alert name. |
| const MAX_ALERT_NAME_LENGTH uint32 = 14; |
| |
| /// aliases |
| alias AlertName = string:MAX_ALERT_NAME_LENGTH; |
| |
| /// The state of the tracing session. |
| /// A "session" is everything between `Initialize` and `Terminate`. |
| type SessionState = flexible enum { |
| /// The tracing system is ready for a new session. |
| /// There can be only one session at a time. |
| READY = 1; |
| /// A new tracing session has been initialized. |
| INITIALIZED = 2; |
| /// Tracing is in the midst of starting. |
| STARTING = 3; |
| /// Tracing has started. |
| STARTED = 4; |
| /// Tracing is in the midst of being stopped. |
| STOPPING = 5; |
| /// Tracing has fully stopped. |
| STOPPED = 6; |
| /// Tracing is in the midst of being terminated. |
| /// Once the system has completely terminated the session it goes back |
| /// to the READY state. |
| TERMINATING = 7; |
| }; |
| |
| /// 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. |
| @discoverable |
| protocol Controller { |
| /// 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. |
| flexible InitializeTracing(resource struct { |
| config TraceConfig; |
| output zx.Handle:SOCKET; |
| }); |
| |
| /// 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. |
| flexible TerminateTracing(struct { |
| options TerminateOptions; |
| }) -> (struct { |
| result TerminateResult; |
| }); |
| |
| /// 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. |
| flexible StartTracing(struct { |
| options StartOptions; |
| }) -> () error StartErrorCode; |
| |
| /// 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. |
| flexible StopTracing(struct { |
| options StopOptions; |
| }) -> (); |
| |
| /// Return the set of registered providers. |
| flexible GetProviders() -> (struct { |
| providers vector<ProviderInfo>:MAX_NUM_PROVIDERS; |
| }); |
| |
| // Gets the known categories. |
| flexible GetKnownCategories() -> (struct { |
| categories vector<fuchsia.tracing.KnownCategory>:fuchsia.tracing.MAX_NUM_KNOWN_CATEGORIES; |
| }); |
| |
| /// Event sent when the session state changes. |
| flexible -> OnSessionStateChange(struct { |
| state SessionState; |
| }); |
| |
| /// Returns the next alert when it arrives. |
| flexible WatchAlert() -> (struct { |
| alert_name AlertName; |
| }); |
| }; |
| |
| // Individual providers can be tuned with this. |
| type ProviderSpec = table { |
| 1: name fuchsia.tracing.ProviderName; |
| 2: buffer_size_megabytes_hint uint32; |
| 3: categories fuchsia.tracing.EnabledCategoryList; |
| }; |
| |
| /// Provides options for the trace. |
| type TraceConfig = table { |
| /// The trace categories to record, or an empty array for all. |
| 1: categories fuchsia.tracing.EnabledCategoryList; |
| |
| /// Suggested size of trace buffer which each provider should receive. |
| // If table defaults were supported, this would default to 4. |
| 2: buffer_size_megabytes_hint uint32; |
| |
| /// Acknowledge start request after at most `start_timeout_milliseconds`. |
| // If table defaults were supported, this would default to 5000. |
| 3: start_timeout_milliseconds uint64; |
| |
| // If table defaults were supported, this would default to BufferingMode.ONESHOT. |
| 4: buffering_mode fuchsia.tracing.BufferingMode; |
| |
| /// Overrides for particular providers. |
| 5: provider_specs vector<ProviderSpec>:MAX_NUM_PROVIDERS; |
| }; |
| |
| /// Options to be passed with the TerminateTracing request. |
| /// This determines whether any pending data is written to the output |
| /// socket before it is closed. |
| type TerminateOptions = table { |
| /// If true then write trace results. |
| /// If false then discard trace results. |
| 1: write_results bool; |
| }; |
| |
| /// Statistics data per provider collected over the course of the tracing session |
| /// that is returned once the session is terminated. |
| type ProviderStats = table { |
| 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; |
| }; |
| |
| /// Result of a terminate request. |
| type TerminateResult = table { |
| 1: provider_stats vector<ProviderStats>:MAX_NUM_PROVIDERS; |
| }; |
| |
| /// Error codes from Start operations. |
| type StartErrorCode = flexible enum { |
| /// Tracing hasn't been initialized, not ready to start. |
| NOT_INITIALIZED = 1; |
| /// Tracing has already been started. |
| ALREADY_STARTED = 2; |
| /// Tracing is currently being stopped. |
| STOPPING = 3; |
| /// Tracing is currently being terminated. |
| TERMINATING = 4; |
| }; |
| |
| /// Additional options to control trace data collection. |
| type StartOptions = table { |
| /// 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. |
| 1: buffer_disposition fuchsia.tracing.BufferDisposition; |
| |
| /// 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. |
| 2: additional_categories fuchsia.tracing.EnabledCategoryList; |
| }; |
| |
| /// Additional options to control stopping of a trace. |
| type StopOptions = table { |
| /// 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. |
| 1: write_results bool; |
| }; |
| |
| /// Result of `GetProviders`. |
| type ProviderInfo = table { |
| /// The provider's ID, assigned by trace-manager. |
| 1: id fuchsia.tracing.ProviderId; |
| |
| /// The provider's pid. |
| 2: pid zx.Koid; |
| |
| /// The name of the provider. |
| 3: name fuchsia.tracing.ProviderName; |
| }; |