Google is committed to advancing racial equity for Black communities. See how.

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.

LogCustomEvent

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.

Request

NameType
metric_id uint32
event_values vector<CustomEventValue>

Response

NameType
status Status

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 event_vector

Response

NameType
status Status

LogIntegerHistogram

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.

Request

NameType
metric_id uint32
histogram integer_histogram
event_codes event_vector

Response

NameType
status Status

LogMetricEvents

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

Request

NameType
events vector<MetricEvent>[500]

Response

NameType
status Status

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 event_vector

Response

NameType
status Status

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 event_vector

Response

NameType
status Status

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 request<MetricEventLogger>

Response

NameType
status Status

STRUCTS

CustomEventValue

Defined in fuchsia.metrics/metric_event_logger.fidl

A value for a custom event. This is used by the method LogCustomEvent().

NameTypeDescriptionDefault
dimension_name string

The name of the metric's dimension this value is for.

No default
value Value

The value for that dimension.

No default

HistogramBucket

Defined in fuchsia.metrics/metric_event_logger.fidl

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

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

No default

MetricEvent

Defined in fuchsia.metrics/metric_event_logger.fidl

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

NameTypeDescriptionDefault
metric_id uint32

ID of the metric being logged.

No default
event_codes event_vector

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

ENUMS

Status

Type: int32

Defined in fuchsia.metrics/metric_event_logger.fidl

Response codes for MetricEventLogger operations.

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

OrdinalNameTypeDescription
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

MetricEventPayload

Defined in fuchsia.metrics/metric_event_logger.fidl

The variadic part of a MetricEvent.

NameTypeDescription
count uint64

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

integer_value int64

The integer measured, see LogInteger().

histogram integer_histogram

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

string_value string[256]

The string to log, see LogString().

Value

Defined in fuchsia.metrics/metric_event_logger.fidl

A custom event value that may be a string, int, double, or index.

NameTypeDescription
string_value string
int_value int64
double_value float64
index_value uint32

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

TYPE ALIASES

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

integer_histogram vector[MAX_HISTOGRAM_BUCKETS]

A histogram that assigns a count to each of several integer ranges. The order of the vector is immaterial.