fuchsia.metrics

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.

PROTOCOLS

MetricEventLogger

Defined in fuchsia.metrics/metric_event_logger.fidl

A logger for events that are associated with one project's metrics.

LogInteger

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.

Request

Name	Type
metric_id	uint32
value	int64
event_codes	EventVector

Response

Name	Type
payload	MetricEventLogger_LogInteger_Result

LogIntegerHistogram

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.

Request

Name	Type
metric_id	uint32
histogram	IntegerHistogram
event_codes	EventVector

Response

Name	Type
payload	MetricEventLogger_LogIntegerHistogram_Result

LogMetricEvents

Bulk logging method, equivalent to making many of the above Log*() calls at once.

Request

Name	Type
events	vector<MetricEvent>:500

Response

Name	Type
payload	MetricEventLogger_LogMetricEvents_Result

LogOccurrence

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.

Request

Name	Type
metric_id	uint32
count	uint64
event_codes	EventVector

Response

Name	Type
payload	MetricEventLogger_LogOccurrence_Result

LogString

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.

Request

Name	Type
metric_id	uint32
string_value	string:256
event_codes	EventVector

Response

Name	Type
payload	MetricEventLogger_LogString_Result

MetricEventLoggerFactory

Defined in fuchsia.metrics/metric_event_logger.fidl

A factory that is used to create a MetricEventLogger for a specific project.

CreateMetricEventLogger

Create a MetricEventLogger for the project specified by project_spec.

Request

Name	Type
project_spec	ProjectSpec
logger	server_end:MetricEventLogger

Response

Name	Type
payload	MetricEventLoggerFactory_CreateMetricEventLogger_Result

CreateMetricEventLoggerWithExperiments

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.

Request

Name	Type
project_spec	ProjectSpec
experiment_ids	vector<uint32>:100
logger	server_end:MetricEventLogger

Response

Name	Type
payload	MetricEventLoggerFactory_CreateMetricEventLoggerWithExperiments_Result

STRUCTS

HistogramBucket

Defined in fuchsia.metrics/metric_event_logger.fidl

One bucket of a histogram, used by the method LogIntegerHistogram.

Field	Type	Description	Default
index	uint32	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.	No default
count	uint64	The number of values in that bucket. To save space/memory/bandwidth, empty buckets should not be included.	No default

MetricEvent

Defined in fuchsia.metrics/metric_event_logger.fidl

A specification of an event that occurred to be passed to LogMetricEvents().

Field	Type	Description	Default
metric_id	uint32	ID of the metric being logged.	No default
event_codes	EventVector	event_codes Ordered list of parameters, one for each of the metric's dimensions.	No default
payload	MetricEventPayload	The metric-type-specific data for the event being logged.	No default

MetricEventLoggerFactory_CreateMetricEventLoggerWithExperiments_Response

Defined in fuchsia.metrics/metric_event_logger.fidl

<EMPTY>

MetricEventLoggerFactory_CreateMetricEventLogger_Response

Defined in fuchsia.metrics/metric_event_logger.fidl

<EMPTY>

MetricEventLogger_LogIntegerHistogram_Response

Defined in fuchsia.metrics/metric_event_logger.fidl

<EMPTY>

MetricEventLogger_LogInteger_Response

Defined in fuchsia.metrics/metric_event_logger.fidl

<EMPTY>

MetricEventLogger_LogMetricEvents_Response

Defined in fuchsia.metrics/metric_event_logger.fidl

<EMPTY>

MetricEventLogger_LogOccurrence_Response

Defined in fuchsia.metrics/metric_event_logger.fidl

<EMPTY>

MetricEventLogger_LogString_Response

Defined in fuchsia.metrics/metric_event_logger.fidl

<EMPTY>

ENUMS

Error strict

Type: int32

Defined in fuchsia.metrics/metric_event_logger.fidl

Error codes for MetricEventLogger operations.

