fuchsia.cobalt

Cobalt is the Fuchsia service used to log, collect and analyze metrics. The two main pillars of Cobalt are protecting user privacy and providing high-quality, aggregate metrics to serve system and component software developers' needs.

This file contains interfaces that allow clients to log Events to Cobalt.

To use Cobalt, you must have a Project and one or more Metrics registered with the Cobalt registration system. You must also register one or more Reports in order to see the results of your logging aggregated over all Fuchsia devices. Registration of Projects, Metrics and Reports consists of entries in the YAML files in this repo: https:///cobalt-analytics.googlesource.com/config/. In a Garnet checkout that is mapped to ///third_party/cobalt_config. Each registered object has an integer ID and those IDs are used as parameters in the methods in this file.

While Cobalt's code and registration files are open source, the running system being managed by the Cobalt team is currently intended to be used by software engineers at Google in order to collect metrics in a way that preserves our users' privacy. If you are a Google software engineer please see our internal user guide or ask for assistance from the Cobalt team.

Usage: First use LoggerFactory to get a Logger for your project. Then you log Events using the Log*() methods. Events are accumulated by the cobalt FIDL service and periodically Observations, derived from the logged Events, are sent to the Cobalt server, where they are used to generate Reports.

PROTOCOLS

Controller

Defined in fuchsia.cobalt/cobalt_controller.fidl

The Controller is primarily useful for testing the Cobalt service. Cobalt clients should use the Logger.

BlockUntilEmpty

The Cobalt FIDL service will block, not processing any further FIDL requests or responses, on either this interface or the Logger interface, until either max_wait_seconds have elapsed or the Cobalt service's worker thread has successfully sent all previously added Observations to the Shuffler. The response will be returned after the blocking period has ended. Note that this method does not request an expedited send and so it is possible that the worker thread is currently waiting for the next scheduled send time and so the empty state will not be achieved prior that time.

Request

Name	Type
`max_wait_seconds`	`uint32`

Response

Name	Type

GenerateAggregatedObservations

Triggers Cobalt to generate Observations based on locally aggregated event data and write them to the local ObservationStore. In a non-test environment this would normally be done periodically by a background thread. In a test environment this method should be invoked against an instance of the Cobalt FIDL service that was passed the flag --start_event_aggregator_worker=false.

day_index The index of the day for which locally aggregated Observations should be generated.

report_ids A vector of report IDs.

Returns a vector whose k-th element is the number of observations generated for the k-th element of report_ids. If report_ids is the empty vector, then an empty vector is returned.

Request

Name	Type
`day_index`	`uint32`
`report_ids`	`vector<uint32>`

Response

Name	Type
`num_obs`	`vector<uint64>`

GetFailedSendAttempts

Request

Name	Type

Response

Name	Type
`num`	`uint32`

GetNumEventAggregatorRuns

Request

Name	Type

Response

Name	Type
`num_runs`	`uint64`

GetNumObservationsAdded

Request

Name	Type

Response

Name	Type
`num_obs`	`uint64`

GetNumSendAttempts

These diagnostic stats are mostly useful in a testing environment but may possibly prove useful in production also.

Request

Name	Type

Response

Name	Type
`num`	`uint32`

ListenForInitialized

Requests that the caller be notified after the Cobalt FIDL service is in the fully-initialized state.

Cobalt starts serving requests before it is fully initialized. In this pre-initialized state it will buffer incoming log events in memory but not complete their processing. After Cobalt becomes fully initialized the events in the bufer are fully processed.

A partial list of things that must happen before Cobalt enters the fully-initialized state are:

Cobalt must by notified by the timekeeper service that the system clock has become accurate--usually because the time has been fetched from a trusted network resource.

The callback to this method will be invoked after Cobalt transistions

Request

Name	Type

Response

Name	Type

RequestSendSoon

Requests that the collection of Observations that are currently cached locally be sent to the Cobalt server soon. Cobalt will send the Observations in one or more batches and will retry several times upon failure. The response occurs only after that procedure is completed. A return value of true indicates that all Observations were successfully sent. A return value of false indicates otherwise.

Request

Name	Type

Response

Name	Type
`success`	`bool`

Logger

Defined in fuchsia.cobalt/cobalt.fidl

