// 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.
library fuchsia.metrics;

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

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

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

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

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

/// Response codes for MetricEventLogger operations.
enum Status : int32 {
    OK = 0;

    /// 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.
table ProjectSpec {
    /// The customer ID. If omitted (i.e. set to 0) then it defaults to the
    /// customer ID for the default "fuchsia" customer.
    1: uint32 customer_id;

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

/// 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(ProjectSpec project_spec,
                            request<MetricEventLogger> logger)
        -> (Status status);
};

/// 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(uint32 metric_id, uint64 count, event_vector event_codes)
        -> (Status status);

    /// 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(uint32 metric_id, int64 value, event_vector event_codes)
        -> (Status status);

    /// 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(uint32 metric_id, integer_histogram histogram,
                        event_vector event_codes)
        -> (Status status);

    /// 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(uint32 metric_id, string:MAX_STRING_EVENT_SIZE string_value,
              event_vector event_codes)
        -> (Status status);

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

    /// 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(uint32 metric_id, vector<CustomEventValue>:MAX event_values)
        -> (Status status);
};

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

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

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

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

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

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

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

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

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

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

/// One bucket of a histogram, used by the method LogIntegerHistogram.
struct HistogramBucket {
    /// 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.
    uint32 index;

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