blob: ce56663d3afdec25680b43d940e1f210de9ca992 [file] [log] [blame]
// 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;
};