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

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

NameType
max_wait_seconds uint32

Response

NameType

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

NameType
day_index uint32
report_ids vector<uint32>

Response

NameType
num_obs vector<uint64>

GetFailedSendAttempts

Request

NameType

Response

NameType
num uint32

GetNumEventAggregatorRuns

Request

NameType

Response

NameType
num_runs uint64

GetNumObservationsAdded

Request

NameType

Response

NameType
num_obs uint64

GetNumSendAttempts

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

Request

NameType

Response

NameType
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

NameType

Response

NameType

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

NameType

Response

NameType
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

NameType
timer_id string[64]
timestamp uint64
timeout_s uint32

Response

NameType
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

NameType
event CobaltEvent

Response

NameType
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

NameType
events vector<CobaltEvent>[500]

Response

NameType
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

NameType
metric_id uint32
event_values vector<CustomEventValue>

Response

NameType
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

NameType
metric_id uint32
event_code uint32
component string[64]
elapsed_micros int64

Response

NameType
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

NameType
metric_id uint32
event_code uint32

Response

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

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.

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

NameType
metric_id uint32
event_code uint32
component string[64]
period_duration_micros int64
count int64

Response

NameType
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

NameType
metric_id uint32
event_code uint32
component string[64]
fps float32

Response

NameType
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

NameType
metric_id uint32
event_code uint32
component string[64]
histogram vector<HistogramBucket>[500]

Response

NameType
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

NameType
metric_id uint32
event_code uint32
component string[64]
bytes int64

Response

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

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

NameType
metric_id uint32
event_code uint32
component string[64]
timer_id string[64]
timestamp uint64
timeout_s uint32

Response

NameType
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

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

NameType
timer_id string[64]
timestamp uint64
timeout_s uint32

Response

NameType
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

NameType
metric_id uint32
event_code uint32
component string[64]
elapsed_micros int64

Response

NameType
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

NameType
metric_id uint32
event_code uint32

Response

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

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.

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

NameType
metric_id uint32
event_code uint32
component string[64]
period_duration_micros int64
count int64

Response

NameType
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

NameType
metric_id uint32
event_code uint32
component string[64]
fps float32

Response

NameType
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

NameType
metric_id uint32
event_code uint32
component string[64]
bytes int64

Response

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

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

NameType
metric_id uint32
event_code uint32
component string[64]
timer_id string[64]
timestamp uint64
timeout_s uint32

Response

NameType
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

NameType
project_id uint32
logger request<Logger>

Response

NameType
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

NameType
customer_id uint32
project_id uint32
logger request<Logger>

Response

NameType
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

NameType
project_id uint32
logger request<LoggerSimple>

Response

NameType
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

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

NameType
timer_id string[64]
timestamp uint64
timeout_s uint32

Response

NameType
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

NameType
metric_id uint32
event_code uint32
component string[64]
elapsed_micros int64

Response

NameType
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

NameType
metric_id uint32
event_code uint32

Response

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

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.

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

NameType
metric_id uint32
event_code uint32
component string[64]
period_duration_micros int64
count int64

Response

NameType
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

NameType
metric_id uint32
event_code uint32
component string[64]
fps float32

Response

NameType
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

NameType
metric_id uint32
event_code uint32
component string[64]
bucket_indices vector<uint32>[500]
bucket_counts vector<uint64>[500]

Response

NameType
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

NameType
metric_id uint32
event_code uint32
component string[64]
bytes int64

Response

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

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

NameType
metric_id uint32
event_code uint32
component string[64]
timer_id string[64]
timestamp uint64
timeout_s uint32

Response

NameType
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

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

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

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

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

NameType
metric_id uint32
string_value string[256]
event_codes event_vector

Response

NameType
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

NameType
project_spec ProjectSpec
logger request<MetricEventLogger>

Response

NameType
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

NameType
experiments vector<Experiment>

Response

NameType
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

NameType
info SoftwareDistributionInfo

Response

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

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

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

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

NameTypeDescriptionDefault

Experiment

Defined in fuchsia.cobalt/cobalt.fidl

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

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

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

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

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

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.

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

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

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

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

NameTypeDescription
string_value string
int_value int64
double_value float64
index_value uint32

CONSTANTS

NameValueTypeDescription
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

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