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.

Added: 7

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

NameType
metric_id uint32
value int64
event_codes EventVector

Response

NameType
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

NameType
metric_id uint32
histogram IntegerHistogram
event_codes EventVector

Response

NameType
payload MetricEventLogger_LogIntegerHistogram_Result

LogMetricEvents

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

Request

NameType
events vector<MetricEvent>[500]

Response

NameType
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

NameType
metric_id uint32
count uint64
event_codes EventVector

Response

NameType
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

NameType
metric_id uint32
string_value string[256]
event_codes EventVector

Response

NameType
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

NameType
project_spec ProjectSpec
logger server_end<MetricEventLogger>

Response

NameType
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

NameType
project_spec ProjectSpec
experiment_ids vector<uint32>[100]
logger server_end<MetricEventLogger>

Response

NameType
payload MetricEventLoggerFactory_CreateMetricEventLoggerWithExperiments_Result

STRUCTS

HistogramBucket

Defined in fuchsia.metrics/metric_event_logger.fidl

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

FieldTypeDescriptionDefault
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().

FieldTypeDescriptionDefault
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.

NameValueDescription
1

For example, the supplied metric id is invalid.

2

An attempt was made to log an Event whose serialized size exceeds MAX_BYTES_PER_EVENT.

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.

4
-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.

OrdinalFieldTypeDescription
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.

project_id uint32

The ID of the project.

UNIONS

MetricEventLoggerFactory_CreateMetricEventLoggerWithExperiments_Result strict

Defined in fuchsia.metrics/metric_event_logger.fidl

OrdinalVariantTypeDescription
response MetricEventLoggerFactory_CreateMetricEventLoggerWithExperiments_Response
err Error

MetricEventLoggerFactory_CreateMetricEventLogger_Result strict

Defined in fuchsia.metrics/metric_event_logger.fidl

OrdinalVariantTypeDescription
response MetricEventLoggerFactory_CreateMetricEventLogger_Response
err Error

MetricEventLogger_LogIntegerHistogram_Result strict

Defined in fuchsia.metrics/metric_event_logger.fidl

OrdinalVariantTypeDescription
response MetricEventLogger_LogIntegerHistogram_Response
err Error

MetricEventLogger_LogInteger_Result strict

Defined in fuchsia.metrics/metric_event_logger.fidl

OrdinalVariantTypeDescription
response MetricEventLogger_LogInteger_Response
err Error

MetricEventLogger_LogMetricEvents_Result strict

Defined in fuchsia.metrics/metric_event_logger.fidl

OrdinalVariantTypeDescription
response MetricEventLogger_LogMetricEvents_Response
err Error

MetricEventLogger_LogOccurrence_Result strict

Defined in fuchsia.metrics/metric_event_logger.fidl

OrdinalVariantTypeDescription
response MetricEventLogger_LogOccurrence_Response
err Error

MetricEventLogger_LogString_Result strict

Defined in fuchsia.metrics/metric_event_logger.fidl

OrdinalVariantTypeDescription
response MetricEventLogger_LogString_Response
err Error

MetricEventPayload flexible

Defined in fuchsia.metrics/metric_event_logger.fidl

The variadic part of a MetricEvent.

OrdinalVariantTypeDescription
count uint64

The number of times the event has occurred, see LogOccurrence().

integer_value int64

The integer measured, see LogInteger().

histogram IntegerHistogram

The collection of approximate integer measurements, see LogIntegerHistogram().

string_value string[256]

The string to log, see LogString().

CONSTANTS

NameValueTypeDescription
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

NameValueDescription
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.