Logger is an extension of the LoggerBase interface that adds some additional methods that do not naturally conform to the Simple layout. We opt for a natural easy-to-understand interface at the cost of not being "Simple". See the interface LoggerSimple below for versions of some of these methods that do conform to the Simple layout.

EndTimer

This method is part of Cobalt's helper service for measuring the time delta between two events that occur in different processes. This ends the timer. A corresponding invocation of StartTimer() with the same timer_id starts the timer. After both StartTimer() and EndTimer() have been invoked, LogElapsedTime() will be invoked with the difference between the end timestamp and the start timestamp as the value of duration_microseconds. It is OK if Cobalt receives the EndTimer() call before the StartTimer() call.

timer_id The ID of the timer being ended. This is an arbitrary non-empty string provided by the caller and it is the caller's responsibility to ensure that Cobalt receives a pair of StartTimer(), EndTimer() calls with this id before the timeout and without any intervening additional calls to StartTimer() or EndTimer() using the same id. Once such a pair is received Cobalt will delete the timer with this ID and after that the ID may be re-used.

timestamp The timestamp to set as the end of the timer. The units must be microseconds. The absolute value does not matter, only the difference between the end and start timestamps will be used.

timeout_s The number of seconds Cobalt should wait to receive the corresponding EndTimer() call with the same timer_id. If Cobalt has already received the corresponding EndTimer() call before receiving this StartTimer() call then this value is ignored as the timeout has already been set by the EndTimer() call. If Cobalt does not receive the corresponding EndTimer() call before the timeout then the timer will be deleted and this invocation of StartTimer() will be forgotten. Must be a positive value less than 300.

status Returns OK on success. There are two success cases: (i) Cobalt does not currently have any timers with the given timer_id. In that case this call creates a new timer with the given ID and end timestamp. (ii) Cobalt currently has a timer with the given timer_id for which it has received exactly one StartTimer() call and no EndTimer() calls. In this case Cobalt will delete the timer and invoke LogElapsedTime() using the difference between the end timestamp and the start timestamp as the value of duration_micros. It is ok if this value is negative. Returns INVALID_ARGUMENTS if timer_id is empty, the timeout is not positive and less than 5 minutes or Cobalt currently has a timer with the given timer_ID and it already has an end timestamp. In the last case Cobalt will delete the timer with the given timer_id and this invocation of EndTimer() will be forgotten. Any error returned by LogElapsedTime() may also be returned by this method.

Request

Name	Type
`timer_id`	`string[64]`
`timestamp`	`uint64`
`timeout_s`	`uint32`

Response

Name	Type
`status`	`Status`

LogCobaltEvent

Logs a CobaltEvent. This method offers an alternative API to Cobalt that uses a single method with a variadic parameter instead of the multiple methods defined above. The reason to use this method is that a CobaltEvent allows multiple event codes to be specified whereas the methods above allow only a single event code.

Request

Name	Type
`event`	`CobaltEvent`

Response

Name	Type
`status`	`Status`

LogCobaltEvents

Logs a list of CobaltEvents. This method is equivalent to invoking LogCobaltEvent() multiple times but is more efficient as it requires only a single FIDL call.

Request

Name	Type
`events`	`vector<CobaltEvent>[500]`

Response

Name	Type
`status`	`Status`

LogCustomEvent

Logs a custom Event. The semantics of the Metric are specified in the Metric definition.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type CUSTOM.

event_values The values for the custom Event. There is one value for each dimension of the Metric. The number and types of the values must be consistent with the dimensions declared in the Metric definition.

Request

Name	Type
`metric_id`	`uint32`
`event_values`	`vector<CustomEventValue>`

Response

Name	Type
`status`	`Status`

LogElapsedTime

Logs that an event lasted a given amount of time.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type ELAPSED_TIME.

event_code The index of the event that occurred. The indexed set of all event codes and their labels is specified in the metric definition.

component Optionally, a component associated with the event may also be logged. Any notion of component that makes sense may be used or use the empty string if there is no natural notion of component.

elapsed_micros The elapsed time of the event, specified as a number of microseconds.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`elapsed_micros`	`int64`

Response

Name	Type
`status`	`Status`

LogEvent

Logs the fact that an event has occurred.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type EVENT_OCCURRED.

