sdk/fidl/fuchsia.metrics/metric_event_logger.fidl - fuchsia - Git at Google

 // 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
 closed protocol MetricEventLoggerFactory {
     /// Create a MetricEventLogger for the project specified by `project_spec`.
     strict CreateMetricEventLogger(resource struct {
         project_spec ProjectSpec;
         logger server_end:MetricEventLogger;
     }) -> () 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.
     strict CreateMetricEventLoggerWithExperiments(resource struct {
         project_spec ProjectSpec;
         experiment_ids vector<uint32>:MAX_EXPERIMENT_IDS;
         logger server_end:MetricEventLogger;
     }) -> () 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 EventVector = vector<uint32>:MAX_METRIC_DIMENSIONS;

 /// A histogram that assigns a count to each of several integer ranges.
 /// To save space/memory/bandwidth, each bucket index should only be included
 /// once, and empty buckets should not be included. The order of the vector
 /// is immaterial.
 alias IntegerHistogram = vector<HistogramBucket>:MAX_HISTOGRAM_BUCKETS;

 /// A logger for events that are associated with one project's metrics.
 closed 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.
     strict LogOccurrence(struct {
         metric_id uint32;
         count uint64;
         event_codes EventVector;
     }) -> () 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.
     strict LogInteger(struct {
         metric_id uint32;
         value int64;
         event_codes EventVector;
     }) -> () 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. Buckets
     /// that have no measurement (empty buckets) should not be sent.
     ///
     /// `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.
     strict LogIntegerHistogram(struct {
         metric_id uint32;
         histogram IntegerHistogram;
         event_codes EventVector;
     }) -> () 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.
     strict LogString(struct {
         metric_id uint32;
         string_value string:MAX_STRING_EVENT_SIZE;
         event_codes EventVector;
     }) -> () error Error;

     /// Bulk logging method, equivalent to making many of the above Log*() calls
     /// at once.
     strict LogMetricEvents(struct {
         events vector<MetricEvent>:MAX_BATCHED_EVENTS;
     }) -> () 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.
     @available(deprecated=9, removed=10)
     strict LogCustomEvent(struct {
         metric_id uint32;
         event_values vector<CustomEventValue>:MAX;
     }) -> () 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 EventVector;

     /// 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 IntegerHistogram;

     /// 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().
 @available(deprecated=9, removed=10)
 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.
 @available(deprecated=9, removed=10)
 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.
     /// To save space/memory/bandwidth, empty buckets should not be included.
     count uint64;
 };
	// 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
	closed protocol MetricEventLoggerFactory {
	/// Create a MetricEventLogger for the project specified by `project_spec`.
	strict CreateMetricEventLogger(resource struct {
	project_spec ProjectSpec;
	logger server_end:MetricEventLogger;
	}) -> () 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.
	strict CreateMetricEventLoggerWithExperiments(resource struct {
	project_spec ProjectSpec;
	experiment_ids vector<uint32>:MAX_EXPERIMENT_IDS;
	logger server_end:MetricEventLogger;
	}) -> () 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 EventVector = vector<uint32>:MAX_METRIC_DIMENSIONS;

	/// A histogram that assigns a count to each of several integer ranges.
	/// To save space/memory/bandwidth, each bucket index should only be included
	/// once, and empty buckets should not be included. The order of the vector
	/// is immaterial.
	alias IntegerHistogram = vector<HistogramBucket>:MAX_HISTOGRAM_BUCKETS;

	/// A logger for events that are associated with one project's metrics.
	closed 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.
	strict LogOccurrence(struct {
	metric_id uint32;
	count uint64;
	event_codes EventVector;
	}) -> () 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.
	strict LogInteger(struct {
	metric_id uint32;
	value int64;
	event_codes EventVector;
	}) -> () 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. Buckets
	/// that have no measurement (empty buckets) should not be sent.
	///
	/// `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.
	strict LogIntegerHistogram(struct {
	metric_id uint32;
	histogram IntegerHistogram;
	event_codes EventVector;
	}) -> () 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.
	strict LogString(struct {
	metric_id uint32;
	string_value string:MAX_STRING_EVENT_SIZE;
	event_codes EventVector;
	}) -> () error Error;

	/// Bulk logging method, equivalent to making many of the above Log*() calls
	/// at once.
	strict LogMetricEvents(struct {
	events vector<MetricEvent>:MAX_BATCHED_EVENTS;
	}) -> () 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.
	@available(deprecated=9, removed=10)
	strict LogCustomEvent(struct {
	metric_id uint32;
	event_values vector<CustomEventValue>:MAX;
	}) -> () 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 EventVector;

	/// 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 IntegerHistogram;

	/// 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().
	@available(deprecated=9, removed=10)
	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.
	@available(deprecated=9, removed=10)
	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.
	/// To save space/memory/bandwidth, empty buckets should not be included.
	count uint64;
	};