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_specs A vector of specifications identifying the reports to
return the number of observations for.
Returns a vector whose k-th element is the number of observations
generated for the k-th element of report_specs. If report_specs
is the empty vector, then an empty vector is returned.
Request
| Name | Type |
|---|---|
day_index |
uint32
|
report_specs |
vector<ReportSpec>
|
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.
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
| 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.
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
| 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
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
|
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.
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
| 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
|
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.
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
| 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, SHUT_DOWN if the factory is no longer
creating new loggers, 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
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
|
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.
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
| 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.
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.
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.
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
| 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
|
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
|
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 |
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 |
SHUT_DOWN |
4 |
|
INTERNAL_ERROR |
-1 |
Catch-all for unexpected errors. |
TABLES
ReportSpec
Defined in fuchsia.cobalt/cobalt_controller.fidl
A specification to identify a single Cobalt report.
| Ordinal | Name | Type | Description |
|---|---|---|---|
| 1 | customer_id |
uint32
|
The customer ID, as specified in Cobalt's metrics registry. |
| 2 | project_id |
uint32
|
The ID of the project, as specified in Cobalt's metrics registry. |
| 3 | metric_id |
uint32
|
The ID of the metric, as specified in Cobalt's metrics registry. |
| 4 | report_id |
uint32
|
The ID of the report, 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(). |
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_REALM_NAME_LENGTH |
256
|
uint32 |
Realm names should not be longer than this. |
| MAX_TIMER_ID_LENGTH |
64
|
uint32 |
Timer ids should not be longer than this. |