<br />

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](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=107)*

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

<br />

### 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` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#EventVector` |

#### Response

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#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` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#IntegerHistogram` |
| `event_codes` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#EventVector` |

#### Response

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#MetricEventLogger_LogIntegerHistogram_Result` |

### LogMetricEvents

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

#### Request

| Name | Type |
|---|---|
| `events` | `vector<https://fuchsia.dev/reference/fidl/fuchsia.metrics#MetricEvent>:500` |

#### Response

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#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` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#EventVector` |

#### Response

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#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` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#EventVector` |

#### Response

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#MetricEventLogger_LogString_Result` |

## MetricEventLoggerFactory

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=73)*

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

<br />

### CreateMetricEventLogger

Create a MetricEventLogger for the project specified by `project_spec`.

#### Request

| Name | Type |
|---|---|
| `project_spec` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#ProjectSpec` |
| `logger` | `server_end:https://fuchsia.dev/reference/fidl/fuchsia.metrics#MetricEventLogger` |

#### Response

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#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` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#ProjectSpec` |
| `experiment_ids` | `vector<uint32>:100` |
| `logger` | `server_end:https://fuchsia.dev/reference/fidl/fuchsia.metrics#MetricEventLogger` |

#### Response

| Name | Type |
|---|---|
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#MetricEventLoggerFactory_CreateMetricEventLoggerWithExperiments_Result` |

## **STRUCTS**

### HistogramBucket

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=239)*

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

<br />

| 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](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=191)*

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

<br />

| Field | Type | Description | Default |
|---|---|---|---|
| `metric_id` | `uint32` | ID of the metric being logged. | No default |
| `event_codes` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#EventVector` | `event_codes` Ordered list of parameters, one for each of the metric's dimensions. | No default |
| `payload` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#MetricEventPayload` | The metric-type-specific data for the event being logged. | No default |

### MetricEventLoggerFactory_CreateMetricEventLoggerWithExperiments_Response

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=92)*

\<EMPTY\>

### MetricEventLoggerFactory_CreateMetricEventLogger_Response

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=78)*

\<EMPTY\>

### MetricEventLogger_LogIntegerHistogram_Response

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=153)*

\<EMPTY\>

### MetricEventLogger_LogInteger_Response

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=137)*

\<EMPTY\>

### MetricEventLogger_LogMetricEvents_Response

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=174)*

\<EMPTY\>

### MetricEventLogger_LogOccurrence_Response

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=122)*

\<EMPTY\>

### MetricEventLogger_LogString_Response

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=168)*

\<EMPTY\>

## **ENUMS**

### Error [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

Type: `int32`

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=41)*

Error codes for MetricEventLogger operations.

<br />

| 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](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=62)*

A specification identifying a project to log events for.

<br />

| 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](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=92)*

| Ordinal | Variant | Type | Description |
|---|---|---|---|
| ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#MetricEventLoggerFactory_CreateMetricEventLoggerWithExperiments_Response` |   |
| ### 2 | `err` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#Error` |   |

<br />

### MetricEventLoggerFactory_CreateMetricEventLogger_Result [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=78)*

| Ordinal | Variant | Type | Description |
|---|---|---|---|
| ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#MetricEventLoggerFactory_CreateMetricEventLogger_Response` |   |
| ### 2 | `err` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#Error` |   |

<br />

### MetricEventLogger_LogIntegerHistogram_Result [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=153)*

| Ordinal | Variant | Type | Description |
|---|---|---|---|
| ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#MetricEventLogger_LogIntegerHistogram_Response` |   |
| ### 2 | `err` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#Error` |   |

<br />

### MetricEventLogger_LogInteger_Result [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=137)*

| Ordinal | Variant | Type | Description |
|---|---|---|---|
| ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#MetricEventLogger_LogInteger_Response` |   |
| ### 2 | `err` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#Error` |   |

<br />

### MetricEventLogger_LogMetricEvents_Result [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=174)*

| Ordinal | Variant | Type | Description |
|---|---|---|---|
| ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#MetricEventLogger_LogMetricEvents_Response` |   |
| ### 2 | `err` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#Error` |   |

<br />

### MetricEventLogger_LogOccurrence_Result [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=122)*

| Ordinal | Variant | Type | Description |
|---|---|---|---|
| ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#MetricEventLogger_LogOccurrence_Response` |   |
| ### 2 | `err` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#Error` |   |

<br />

### MetricEventLogger_LogString_Result [strict](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=168)*

| Ordinal | Variant | Type | Description |
|---|---|---|---|
| ### 1 | `response` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#MetricEventLogger_LogString_Response` |   |
| ### 2 | `err` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#Error` |   |

<br />

### MetricEventPayload [flexible](https://fuchsia.dev/fuchsia-src/reference/fidl/language/language#strict-vs-flexible)

*Defined in [fuchsia.metrics/metric_event_logger.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=204)*

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` | `https://fuchsia.dev/reference/fidl/fuchsia.metrics#IntegerHistogram` | The collection of approximate integer measurements, see LogIntegerHistogram(). |
| ### 4 | `string_value` | `string:256` | The string to log, see LogString(). |

<br />

## **CONSTANTS**

| Name | Value | Type | Description |
|---|---|---|---|
| [MAX_BATCHED_EVENTS](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=28) | `500` | `uint32` | Maximum number of events that may be logged in a single FIDL call. |
| [MAX_BYTES_PER_EVENT](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=21) | `102400` | `int64` | The maximum size of a single Event is 100 KB. |
| [MAX_EXPERIMENT_IDS](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=37) | `100` | `uint32` | Maximum number of experiment ids that can be provided to a single logger. |
| [MAX_HISTOGRAM_BUCKETS](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=25) | `500` | `uint32` | This is intended as a reasonable maximum number of histogram buckets per event. |
| [MAX_METRIC_DIMENSIONS](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=34) | `10` | `uint32` | Maximum number of event codes that can be associated with a single event. |
| [MAX_STRING_EVENT_SIZE](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=31) | `256` | `uint32` | String events should not be longer than this. |

## **ALIASES**

| Name | Value | Description |
|---|---|---|
| [EventVector](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=98) | `vector`\[`https://fuchsia.dev/reference/fidl/fuchsia.metrics#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](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.metrics/metric_event_logger.fidl;l=104) | `vector`\[`https://fuchsia.dev/reference/fidl/fuchsia.metrics#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. |