event_code The index of the event that occurred. The indexed set of all event codes and their labels is specified in the metric definition.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`

Response

Name	Type
`status`	`Status`

LogEventCount

Logs that an event has occurred a given number of times.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type EVENT_COUNT.

event_code The index of the event that occurred. The indexed set of all event codes and their labels is specified in the metric definition.

period_duration_micros Optionally, the period of time over which the count events occurred may be logged. If this is not relevant the value may be set to 0. Otherwise specify the period duration as a number of microseconds.

count The number of times the event occurred. One may choose to always set this value to 1 and always set

period_duration_micros to 0 in order to achieve a semantics similar to the LogEventOccurred() method, but with a component.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`period_duration_micros`	`int64`
`count`	`int64`

Response

Name	Type
`status`	`Status`

LogFrameRate

Logs a measured average frame rate.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type FRAME_RATE.

event_code The index of the event that associated with the frame-rate measurement. The indexed set of all event codes and their labels is specified in the metric definition.

component Optionally, a component associated with the frame-rate measurement may also be logged. Any notion of component that makes sense may be used or use the empty string if there is no natural notion of component.

fps The average-frame rate in frames-per-second.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`fps`	`float32`

Response

Name	Type
`status`	`Status`

LogIntHistogram

Logs a histogram over a set of integer buckets. The meaning of the Metric and the buckets is specified in the Metric definition.

This method is intended to be used in situations where the client wishes to aggregate a large number of integer-valued measurements in-process, prior to submitting the data to Cobalt. One reason a client may wish to do this is that the measurements occur with very high frequency and it is not practical to make a FIDL call for each individual measurement.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type INT_HISTOGRAM.

event_code The index of the event type associated with the integer-valued measurement. The indexed set of all event codes and their labels is specified in the metric definition.

component Optionally, a component associated with integer-valued measurements may also be logged. Any notion of component that makes sense may be used or use the empty string if there is no natural notion of component.

histogram The histogram to log. Each HistogramBucket gives the count for one bucket of the histogram. The definitions of the buckets is given in the Metric definition.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`histogram`	`vector<HistogramBucket>[500]`

Response

Name	Type
`status`	`Status`

LogMemoryUsage

Logs a measured memory usage.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type MEMORY_USAGE.

event_code The index of the event type associated with the memory usage. The indexed set of all event codes and their labels is specified in the metric definition.

component Optionally, a component associated with the memory usage may also be logged. Any notion of component that makes sense may be used or use the empty string if there is no natural notion of component.

bytes The memory used, in bytes.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`bytes`	`int64`

Response

Name	Type
`status`	`Status`

StartTimer

This method is part of Cobalt's helper service for measuring the time delta between two events that occur in different processes. This starts the timer. A corresponding invocation of EndTimer() with the same timer_id ends the timer. After both StartTimer() and EnvdTimer() have been invoked, LogElapsedTime() will be invoked with the difference between the end timestamp and the start timestamp as the value of duration_microseconds. It is OK if Cobalt receives the EndTimer() call before the StartTimer() call.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type ELAPSED_TIME.

event_code The index of the event type to associate with the elapsed time. This is passed to LogElapsedTime()

component Optionally, a component associated with the event may also be logged. See the description at LogElapsedTime().

timer_id The ID of the timer being started. This is an arbitrary non-empty string provided by the caller and it is the caller's responsibility to ensure that Cobalt receives a pair of StartTimer(), EndTimer() calls with this id before the timeout and without any intervening additional calls to StartTimer() or EndTimer() using the same id. Once such a pair is received Cobalt will delete the timer with this ID and after that the ID may be re-used.

timestamp The timestamp to set as the start of the timer. The units must be microseconds. The absolute value does not matter, only the difference between the end and start timestamps will be used.

status Returns OK on success. There are two success cases: (i) Cobalt does not currently have any timers with the given timer_id. In that case this call creates a new timer with the given ID and start timestamp. (ii) Cobalt currently has a timer with the given timer_id for which it has received exactly one EndTimer() call and no StartTimer() calls. In this case Cobalt will delete the timer and invoke LogElapsedTime() using the difference between the end timestamp and the start timestamp as the value of duration_micros. It is ok if this value is negative. Returns INVALID_ARGUMENTS if timer_id is empty, the timeout is not positive and less than 5 minutes or Cobalt currently has a timer with the given timer_ID and it already has a start timestamp. In the last case Cobalt will delete the timer with the given timer_id and this invocation of StartTimer() will be forgotten. Any error returned by LogElapsedTime() may also be returned by this method.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`timer_id`	`string[64]`
`timestamp`	`uint64`
`timeout_s`	`uint32`

Response

Name	Type
`status`	`Status`

LoggerBase

Defined in fuchsia.cobalt/cobalt.fidl

LoggerBase and its extensions are used to log Events to the Cobalt system. The Cobalt FIDL service stores the Events locally for some period of time, processes the Events to form Observations, and periodically uploads batches of Observations to the Cobalt server. The Cobalt server processes the Observations and generates Reports. See [TODO(rudominer)] for more description of the Cobalt server and Reports.

LoggerBase or one of its extensions is associated with a single Cobalt project.

This interface conforms to the Simple layout so that Simple bindings may be generated for it. For the full interfaces, see Logger and LoggerSimple below.

EndTimer

timestamp The timestamp to set as the end of the timer. The units must be microseconds. The absolute value does not matter, only the difference between the end and start timestamps will be used.

Request

Name	Type
`timer_id`	`string[64]`
`timestamp`	`uint64`
`timeout_s`	`uint32`

Response

Name	Type
`status`	`Status`

LogElapsedTime

Logs that an event lasted a given amount of time.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type ELAPSED_TIME.

event_code The index of the event that occurred. The indexed set of all event codes and their labels is specified in the metric definition.

elapsed_micros The elapsed time of the event, specified as a number of microseconds.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`elapsed_micros`	`int64`

Response

Name	Type
`status`	`Status`

LogEvent

Logs the fact that an event has occurred.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type EVENT_OCCURRED.

event_code The index of the event that occurred. The indexed set of all event codes and their labels is specified in the metric definition.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`

