sdk/fidl/fuchsia.feedback/data_provider.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.feedback;

using zx;

/// Provides data useful to attach to feedback reports, e.g., a crash report filed by the system, a
/// user feedback report filed by a user or a bug report filed by a developer.
@discoverable(server="platform")
closed protocol DataProvider {
    /// Returns a snapshot of the device's state.
    ///
    /// `snapshot` may be empty if there was an issue generating the snapshot.
    strict GetSnapshot(resource struct {
        params GetSnapshotParameters;
    }) -> (resource struct {
        snapshot Snapshot;
    });

    /// Returns a set of annotations about the device's state.
    ///
    /// `annotations` may be empty if there was an issue collecting them.
    ///
    /// These are the same annotations as provided through GetSnapshot() - some clients only want
    /// the annotations while others want both the annotations and the snapshot and generating the
    /// snapshot can take significantly more time than collecting the annotations, e.g., logs are
    /// only part of the snapshot and not part of the annotations and can take some time.
    strict GetAnnotations(struct {
        params GetAnnotationsParameters;
    }) -> (struct {
        annotations Annotations;
    });
};

@available(added=25)
const MAX_NUM_ANNOTATIONS2_PROVIDED uint32 = 512;


/// Parameters for the DataProvider::GetAnnotations() method.
type GetAnnotationsParameters = table {
    /// Annotations are collected in parallel from various places in the platform, each with a
    /// timeout.
    ///
    /// `collection_timeout_per_annotation` allows clients to control how much time is given to
    /// each annotation collection. It enables clients to get a partial set of annotations under a
    /// certain time.
    1: collection_timeout_per_annotation zx.Duration;
};

/// Parameters for the DataProvider::GetSnapshot() method.
type GetSnapshotParameters = resource table {
    /// A snapshot aggregates various data from the platform (device uptime, logs, Inspect data,
    /// etc.) that are collected in parallel. Internally, each data collection is done within a
    /// timeout.
    ///
    /// `collection_timeout_per_data` allows clients to control how much time is given to each data
    /// collection. It enables clients to get a partial yet valid snapshot under a certain time.
    ///
    /// Note that this does not control how much total time the snapshot generation may take,
    /// which is by construction higher than `collection_timeout_per_data`, as clients can control
    /// the total time by using a timeout on the call to GetSnapshot() on their side.
    1: collection_timeout_per_data zx.Duration;

    /// If set, the snapshot archive will be sent as a |fuchsia.io.File| over this channel instead
    /// of being set in the |archive| field in the |Snapshot| response. This is typically useful if
    /// the client is on the host and does not support VMOs.
    2: response_channel zx.Handle:CHANNEL;
};

/// Annotations about the device's state.
///
/// Clients typically upload the data straight to servers. So the data comes in the form of
/// arbitrary key-value pairs that clients can directly forward to the servers.
type Annotations = table {
    /// A vector of key-value string pairs. Keys are guaranteed to be unique.
    @available(added=25)
    2: annotations2 vector<Annotation>:MAX_NUM_ANNOTATIONS2_PROVIDED;
};

/// Snapshot about the device's state.
///
/// Clients typically upload the data straight to servers. So the data comes in the form of
/// arbitrary key-value pairs that clients can directly forward to the servers.
type Snapshot = resource table {
    /// A <filename, ZIP archive> pair.
    ///
    /// The ZIP archive contains several files corresponding to the various data it collected from
    /// the platform. There is typically one file for all the annotations (device uptime, build
    /// version, etc.) and one file per attachment (logs, Inspect data, etc.).
    ///
    /// Not set if |response_channel| was set in the request.
    1: archive Attachment;

    /// A vector of key-value string pairs. Keys are guaranteed to be unique.
    ///
    /// While the annotations are included in the ZIP archive itself, some clients also want them
    /// separately to index or augment them so we provide them separately as well.
    @available(added=25)
    3: annotations2 vector<Annotation>:MAX_NUM_ANNOTATIONS2_PROVIDED;
};