blob: e40e8cf33d71df3c47a92bb455a4520794cdc63d [file] [log] [blame]
// Copyright 2017 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;
/// A specification to identify a single Cobalt report.
table ReportSpec {
/// The customer ID, as specified in Cobalt's metrics registry.
1: uint32 customer_id;
/// The ID of the project, as specified in Cobalt's metrics registry.
2: uint32 project_id;
/// The ID of the metric, as specified in Cobalt's metrics registry.
3: uint32 metric_id;
/// The ID of the report, as specified in Cobalt's metrics registry.
4: uint32 report_id;
/// The Controller is primarily useful for testing the Cobalt service.
/// Cobalt clients should use the Logger.
protocol Controller {
/// Requests that the collection of Observations that are currently cached
/// locally be sent to the Cobalt server soon. Cobalt will send the
/// Observations in one or more batches and will retry several times upon
/// failure. The response occurs only after that procedure is completed. A
/// return value of true indicates that all Observations were successfully
/// sent. A return value of false indicates otherwise.
RequestSendSoon() -> (bool success);
/// The Cobalt FIDL service will block, not processing any further FIDL
/// requests or responses, on either this interface or the Logger interface,
/// until either `max_wait_seconds` have elapsed or the Cobalt service's
/// worker thread has successfully sent all previously added Observations to
/// the Shuffler. The response will be returned after the blocking period has
/// ended. Note that this method does not request an expedited send and so it
/// is possible that the worker thread is currently waiting for the next
/// scheduled send time and so the empty state will not be achieved prior
/// that time.
BlockUntilEmpty(uint32 max_wait_seconds) -> ();
/// These diagnostic stats are mostly useful in a testing environment but
/// may possibly prove useful in production also.
GetNumSendAttempts() -> (uint32 num);
GetFailedSendAttempts() -> (uint32 num);
GetNumObservationsAdded() -> (uint64 num_obs);
GetNumEventAggregatorRuns() -> (uint64 num_runs);
/// Triggers Cobalt to generate Observations based on locally aggregated
/// event data and write them to the local ObservationStore. In a non-test
/// environment this would normally be done periodically by a background
/// thread. In a test environment this method should be invoked against an
/// instance of the Cobalt FIDL service that was passed the flag
/// --start_event_aggregator_worker=false.
/// `day_index` The index of the day for which locally aggregated
/// Observations should be generated.
/// `report_specs` A vector of specifications identifying the reports to
/// return the number of observations for.
/// Returns a vector whose k-th element is the number of observations
/// generated for the k-th element of `report_specs`. If `report_specs`
/// is the empty vector, then an empty vector is returned.
GenerateAggregatedObservations(uint32 day_index,
vector<ReportSpec>:MAX report_specs)
-> (vector<uint64>:MAX num_obs);
/// Requests that the caller be notified after the Cobalt FIDL service
/// is in the fully-initialized state.
/// Cobalt starts serving requests before it is fully initialized. In this
/// pre-initialized state it will buffer incoming log events in memory
/// but not complete their processing. After Cobalt becomes fully
/// initialized the events in the bufer are fully processed.
/// A partial list of things that must happen before Cobalt enters the
/// fully-initialized state are:
/// - Cobalt must by notified by the timekeeper service that the system
/// clock has become accurate--usually because the time has been
/// fetched from a trusted network resource.
/// The callback to this method will be invoked after Cobalt transistions
// to the fully-initialized state. This may never happen.
ListenForInitialized() -> ();