Response

Name	Type
`status`	`Status`

LogEventCount

Logs that an event has occurred a given number of times.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type EVENT_COUNT.

event_code The index of the event that occurred. The indexed set of all event codes and their labels is specified in the metric definition.

count The number of times the event occurred. One may choose to always set this value to 1 and always set

period_duration_micros to 0 in order to achieve a semantics similar to the LogEventOccurred() method, but with a component.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`period_duration_micros`	`int64`
`count`	`int64`

Response

Name	Type
`status`	`Status`

LogFrameRate

Logs a measured average frame rate.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type FRAME_RATE.

event_code The index of the event that associated with the frame-rate measurement. The indexed set of all event codes and their labels is specified in the metric definition.

fps The average-frame rate in frames-per-second.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`fps`	`float32`

Response

Name	Type
`status`	`Status`

LogMemoryUsage

Logs a measured memory usage.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type MEMORY_USAGE.

event_code The index of the event type associated with the memory usage. The indexed set of all event codes and their labels is specified in the metric definition.

bytes The memory used, in bytes.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`bytes`	`int64`

Response

Name	Type
`status`	`Status`

StartTimer

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type ELAPSED_TIME.

event_code The index of the event type to associate with the elapsed time. This is passed to LogElapsedTime()

component Optionally, a component associated with the event may also be logged. See the description at LogElapsedTime().

timestamp The timestamp to set as the start of the timer. The units must be microseconds. The absolute value does not matter, only the difference between the end and start timestamps will be used.

status Returns OK on success. There are two success cases: (i) Cobalt does not currently have any timers with the given timer_id. In that case this call creates a new timer with the given ID and start timestamp. (ii) Cobalt currently has a timer with the given timer_id for which it has received exactly one EndTimer() call and no StartTimer() calls. In this case Cobalt will delete the timer and invoke LogElapsedTime() using the difference between the end timestamp and the start timestamp as the value of duration_micros. It is ok if this value is negative. Returns INVALID_ARGUMENTS if timer_id is empty, the timeout is not positive and less than 5 minutes or Cobalt currently has a timer with the given timer_ID and it already has a start timestamp. In the last case Cobalt will delete the timer with the given timer_id and this invocation of StartTimer() will be forgotten. Any error returned by LogElapsedTime() may also be returned by this method.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`timer_id`	`string[64]`
`timestamp`	`uint64`
`timeout_s`	`uint32`

Response

Name	Type
`status`	`Status`

