blob: 8f6fa92576f53a0c4ba1bf5dbe88b2f235fb609b [file] [log] [blame]
// 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.provider;
using zx;
/// The maximum length of a provider's name.
const uint32 MAX_PROVIDER_NAME_LENGTH = 100;
/// The maximum number of categories supported.
const uint32 MAX_NUM_CATEGORIES = 100;
/// The maximum length of a category name.
const uint32 MAX_CATEGORY_NAME_LENGTH = 100;
/// The provider interface which applications must implement and register
/// with the `TraceRegistry` to participate in tracing.
/// See //zircon/system/ulib/trace-provider/ for a C++ implementation of
/// this interface which can easily be configured by an application.
protocol Provider {
/// Initialize tracing and prepare for writing trace records for events in
/// the specified `categories` into `buffer` using `fifo` for signaling.
/// Tracing hasn't started yet, a `Start()` call is still required.
/// At most one trace can be active at a time. Subsequent `Initialize()`
/// requests received prior to a `Terminate()` call must be ignored.
Initialize(ProviderConfig config);
/// Begin tracing.
/// If tracing has already started the provider must ignore the request.
/// There is no result. The provider must send a `TRACE_PROVIDER_STARTED`
/// packet on `fifo` to indicate success/failure of starting.
Start(StartOptions options);
/// Stop tracing.
/// If tracing has already stopped the provider must ignore the request.
/// Once the provider has finished writing any final events to the trace
/// buffer, it must send a `TRACE_PROVIDER_STOPPED` packet on `fifo`.
/// Note that multiple `Start,Stop` requests can be received between
/// `Initialize,Terminate`.
/// Terminate tracing.
/// Tracing is stopped first if not already stopped.
/// After tracing has fully terminated the provider must close both
/// `buffer` and `fifo` to indicate to the trace manager that tracing is
/// finished.
/// The service which trace providers use to register themselves with
/// the tracing system.
/// Note that one property of this interface is that once registration is made
/// the provider can drop this connection.
[Discoverable, Layout = "Simple"]
protocol Registry {
/// Registers the trace provider.
/// Note: Registration is asynchronous, it's only at some point after this
/// returns that the provider is actually registered.
/// To unregister, simply close the Provider pipe.
/// `pid` is the process id of the provider, `name` is the name of the
/// provider. Both of these are used in logging and diagnostic messages.
RegisterProvider(Provider provider, zx.koid pid, string:MAX_PROVIDER_NAME_LENGTH name);
/// Registers the trace provider synchronously. The call doesn't return
/// until the provider is registered.
/// On return `s` is `ZX_OK` if registration was successful.
/// `started` is true if tracing has already started, which is a hint to
/// the provider to wait for the Start() message before continuing if it
/// wishes to not drop trace records before Start() is received.
/// To unregister, simply close the Provider pipe.
/// `pid` is the process id of the provider, `name` is the name of the
/// provider. Both of these are used in logging and diagnostic messages.
RegisterProviderSynchronously(Provider provider, zx.koid pid, string:MAX_PROVIDER_NAME_LENGTH name) -> (zx.status s, bool started);
/// The trace buffering mode.
enum BufferingMode : uint8 {
/// In oneshot mode there is only one buffer that is not reused. When the
/// buffer fills the provider just keeps dropping records, keeping a count,
/// and then when tracing stops the header is updated to record final
/// state.
/// In circular mode, the buffer is continually written to until tracing
/// stops. When the buffer fills older records are discarded as needed.
/// In streaming mode, the buffer is effectively split into two pieces.
/// When one half of the buffer fills the provider notifies the trace
/// manager via the provided fifo, and then starts filling the other half
/// of the buffer. When the buffer is saved, the manager responds via the
/// provided fifo. If trace manager hasn't saved the buffer in time, and
/// the other buffer fills, then the provider is required to drop records
/// until space becomes available.
/// Trace provider configuration.
// The configuration of a provider is split out into a struct so that we can
// add configuration data without changing the method signature. Structs still
// introduce ABI compatibility issues, this will be switched to a table when
// tables are ready for use in zircon.
struct ProviderConfig {
/// `buffering_mode` specifies what happens when the buffer fills.
BufferingMode buffering_mode;
/// The buffer to write trace records into.
handle<vmo> buffer;
/// When the trace provider observes `ZX_FIFO_PEER_CLOSED` on `fifo`, it
/// must assume the trace manager has terminated abnormally (since `Stop`
/// was not received as usual) and stop tracing automatically, discarding
/// any in-flight trace data.
handle<fifo> fifo;
/// What trace categories to collect data for.
/// 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.
enum BufferDisposition : uint8 {
/// 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 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 buffer contents. New trace data is added where 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.
/// Additional options to control tracing at start.
struct StartOptions {
/// 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.
BufferDisposition buffer_disposition;
/// The trace categories to add to the initial set provided in
/// `ProviderConfig`.
vector<string:MAX_CATEGORY_NAME_LENGTH>:MAX_NUM_CATEGORIES additional_categories;