sdk/fidl/fuchsia.diagnostics/reader.fidl

// Copyright 2019 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.diagnostics;

using fuchsia.mem;

///  The size bound of 1024 is a reasonably low size restriction that meets most
///  canonical selectors we've ecountered.
const uint16 MAXIMUM_RAW_SELECTOR_LENGTH = 1024;

/// The size 64 was chosen because entries in batches are handles to
/// VMOs and there is a limit of 64 handles per fidl message.
const uint16 MAXIMUM_ENTRIES_PER_BATCH = 64;

/// Enum describing the potential fail-states of the Accessor service.
enum AccessorError {
    // A provided selector argument failed to verify/parse.
    // Existing examples:
    //    * Use of an escape character, without a following character to escape.
    INVALID_SELECTOR = 1;
};

/// Enum describing the potential fail-states of the Accessor service due to issues
/// reading the data.
enum ReaderError {
    // An IO error suggests that parsing of data hierarchy VMOs or writing of formatted data to
    // sockets has failed.
    IO = 1;
};

/// Argument used for Archive selectors, can be either the pre-parsed
/// fidl struct or string representation.
xunion SelectorArgument {
    /// A Selector defining a pattern-matcher which selects for components within a hierarchy
    /// and properties in a data hierarchy namespaced by component.
    1: Selector structured_selector;

    /// The Archive protocol parses the raw_selector
    /// into a structured [fuchsia.diagnostics/Selector]
    /// The Selector defines a pattern-matcher which selects for components within a hierarchy
    /// and properties in a data hierarchy namespaced by component.
    /// NOTE: All StringSelectors parsed from the raw_selector will be interperetted in
    ///       string_pattern mode, giving significance to special characters.
    /// TODO(4601): Link to in-tree documentation for raw selector strings.
    2: string:MAXIMUM_RAW_SELECTOR_LENGTH raw_selector;
};

/// A fidl union containing a complete hierarchy of structured diagnostics
/// data, such that the content can be parsed into a file by itself.
xunion FormattedContent {
    /// A complete formatted data hierarchy encoded as json.
    /// Data hierarchies are the hierarchical representation
    /// of the structured diagnostics data on the system.
    /// The VMO will contain up to 1mb of diagnostics data,
    /// with dropped subtrees if the hierarchy is too large.
    1: fuchsia.mem.Buffer formatted_json_hierarchy;

    /// A complete formatted data hierarchy encoded as text.
    /// The VMO will contain up to 1mb of diagnostics data,
    /// with dropped subtrees if the hierarchy is too large.
    2: fuchsia.mem.Buffer formatted_text_hierarchy;
};

/// Outer protocol for interacting with the different diagnostics data sources.
[Discoverable]
protocol Archive {
    /// Creates a Reader for interacting with Inspect data.
    /// The resulting interface can be used to analyze Inspect hierarchy data
    /// scoped to the components specified by the static configurations of the Accessor
    /// pipeline that the client connects to, and the provided selectors vector argument.
    ///
    /// + request `inspect_reader` is a [fuchsia.diagnostics/Reader] that processes
    ///   Reader requests, sitting on top of inspect data.
    /// + request `selectors` is a vector of [fuchsia.diagnostics/SelectorArgument] which
    ///   provide additional filters to scope data with. If the vector is empty,
    ///   all available results are returned.
    ///.
    /// * error a [fuchsia.diagnostics/AccessorError]
    ///   value indicating that the provided selectors failed to verify.
    // TODO(4601): Consider making selectors optional or providing the parameters
    //             as a table.
    ReadInspect(request<Reader> inspect_reader, vector<SelectorArgument>:MAX selectors)
        -> () error AccessorError;

    /// Creates a Reader for interacting with structured Log data.
    /// The resulting interface can be used to analyze structured Log data
    /// scoped to the components specified by the static configurations of the Accessor
    /// pipeline that the client connects to, and the provided selectors vector argument.
    ///
    /// + request `log_reader` is a [fuchsia.diagnostics/Reader] that processes
    ///   Reader requests, sitting on top of Log data.
    /// + request `selectors` is a vector of [fuchsia.diagnostics/SelectorArgument] which
    ///   provide additional filters to scope data with. If the vector is empty,
    ///   all available results are returned.
    ///
    /// * error a [fuchsia.diagnostics/AccessorError]
    ///   value indicating that the provided selectors failed to verify.
    ReadLogs(request<Reader> log_reader, vector<SelectorArgument>:MAX selectors)
        -> () error AccessorError;

    /// Creates a Reader for interacting with lifecycle event data.
    /// The resulting interface can be used to analyze lifecycle event data
    /// scoped to the components specified by the static configurations of the Accessor
    /// pipeline that the client connects to, and the provided selectors vector argument.
    ///
    /// + request `lifecycle_reader` is a [fuchsia.diagnostics/Reader] that processes Reader
    ///   requests, sitting on top of lifecycle event data.
    /// + request `selectors` is a vector of [fuchsia.diagnostics/SelectorArgument] which
    ///   provide additional filters to scope data with. If the vector is empty,
    ///   all available results are returned.
    ///
    /// * error a [fuchsia.diagnostics/AccessorError]
    ///   value indicating that the provided selectors failed to verify.
    ReadLifecycleEvents(request<Reader> lifecycle_reader,
                        vector<SelectorArgument>:MAX selectors) -> () error AccessorError;
};

