sdk/fidl/fuchsia.developer.bridge/tracing.fidl

// Copyright 2021 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.

//! Covers the FFX tracing service, which is for running trace readouts
//! on a Fuchsia target.
//! For more information/usage examples, see the FFX trace plugin.
library fuchsia.developer.bridge;

using fuchsia.device;
using fuchsia.tracing.controller;

/// This covers erorr from using the `Tracing` protocol below (specifically
/// trace recording errors).
type RecordingError = strict enum {
    /// Error encountered when opening the proxy to the target.
    TARGET_PROXY_OPEN = 0;

    /// This is a general error when starting a trace.
    RECORDING_START = 1;

    /// An error encountered if a trace recording has already been started.
    RECORDING_ALREADY_STARTED = 2;

    /// An error encountered when attempting to stop a trace. This causes an
    /// immediate termination of the client channel, so the user should not
    /// attempt to run `StopRecording` again.
    RECORDING_STOP = 3;
};

/// Covers how a trace will be run when invoking `StartRecording`.
type TraceOptions = table {
    /// Determines how long a trace recording will run before terminating in
    /// fractional seconds. This is an "at-least" duration, with the actual
    /// runtime terminating likely a few dozen milliseconds longer.
    ///
    /// If this is not set, a trace will run indefinitely and must be stopped
    /// using `StopRecording`. Or by cleanly shutting down the daemon via
    /// `ffx daemon stop` or by using the Deamon proxy itself.
    1: duration float64;
};

@discoverable
protocol Tracing {
    /// Starts a trace recording. If the target behind the query is already
    /// running a trace, or some trace is actively writing to the output file,
    /// this will
    StartRecording(struct {
        target_query string:<fuchsia.device.DEVICE_NAME_MAX, optional>;
        output_file string:255;
        options TraceOptions;
        target_config fuchsia.tracing.controller.TraceConfig;
    }) -> (struct {}) error RecordingError;

    /// Stops the trace recording, flushing the remaining contents to the output
    /// file.
    StopRecording(struct {
        output_file string:255;
    }) -> (struct {}) error RecordingError;
};