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 MAX_QUERY_LENGTH uint16 = 64;

/// This is currently not exhaustive.
type LogMethod = strict enum {
    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;
};

type QueryError = strict enum {
    /// 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(struct {
        project_id uint32;
        method LogMethod;
    }) -> (struct {
        events vector<cobalt.CobaltEvent>:MAX_QUERY_LENGTH;
        more bool;
    });

    /// 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(struct {
        project_id uint32;
        method LogMethod;
    }) -> (struct {
        events vector<cobalt.CobaltEvent>:MAX_QUERY_LENGTH;
        more bool;
    }) 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(struct {
        project_id uint32;
        method LogMethod;
    });
};