| // 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; |
| |
| /// 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 |
| /// for a given Fuchsia target. |
| 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; |
| |
| /// Error for when a trace file is already being written to by the tracing |
| /// service. |
| DUPLICATE_TRACE_FILE = 4; |
| |
| /// When attempting to stop a trace, there were no active traces found for |
| /// the given lookup name. |
| NO_SUCH_TRACE_FILE = 5; |
| |
| /// No targets were found matching the query. |
| NO_SUCH_TARGET = 6; |
| |
| /// The query matched a target that is not connected to the Daemon's FIDL |
| /// channels. |
| DISCONNECTED_TARGET = 7; |
| }; |
| |
| /// An action to be preformed on this trace. Used as part of a Trigger. |
| type Action = strict enum { |
| /// Terminates the active trace. |
| TERMINATE = 1; |
| }; |
| |
| /// A trigger is an action that is done when a certain alert has been raised in the |
| /// fuchsia tracing system. |
| type Trigger = table { |
| /// The name of the alert being watched. |
| /// See fuchsia.tracing.controller.Controller.WatchAlert for more info. |
| 1: alert string:fuchsia.tracing.controller.MAX_ALERT_NAME_LENGTH; |
| |
| /// The action to run when this alert has been witnessed. |
| 2: action Action; |
| }; |
| |
| /// 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; |
| |
| /// The triggers to run against this trace. |
| 2: triggers vector<Trigger>:MAX; |
| }; |
| |
| @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 return a [RecordingAlreadyStarted] error. |
| /// |
| /// On success, returns the target on which the trace is running. |
| StartRecording(struct { |
| target_query TargetQuery; |
| output_file string:255; |
| 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. It is used the same way as |
| /// `TargetQuery.string_matcher`. If no target can be found |
| /// associated with a trace, this will fall back to being |
| /// interpreted as a file name. |
| /// |
| /// Returns: |
| /// - the resolved target for which the trace was running. |
| /// |
| /// Examples: |
| /// |
| /// ``` |
| /// 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"); |
| /// ``` |
| StopRecording(struct { |
| name string:255; |
| }) -> (struct { |
| target TargetInfo; |
| }) error RecordingError; |
| |
| /// Reports the current status of all running traces. |
| 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:255; |
| |
| /// 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; |
| }; |
| |
| protocol TracingStatusIterator { |
| /// Gets the next block of trace info entries. |
| GetNext() -> (struct { |
| entries vector<TraceInfo>:MAX; |
| }); |
| }; |