LoggerFactory

Defined in fuchsia.cobalt/cobalt.fidl

LoggerFactory creates Loggers.

CreateLoggerFromProjectId

Creates a Logger for the project with the given ID, using the state of the metrics registry that is bundled with Cobalt. The project must be in the "fuchsia" customer.

project_id The ID of the client's Cobalt project.

status Returns OK on success or INVALID_ARGUMENTS if there is no project with the given ID in the version of the metrics registry that is bundled with Cobalt.

Request

Name	Type
`project_id`	`uint32`
`logger`	`request<Logger>`

Response

Name	Type
`status`	`Status`

CreateLoggerFromProjectSpec

Creates a Logger for the project specified, using the state of the metrics registry that is bundled with Cobalt.

customer_id The ID of the client's Cobalt customer.

project_id The ID of the client's Cobalt project.

status Returns OK on success or INVALID_ARGUMENTS if there is no project with the given IDs in the version of the metrics registry that is bundled with Cobalt.

Request

Name	Type
`customer_id`	`uint32`
`project_id`	`uint32`
`logger`	`request<Logger>`

Response

Name	Type
`status`	`Status`

CreateLoggerSimpleFromProjectId

Creates a LoggerSimple for the project with the given ID, using the state of the metrics registry that is bundled with Cobalt. The project must be in the "fuchsia" customer.

project_id The ID of the client's Cobalt project.

status Returns OK on success or INVALID_ARGUMENTS if there is no project with the given ID in the version of the metrics registry that is bundled with Cobalt.

Request

Name	Type
`project_id`	`uint32`
`logger`	`request<LoggerSimple>`

Response

Name	Type
`status`	`Status`

LoggerSimple

Defined in fuchsia.cobalt/cobalt.fidl

LoggerSimple is an extension of the LoggerBase interface that adds some additional methods intended to be used by lower-levels of the Fuchsia system.

This interface conforms to the Simple layout so that Simple bindings may be generated for it.

EndTimer

timestamp The timestamp to set as the end of the timer. The units must be microseconds. The absolute value does not matter, only the difference between the end and start timestamps will be used.

Request

Name	Type
`timer_id`	`string[64]`
`timestamp`	`uint64`
`timeout_s`	`uint32`

Response

Name	Type
`status`	`Status`

LogElapsedTime

Logs that an event lasted a given amount of time.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type ELAPSED_TIME.

event_code The index of the event that occurred. The indexed set of all event codes and their labels is specified in the metric definition.

elapsed_micros The elapsed time of the event, specified as a number of microseconds.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`elapsed_micros`	`int64`

Response

Name	Type
`status`	`Status`

LogEvent

Logs the fact that an event has occurred.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type EVENT_OCCURRED.

