src/developer/ffx/fidl/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.
library fuchsia.developer.ffx;

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

/// The maximum length allowed for paths passed to tracing commands.
///
/// We choose the value of 4096 here to match Linux's maximum path length.
const MAX_PATH_LENGTH uint32 = 4096;

alias RecordingError = fuchsia.tracing.controller.RecordingError;
alias Action = fuchsia.tracing.controller.Action;
alias Trigger = fuchsia.tracing.controller.Trigger;
alias TraceOptions = fuchsia.tracing.controller.TraceOptions;

@discoverable
closed 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 return a [RecordingAlreadyStarted] error.
    ///
    /// On success, returns the target on which the trace is running.
    strict StartRecording(struct {
        target_query TargetQuery;
        output_file string:MAX_PATH_LENGTH;
        options TraceOptions;
        target_config fuchsia.tracing.controller.TraceConfig;
    }) -> (struct {
        target TargetInfo;
    }) error RecordingError;

    /// Stops the trace recording, flushing the remaining contents to the output
    /// file.
    ///
    /// Parameters:
    /// - name: A string that is first used to look up a target under which the
    ///         trace is running. If no file can be found given the name of the
    ///         trace, it is used the same way as
    ///         `TargetQuery.string_matcher` to find a Fuchsia Device nodename.
    ///         If no target can be found associated with a trace, this will
    ///         return an error.
    ///
    /// Returns:
    /// - the resolved target for which the trace was running, as well as the
    ///   output file being written to, and the result of the tracing
    ///   termination.
    ///
    /// Examples:
    ///
    /// ```rust
    /// proxy.start_recording(
    ///     target_query: TargetQuery { string_matcher: "foo"},
    ///     output_file: "output_file.fxt",
    ///     ...
    /// );
    ///
    /// // Can be stopped via this invocation (preferred).
    /// proxy.stop_recording("foo");
    ///
    /// // Can also be stopped via this invocation.
    /// proxy.stop_recording("output_file.fxt");
    /// ```
    strict StopRecording(struct {
        name string:MAX_PATH_LENGTH;
    }) -> (struct {
        target TargetInfo;
        output_file string:MAX_PATH_LENGTH;
        categories fuchsia.tracing.EnabledCategoryList;
        result fuchsia.tracing.controller.StopResult;
    }) error RecordingError;

    /// Reports the current status of all running traces.
    strict Status(resource struct {
        iterator server_end:TracingStatusIterator;
    }) -> ();
};

type TraceInfo = table {
    /// The target on which the trace is running.
    1: target TargetInfo;

    /// Path to the output file.
    2: output_file string:MAX_PATH_LENGTH;

    /// The total duration of the command in fractional seconds. This will not
    /// be set if the command is supposed to run indefinitely.
    3: duration float64;

    /// The amount of time remaining before the trace terminates. This will not
    /// be set if the command is supposed to run indefinitely.
    4: remaining_runtime float64;

    /// The original config sent to the `StartRecording` command.
    5: config fuchsia.tracing.controller.TraceConfig;

    /// A list of triggers active for this trace. See [Trigger] for more info.
    6: triggers vector<Trigger>:MAX;
};

closed protocol TracingStatusIterator {
    /// Gets the next block of trace info entries.
    strict GetNext() -> (struct {
        entries vector<TraceInfo>:MAX;
    });
};