sdk/fidl/fuchsia.cobalt.test/query.test.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.cobalt.test;

using fuchsia.cobalt as cobalt;

/// Maximum number of events returned by a query.
const uint16 MAX_QUERY_LENGTH = 64;

/// This is currently not exhaustive.
enum LogMethod {
    LOG_EVENT = 1;
    LOG_EVENT_COUNT = 2;
    LOG_ELAPSED_TIME = 3;
    LOG_FRAME_RATE = 4;
    LOG_MEMORY_USAGE = 5;
    LOG_INT_HISTOGRAM = 7;
    LOG_COBALT_EVENT = 8;
    LOG_COBALT_EVENTS = 9;
};

enum QueryError {
    /// The logger required to complete the current query could not be found.
    LOGGER_NOT_FOUND = 0;
};

/// LoggerQuerier provides a way to query mock cobalt services to check that
/// clients of cobalt are logging events as expected.
[Discoverable]
protocol LoggerQuerier {
    /// Returns the _first_ N events that were logged for the logger with the
    /// given `project_id` and a `more` flag indicating whether there were
    /// more than N events logged. There is no way to retrieve events logged
    /// after the first N events.
    ///
    /// Will hang until at least one cobalt metric is recorded for the given
    /// `project_id` and `method`.
    ///
    /// Repeated calls to WatchLogs for a given LogMethod will block until new
    /// events are logged with that method, enabling tests to synchronize
    /// without sleeps or timeouts.
    [Transitional]
    WatchLogs2(uint32 project_id, LogMethod method) -> (vector<cobalt.CobaltEvent>:MAX_QUERY_LENGTH events, bool more);

    /// Returns the _first_ N events that were logged for the logger with the
    /// given `project_id` and a `more` flag indicating whether there were
    /// more than N events logged. There is no way to retrieve events logged
    /// after the first N events.
    ///
    /// Returns an error if a Logger for the given `project_id` has not been
    /// created through a request to the LoggerFactory protocol.
    ///
    /// Repeated calls to WatchLogs for a given LogMethod will block until new
    /// events are logged with that method, enabling tests to synchronize
    /// without sleeps or timeouts.
    [Deprecated = "use WatchLogs2"]
    WatchLogs(uint32 project_id, LogMethod method) -> (vector<cobalt.CobaltEvent>:MAX_QUERY_LENGTH events, bool more) error QueryError;

    /// Clear all logged events by logging `method` for the logger with the
    /// given `project_id`.
    ///
    /// This is a no-op if a logger for the given `project_id` does not exist.
    /// Notably, it does _not_ create a new logger with `project_id` if one
    /// does not already exist.
    ResetLogger(uint32 project_id, LogMethod method);
};