Name	Value	Description
INVALID_ARGUMENTS	1	For example, the supplied metric id is invalid.
EVENT_TOO_BIG	2	An attempt was made to log an Event whose serialized size exceeds MAX_BYTES_PER_EVENT.
BUFFER_FULL	3	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.
SHUT_DOWN	4
INTERNAL_ERROR	-1	Catch-all for unexpected errors.

TABLES

ProjectSpec

Defined in fuchsia.metrics/metric_event_logger.fidl

A specification identifying a project to log events for.

Ordinal	Field	Type	Description
1	customer_id	uint32	The customer ID. If omitted (i.e. set to 0) then it defaults to the customer ID for the default "fuchsia" customer.
2	project_id	uint32	The ID of the project.

UNIONS

MetricEventLoggerFactory_CreateMetricEventLoggerWithExperiments_Result strict

Defined in fuchsia.metrics/metric_event_logger.fidl

Ordinal	Variant	Type	Description
1	response	MetricEventLoggerFactory_CreateMetricEventLoggerWithExperiments_Response
2	err	Error

MetricEventLoggerFactory_CreateMetricEventLogger_Result strict

Defined in fuchsia.metrics/metric_event_logger.fidl

Ordinal	Variant	Type	Description
1	response	MetricEventLoggerFactory_CreateMetricEventLogger_Response
2	err	Error

MetricEventLogger_LogIntegerHistogram_Result strict

Defined in fuchsia.metrics/metric_event_logger.fidl

Ordinal	Variant	Type	Description
1	response	MetricEventLogger_LogIntegerHistogram_Response
2	err	Error

MetricEventLogger_LogInteger_Result strict

Defined in fuchsia.metrics/metric_event_logger.fidl

Ordinal	Variant	Type	Description
1	response	MetricEventLogger_LogInteger_Response
2	err	Error

MetricEventLogger_LogMetricEvents_Result strict

Defined in fuchsia.metrics/metric_event_logger.fidl

Ordinal	Variant	Type	Description
1	response	MetricEventLogger_LogMetricEvents_Response
2	err	Error

MetricEventLogger_LogOccurrence_Result strict

Defined in fuchsia.metrics/metric_event_logger.fidl

Ordinal	Variant	Type	Description
1	response	MetricEventLogger_LogOccurrence_Response
2	err	Error

MetricEventLogger_LogString_Result strict

Defined in fuchsia.metrics/metric_event_logger.fidl

Ordinal	Variant	Type	Description
1	response	MetricEventLogger_LogString_Response
2	err	Error

MetricEventPayload flexible

Defined in fuchsia.metrics/metric_event_logger.fidl

The variadic part of a MetricEvent.

Ordinal	Variant	Type	Description
1	count	uint64	The number of times the event has occurred, see LogOccurrence().
2	integer_value	int64	The integer measured, see LogInteger().
3	histogram	IntegerHistogram	The collection of approximate integer measurements, see LogIntegerHistogram().
4	string_value	string:256	The string to log, see LogString().

CONSTANTS

Name	Value	Type	Description
MAX_BATCHED_EVENTS	500	uint32	Maximum number of events that may be logged in a single FIDL call.
MAX_BYTES_PER_EVENT	102400	int64	The maximum size of a single Event is 100 KB.
MAX_EXPERIMENT_IDS	100	uint32	Maximum number of experiment ids that can be provided to a single logger.
MAX_HISTOGRAM_BUCKETS	500	uint32	This is intended as a reasonable maximum number of histogram buckets per event.
MAX_METRIC_DIMENSIONS	10	uint32	Maximum number of event codes that can be associated with a single event.
MAX_STRING_EVENT_SIZE	256	uint32	String events should not be longer than this.

ALIASES

Name	Value	Description
EventVector	vector[MAX_METRIC_DIMENSIONS]	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.
IntegerHistogram	vector[MAX_HISTOGRAM_BUCKETS]	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.