// Copyright 2020 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.
/// This file contains interfaces that allow clients to log events that are
/// associated with metrics. These events are collected and later analyzed.
/// Metrics are organized under a Project, which are associated with a Customer.
/// Each of these objects has an integer ID and those IDs are used as parameters
/// in the methods in this file. Metrics can also have one or more dimensions
/// associated with them, which are then passed as a vector of event codes when
/// logging the event.
///
/// Usage: First use MetricEventLoggerFactory to get a MetricEventLogger for your
/// project. Then you log Events as they occur, using the Log*() methods on it.
///
/// The default implementation of this service in Fuchsia is Cobalt. For more
/// details on how to use these interfaces with Cobalt, see README.md.
@available(added=7)
library fuchsia.metrics;

/// The maximum size of a single Event is 100 KB.
const MAX_BYTES_PER_EVENT int64 = 102400;

/// This is intended as a reasonable maximum number of histogram buckets per
/// event.
const MAX_HISTOGRAM_BUCKETS uint32 = 500;

/// Maximum number of events that may be logged in a single FIDL call.
const MAX_BATCHED_EVENTS uint32 = 500;

/// String events should not be longer than this.
const MAX_STRING_EVENT_SIZE uint32 = 256;

/// Maximum number of event codes that can be associated with a single event.
const MAX_METRIC_DIMENSIONS uint32 = 10;

/// Maximum number of experiment ids that can be provided to a single logger.
const MAX_EXPERIMENT_IDS uint32 = 100;

/// Error codes for MetricEventLogger operations.
type Error = strict enum : int32 {
    /// For example, the supplied metric id is invalid.
    INVALID_ARGUMENTS = 1;

    /// An attempt was made to log an Event whose serialized size exceeds
    /// MAX_BYTES_PER_EVENT.
    EVENT_TOO_BIG = 2;

    /// The logger's local buffer is temporarily full and cannot handle any more
    /// Events at this time. Try again later. This condition should be rare.
    BUFFER_FULL = 3;

    // The logger has received a ShutDown signal and will not accept any more
    // events.
    SHUT_DOWN = 4;

    /// Catch-all for unexpected errors.
    INTERNAL_ERROR = -1;
};

/// A specification identifying a project to log events for.
type ProjectSpec = table {
    /// The customer ID. If omitted (i.e. set to 0) then it defaults to the
    /// customer ID for the default "fuchsia" customer.
    1: customer_id uint32;

    /// The ID of the project.
    2: project_id uint32;
};

/// A factory that is used to create a MetricEventLogger for a specific project.
@discoverable
protocol MetricEventLoggerFactory {
    /// Create a MetricEventLogger for the project specified by `project_spec`.
    CreateMetricEventLogger(resource struct {
        project_spec ProjectSpec;
        logger server_end:MetricEventLogger;
    }) -> (struct {}) error Error;

    /// Create a MetricEventLogger with experiment metadata.
    ///
    /// This temporary method exposes experiment data to Cobalt directly from
    /// components. In the future, experiment state will be managed by the
    /// system and passed directly to Cobalt. Contact the Cobalt team before
    /// using this interface.
    ///
    /// To update experiment state create a new logger.
    CreateMetricEventLoggerWithExperiments(resource struct {
        project_spec ProjectSpec;
        experiment_ids vector<uint32>:MAX_EXPERIMENT_IDS;
        logger server_end:MetricEventLogger;
    }) -> (struct {}) error Error;
};

/// A vector of event codes. When used in one of the Log*() calls below,
/// there must be one event code for each dimension of the metric whose
/// metric_id is supplied, or else the call will return INVALID_ARGUMENTS.
alias event_vector = vector<uint32>:MAX_METRIC_DIMENSIONS;

/// A histogram that assigns a count to each of several integer ranges.
/// The order of the vector is immaterial.
alias integer_histogram = vector<HistogramBucket>:MAX_HISTOGRAM_BUCKETS;

