blob: c202cc2b1f72f624a349fde8b74b2bf3d181d054 [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.
type ReportSpec = table {
/// The customer ID, as specified in Cobalt's metrics registry.
1: customer_id uint32;
/// The ID of the project, as specified in Cobalt's metrics registry.
2: project_id uint32;
/// The ID of the metric, as specified in Cobalt's metrics registry.
3: metric_id uint32;
/// The ID of the report, as specified in Cobalt's metrics registry.
4: report_id uint32;
/// 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() -> (struct {
success bool;
/// 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(struct {
max_wait_seconds uint32;
}) -> ();
/// These diagnostic stats are mostly useful in a testing environment but
/// may possibly prove useful in production also.
GetNumSendAttempts() -> (struct {
num uint32;
GetFailedSendAttempts() -> (struct {
num uint32;
GetNumObservationsAdded() -> (struct {
num_obs uint64;
GetNumEventAggregatorRuns() -> (struct {
num_runs uint64;
/// 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(struct {
day_index uint32;
report_specs vector<ReportSpec>:MAX;
}) -> (struct {
num_obs vector<uint64>:MAX;
/// 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() -> ();