event_code The index of the event that occurred. The indexed set of all event codes and their labels is specified in the metric definition.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`

Response

Name	Type
`status`	`Status`

LogEventCount

Logs that an event has occurred a given number of times.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type EVENT_COUNT.

event_code The index of the event that occurred. The indexed set of all event codes and their labels is specified in the metric definition.

count The number of times the event occurred. One may choose to always set this value to 1 and always set

period_duration_micros to 0 in order to achieve a semantics similar to the LogEventOccurred() method, but with a component.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`period_duration_micros`	`int64`
`count`	`int64`

Response

Name	Type
`status`	`Status`

LogFrameRate

Logs a measured average frame rate.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type FRAME_RATE.

event_code The index of the event that associated with the frame-rate measurement. The indexed set of all event codes and their labels is specified in the metric definition.

fps The average-frame rate in frames-per-second.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`fps`	`float32`

Response

Name	Type
`status`	`Status`

LogIntHistogram

Logs a histogram over a set of integer buckets. The meaning of the Metric and the buckets is specified in the Metric definition.

See the method LogIntHistogram() in the Logger interface for more information. This method is similar except that it adheres to the requirements of Simple layout. Instead of a vector of HistogramBucekts this version takes two parallel vectors of bucket indices and the corresponding bucket counts.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`bucket_indices`	`vector<uint32>[500]`
`bucket_counts`	`vector<uint64>[500]`

Response

Name	Type
`status`	`Status`

LogMemoryUsage

Logs a measured memory usage.

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type MEMORY_USAGE.

event_code The index of the event type associated with the memory usage. The indexed set of all event codes and their labels is specified in the metric definition.

bytes The memory used, in bytes.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`bytes`	`int64`

Response

Name	Type
`status`	`Status`

StartTimer

metric_id ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and it must be of type ELAPSED_TIME.

event_code The index of the event type to associate with the elapsed time. This is passed to LogElapsedTime()

component Optionally, a component associated with the event may also be logged. See the description at LogElapsedTime().

timestamp The timestamp to set as the start of the timer. The units must be microseconds. The absolute value does not matter, only the difference between the end and start timestamps will be used.

status Returns OK on success. There are two success cases: (i) Cobalt does not currently have any timers with the given timer_id. In that case this call creates a new timer with the given ID and start timestamp. (ii) Cobalt currently has a timer with the given timer_id for which it has received exactly one EndTimer() call and no StartTimer() calls. In this case Cobalt will delete the timer and invoke LogElapsedTime() using the difference between the end timestamp and the start timestamp as the value of duration_micros. It is ok if this value is negative. Returns INVALID_ARGUMENTS if timer_id is empty, the timeout is not positive and less than 5 minutes or Cobalt currently has a timer with the given timer_ID and it already has a start timestamp. In the last case Cobalt will delete the timer with the given timer_id and this invocation of StartTimer() will be forgotten. Any error returned by LogElapsedTime() may also be returned by this method.

Request

Name	Type
`metric_id`	`uint32`
`event_code`	`uint32`
`component`	`string[64]`
`timer_id`	`string[64]`
`timestamp`	`uint64`
`timeout_s`	`uint32`

Response

Name	Type
`status`	`Status`

MetricEventLogger

Defined in fuchsia.cobalt/cobalt.fidl

Note: This protocol is part of the Cobalt 1.1 interface which is still in development. Do not use this yet.

LogCustomEvent

Logs a custom Event.

metric_id ID of the metric being logged. It must be one of the metrics declared in Cobalt's registry for the project associated with this logger, and it must be of type CUSTOM.

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

Name	Type
`metric_id`	`uint32`
`event_values`	`vector<CustomEventValue>`

Response

Name	Type
`status`	`Status`

LogInteger

Logs an integer measurement.

metric_id ID of the metric being logged. It must be one of the metrics declared in Cobalt's registry for the project associated with this logger, and it must be of type INTEGER.

value The integer measurement.

event_codes. Enum parameters, one for each of the metric's metric_dimensions. Cobalt aggregates integer values that have the same event_codes.

Request

Name	Type
`metric_id`	`uint32`
`value`	`int64`
`event_codes`	`event_vector`

Response

Name	Type
`status`	`Status`

LogIntegerHistogram

Logs a histogram giving many approximate integer measurements.

metric_id ID of the metric being logged. It must be one of the metrics declared in Cobalt's registry for the project associated with this logger, and it must be of type INTEGER_HISTOGRAM.

histogram The collection of approximate integer measurements.

event_codes. Enum parameters, one for each of the metric's metric_dimensions. Cobalt aggregates histograms that have the same event_codes.

Request

Name	Type
`metric_id`	`uint32`
`histogram`	`integer_histogram`
`event_codes`	`event_vector`

Response

Name	Type
`status`	`Status`

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
`status`	`Status`

LogOccurrence

Logs the fact that an event has occurred a number of times.

metric_id ID of the metric being logged. It must be one of the metrics declared in Cobalt's registry for the project associated with this logger, and it must be of type OCCURRENCE.

count The number of times the event has occurred. The value should be positive as a value of 0 is ignored.

event_codes. Enum parameters, one for each of the metric's metric_dimensions. Cobalt aggregates occurrence counts based on this parameter.

Request

Name	Type
`metric_id`	`uint32`
`count`	`uint64`
`event_codes`	`event_vector`

Response

Name	Type
`status`	`Status`

LogString

Logs a string value that was observed.

metric_id ID of the metric being logged. It must be one of the metrics declared in Cobalt's registry for the project associated with this logger, and it must be of type STRING.

string_value The string to log.

event_codes. Enum parameters, one for each of the metric's metric_dimensions. Cobalt aggregates counts of logged strings separately for each event_codes.

Request

Name	Type
`metric_id`	`uint32`
`string_value`	`string[256]`
`event_codes`	`event_vector`

Response

Name	Type
`status`	`Status`

MetricEventLoggerFactory

Defined in fuchsia.cobalt/cobalt.fidl

Note: This protocol is part of the Cobalt 1.1 interface which is still in development. Do not use this yet.

CreateMetricEventLogger

Create a MetricEventLogger for the project specified by project_spec.

Request

Name	Type
`project_spec`	`ProjectSpec`
`logger`	`request<MetricEventLogger>`

Response

Name	Type
`status`	`Status`

SystemDataUpdater

Defined in fuchsia.cobalt/cobalt.fidl

The SystemDataUpdater interface allows callers to update the state of the System Data in Cobalt. This includes the SystemProfile and experiment state. The changes are global and affect all loggers running on the device.

SetExperimentState

Resets Cobalt's view of the system-wide experiment state and replaces it with the given values.

experiments All experiments the device has a notion of and the arms the device belongs to for each of them. These are the only experiments the device can collect data for.

Request

Name	Type
`experiments`	`vector<Experiment>`

Response

Name	Type
`status`	`Status`

SetSoftwareDistributionInfo

Sets Cobalt's view of the system-wide distribution information replacing the existing values.

info The specifications of the current system's software distribution.

Request

Name	Type
`info`	`SoftwareDistributionInfo`

Response

Name	Type
`status`	`Status`

STRUCTS

CobaltEvent

Defined in fuchsia.cobalt/cobalt.fidl

A specification of an event that occurred to be passed to LogCobaltEvent(). This is part of an alternative API to cobalt that uses a single method with a variadic parameter instead of the multiple methods above. This technique allows multiple event codes to be passed whereas the methods above support only a single event code.

Name	Type	Description	Default
`metric_id`	`uint32`	ID of the metric to use. It must be one of the Metrics from the ProjectProfile used to obtain this Logger, and its type must match the `payload` type.	No default
`event_codes`	`vector<uint32>[5]`	The event codes for the event that occurred. There must be one event code given for each dimension specified in the metric definition.	No default
`component`	`string[64]?`	Optionally, a component associated with the event that occurred may also be logged also be logged. Any notion of component that makes sense may be used or use the empty string if there is no natural notion of component.	No default
`payload`	`EventPayload`	The event-specific information for the event to be logged.	No default

CountEvent

Defined in fuchsia.cobalt/cobalt.fidl

Used to log that an event has occurred a given number of times. Using this struct with LogCobaltEvent() is equivalent to invoking LogEventCount().

Name	Type	Description	Default
`period_duration_micros`	`int64`	The number of microseconds over which this count was observed.	No default
`count`	`int64`	The number of times the event occurred	No default

CustomEventValue

Defined in fuchsia.cobalt/cobalt.fidl

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

Name	Type	Description	Default
`dimension_name`	`string`	The name of the Metric dimension this value is for.	No default
`value`	`Value`	The value for that dimension.	No default

Event

Defined in fuchsia.cobalt/cobalt.fidl

Used to log an event that has no extra fields. Using this struct with LogCobaltEvent() is equivalent to invoking LogEvent().

Name	Type	Description	Default

Experiment

Defined in fuchsia.cobalt/cobalt.fidl

The state of a single experiment on a device or binary.

Name	Type	Description	Default
`experiment_id`	`uint64`	The id of the experiment as defined by the A/B Experiment framework.	No default
`arm_id`	`uint32`	The id of the experiment arm as defined by the A/B Experiment framework.	No default

HistogramBucket

Defined in fuchsia.cobalt/cobalt.fidl

One bucket of histogram. This is used by the methods LogIntHistogram() from Cobalt 1.0 and LogIntegerHistogram from Cobalt 1.1.

Name	Type	Description	Default
`index`	`uint32`	The index of the bucket. The MetricDefinition 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.cobalt/cobalt.fidl

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

Note: This type is part of the Cobalt 1.1 interface which is still in development. Do not use this yet.

Name	Type	Description	Default
`metric_id`	`uint32`	ID of the metric being logged. It must be one of the metrics declared in Cobalt's registry for the project associated with the MetricEventLogger being used and its type must match the type of `payload`.	No default
`event_codes`	`event_vector`	`event_codes`. Enum parameters corresponding to the metric's additional dimensions.	No default
`payload`	`MetricEventPayload`	The metric-type-specific data for the event being logged.	No default

ENUMS

Status

Type: int32

Defined in fuchsia.cobalt/cobalt.fidl

Response codes for Logger operations.

Name	Value	Description
`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`	Cobalt's local buffer is temporarily full and cannot handle any more Events at this time. Try again later. This condition should be rare
`INTERNAL_ERROR`	`-1`	Catch-all for unexpected errors.

TABLES

ProjectSpec

Defined in fuchsia.cobalt/cobalt.fidl

A specification of a Cobalt project.

Note: This type is part of the Cobalt 1.1 interface which is still in development. Do not use this yet.

Ordinal	Name	Type	Description
1	`customer_id`	`uint32`	The customer ID, as specified in Cobalt's metrics registry. If omitted (i.e. set to 0) then it defaults to the customer ID for the "fuchsia" customer.
2	`project_id`	`uint32`	The ID of the project, as specified in Cobalt's metrics registry.

SoftwareDistributionInfo

Defined in fuchsia.cobalt/cobalt.fidl

A collection of fields describing a system's software distribution.

Ordinal	Name	Type	Description
1	`current_channel`	`string[256]`	The channel that the device last used as an update source. This value may be empty to indicate that the device is not currently associated with any channel.
2	`current_realm`	`string[256]`	The realm of the device represented by the Omaha App ID. This value may be empty to indicate that the device is not currently associated with any realm.

UNIONS

EventPayload

Defined in fuchsia.cobalt/cobalt.fidl

The variadic part of a CobaltEvent.

Name	Type	Description
`event`	`Event`	This maps to a call to LogEvent().
`event_count`	`CountEvent`	This maps to a call to LogEventCount().
`elapsed_micros`	`int64`	This maps to a call to LogElapsedTime().
`fps`	`float32`	This maps to a call to LogFrameRate().
`memory_bytes_used`	`int64`	This maps to a call to LogMemoryUsage().

`int_histogram`	`vector<HistogramBucket>[500]`	This maps to a call to LogIntHistogram().

MetricEventPayload

Defined in fuchsia.cobalt/cobalt.fidl

The variadic part of a MetricEvent.

Note: This type is part of the Cobalt 1.1 interface which is still in development. Do not use this yet.

Name	Type	Description
`count`	`uint64`	This should be used for metrics of type OCCURRENCE. See MetricEventLogger::LogOcurrenceCount().
`integer_value`	`int64`	This should be used for metrics of type INTEGER. See MetricEventLogger::LogInteger().
`histogram`	`integer_histogram`	This payload type should be used for metrics of type INTEGER_HISTOGRAM. See MetricEventLogger::LogIntegerHistogram().
`string_value`	`string[256]`	This payload type should be used for metrics of type STRING.

Value

Defined in fuchsia.cobalt/cobalt.fidl

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

Name	Type	Description
`string_value`	`string`
`int_value`	`int64`
`double_value`	`float64`
`index_value`	`uint32`

CONSTANTS

Name	Value	Type	Description
MAX_BATCHED_EVENTS	`500`	`uint32`	Maximum number of Cobalt 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_CHANNEL_NAME_LENGTH	`256`	`uint32`	Channels should not be longer than this.
MAX_COMPONENT_LENGTH	`64`	`uint32`	Component strings should not be longer than this.
MAX_EVENT_CODE_COUNT	`5`	`uint32`	We only support up to 5 event_codes
MAX_HISTOGRAM_BUCKETS	`500`	`uint32`	This is intended as a reasonable maximum number of histogram buckets per event.
MAX_METRIC_DIMENSIONS	`10`	`uint32`	In Cobalt 1.1 we support up to 10 event codes.
MAX_REALM_NAME_LENGTH	`256`	`uint32`	Realm names should not be longer than this.
MAX_STRING_EVENT_SIZE	`256`	`uint32`	String events should not be longer than this.
MAX_TIMER_ID_LENGTH	`64`	`uint32`	Timer ids should not be longer than this.

TYPE ALIASES

Name Value Description

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. Each event code is a key from the event_codes map of the corresponding MetricDimension.

This type is part of the Cobalt 1.1 interface which is still in development. Do not use this yet.

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.