/// A logger for events that are associated with one project's metrics.
protocol MetricEventLogger {
    /// Logs the fact that an event has occurred a number of times.
    ///
    /// `metric_id` ID of the metric being logged.
    ///
    /// `count` The number of times the event has occurred. The value should
    /// be positive as a value of 0 is ignored.
    ///
    /// `event_codes` Ordered list of parameters, one for each of the metric's
    /// dimensions. Occurrence counts with the same event codes are aggregated
    /// based on these parameters.
    LogOccurrence(struct {
        metric_id uint32;
        count uint64;
        event_codes event_vector;
    }) -> (struct {}) error Error;

    /// Logs an integer measurement.
    ///
    /// `metric_id` ID of the metric being logged.
    ///
    /// `value` The integer measurement.
    ///
    /// `event_codes` Ordered list of parameters, one for each of the metric's
    /// dimensions. Integer values with the same event codes are aggregated
    /// based on these parameters.
    LogInteger(struct {
        metric_id uint32;
        value int64;
        event_codes event_vector;
    }) -> (struct {}) error Error;

    /// Logs a histogram giving many approximate integer measurements.
    ///
    /// `metric_id` ID of the metric being logged.
    ///
    /// `histogram` The collection of approximate integer measurements.
    ///
    /// `event_codes` Ordered list of parameters, one for each of the metric's
    /// dimensions. Histograms with the same event codes are aggregated together
    /// based on these parameters.
    LogIntegerHistogram(struct {
        metric_id uint32;
        histogram integer_histogram;
        event_codes event_vector;
    }) -> (struct {}) error Error;

    /// Logs a string value that was observed.
    ///
    /// `metric_id` ID of the metric being logged.
    ///
    /// `string_value` The string to log.
    ///
    /// `event_codes` Ordered list of parameters, one for each of the metric's
    /// dimensions. Counts of logged strings are aggregated separately based on
    /// these parameters.
    LogString(struct {
        metric_id uint32;
        string_value string:MAX_STRING_EVENT_SIZE;
        event_codes event_vector;
    }) -> (struct {}) error Error;

    /// Bulk logging method, equivalent to making many of the above Log*() calls
    /// at once.
    LogMetricEvents(struct {
        events vector<MetricEvent>:MAX_BATCHED_EVENTS;
    }) -> (struct {}) error Error;

    /// Logs a custom Event.
    ///
    /// `metric_id` ID of the metric being logged.
    ///
    /// `event_values` The values for the custom Event. There must be one value
    /// for each dimension of the metric and the types of the values must
    /// be consistent with the dimensions declared in the metric definition.
    LogCustomEvent(struct {
        metric_id uint32;
        event_values vector<CustomEventValue>:MAX;
    }) -> (struct {}) error Error;
};

/// A specification of an event that occurred to be passed to LogMetricEvents().
type MetricEvent = struct {
    /// ID of the metric being logged.
    metric_id uint32;

    /// `event_codes` Ordered list of parameters, one for each of the metric's
    /// dimensions.
    event_codes event_vector;

    /// The metric-type-specific data for the event being logged.
    payload MetricEventPayload;
};

/// The variadic part of a MetricEvent.
type MetricEventPayload = flexible union {
    /// The number of times the event has occurred, see LogOccurrence().
    1: count uint64;

    /// The integer measured, see LogInteger().
    2: integer_value int64;

    /// The collection of approximate integer measurements, see
    /// LogIntegerHistogram().
    3: histogram integer_histogram;

    /// The string to log, see LogString().
    4: string_value string:MAX_STRING_EVENT_SIZE;
};

/// A value for a custom event. This is used by the method LogCustomEvent().
type CustomEventValue = struct {
    /// The name of the metric's dimension this value is for.
    dimension_name string:MAX;

    /// The value for that dimension.
    value Value;
};

/// A custom event value that may be a string, int, double, or index.
type Value = strict union {
    1: string_value string:MAX;
    2: int_value int64;
    3: double_value float64;
    4: index_value uint32;
};

/// One bucket of a histogram, used by the method LogIntegerHistogram.
type HistogramBucket = struct {
    /// The index of the bucket. The metric includes a specification
    /// of a sequence of N+1 integer-range buckets that are indexed from
    /// 0, the underflow bucket, to N, the overflow bucket.
    index uint32;

    /// The number of values in that bucket.
    count uint64;
};