/// A protocol to access data from a particular data source.
protocol Reader {
    /// Filters the data hierarchies of components based on the statically provided allowlists
    /// and the selectors provided by the accessor request, formats these filtered data
    /// hierarchies according to the specified [fuchsia.diagnostics/FormatSettings]
    /// argument, then serves the resulting data hierarchies over a BatchIterator.
    ///
    /// + request `format_settings` the [fuchsia.diagnostics/FormatSettings] that
    ///   specifies the format of data returned by the BatchIterator.
    /// + request `result_iterator` is a [fuchsia.diagnostics.BatchIterator] that
    ///   processes client requests to fetch [fuchsia.diagnostics/FormattedContent]
    ///   structs from the current snapshot.
    ///
    /// * error a [fuchsia.diagnostics/ReaderError]
    ///   value indicating that there was an issue configuring the BatchIterator
    ///   connection.
    GetSnapshot(Format format, request<BatchIterator> result_iterator)
        -> () error ReaderError;

    /// Creates a Stream for polling a Reader data sources for new data.
    /// The resulting interface can be used retrieve the next batch of data matching
    /// which is within the ComponentSelector and TreeSelector scopes defined by the Archive
    /// and Reader protocols through which this stream was created, in addition to the
    /// static configurations that define the allowlist of data the reader has access to.
    ///
    /// + request `format_settings` the [fuchsia.diagnostics/FormatSettings] that
    ///   specifies the format of data returned by the Batch during
    ///  FormatBatch calls.
    /// + request `stream_mode` is a [fuchsia.diagnostics/StreamMode] that specifies how the
    ///   streaming server provides streamed results.
    ReadStream(StreamMode stream_mode, Format format, request<Stream> formatted_stream);
};

/// Enum specifying the modes by which a user can connect to and stream diagnostics metrics.
enum StreamMode : uint8 {
    /// The first call to FormatBatch will serve the historical polling records of metrics
    /// configured to store state in buffers, then the server will close.
    REPLAY_ONLY = 1;
    /// The first call to FormatBatch will serve the historical polling records of metrics
    /// configured to store state in buffers, then will close. Subsequent calls to FormatBatch
    /// will return newly polled records that were taken since the last FormatBatch call.
    REPLAY_THEN_ONGOING = 2;
    /// The first call to FormatBatch will return newly polled records that were taken
    /// since the client connection was established. Subsequent calls to FormatBatch
    /// will return newly polled records that were taken since the last FormatBatch call.
    ONGOING_ONLY = 3;
};

/// Protocol offering an API for batch-retrieving all newly updated diagnostics data sincee
/// the last call.
protocol Stream {
    /// Retrieves the batch of data which has appeared since the last GetNext call and matches
    /// the configured ComponentSelector and TreeSelector scopes, in addition to the
    /// static configurations that define the allowlist of data the reader has access to.
    ///
    /// The batch of data which has appeared since the last FormatNext call is formatted
    /// according to the FormatSettings provided to the ReadStream call
    /// which created the connection and then is served over a BatchIterator.
    ///
    /// If no new data has appeared since the last FormatBatch call, the BatchIterator
    /// that starts serving over `batch_iterator` will just serve an empty vector, and then
    /// close.
    ///
    ///
    /// + request `batch_iterator` is a [fuchsia.diagnostics.BatchIterator] that
    ///   processes client requests to fetch [fuchsia.diagnostics/FormattedContent]
    ///   structs encoding newly available data from the data hierarchies the Reader that spawned
    ///   this stream is sitting upon.
    ///
    /// * error a [fuchsia.diagnostics/ReaderError]
    ///   value indicating that there was an issue configuring the Batch
    ///   connection for the stream data.
    GetBatch(request<BatchIterator> batch_iterator) -> () error ReaderError;
};

/// Conceptually, a directory iterator, where each element in the iterator is a single
/// complete file that can be concatenated with other results.
protocol BatchIterator {
    /// Returns a vector of [fuchsia.diagnostics/FormattedContent] structs
    /// with a format dictated by the format_settings argument provided to the Reader protocol
    /// which spawned this BatchIterator.
    ///
    /// An empty vector implies that the data hierarchy has been fully iterated, and subsequent
    /// GetNext calls will return no data.
    ///
    /// - returns a vector of FormattedContent structs. Clients connected to a
    ///   Batch are expected to call GetNext() until an empty vector
    ///   is returned, denoting that the entire data hierarchy has been read.
    ///
    /// * error a [fuchsia.diagnostics/ReaderError]
    ///   value indicating that there was an issue reading the underlying data hierarchies
    ///   or formatting those hierarchies to populate the `batch`. Note, these
    ///   issues do not include a single component's data hierarchy failing to be read.
    ///   The iterator is tolerant of individual component data sources failing to be read,
    ///   whether that failure is a timeout or a malformed binary file.
    ///   In the event that a GetNext call fails, that subset of the data hierarchy results is
    ///   dropped, but future calls to GetNext will provide new subsets of
    ///   FormattedDataHierarchies.
    ///
    GetNext() -> (vector<FormattedContent>:MAXIMUM_ENTRIES_PER_BATCH batch) error ReaderError;
};