Cobalt FIDL Service

This directory contains an implementation of a FIDL service for Cobalt. The majority of the client-side logic for Cobalt lives in Cobalt Core and is imported into a Fuchsia checkout at //third_party/cobalt. The Cobalt FIDL service is an embedding of Cobalt Core into Fuchsia. The service implements Cobalt's FIDL protocols.

To use Cobalt on Fuchsia you follow these steps:

Register a metric

Before you can start using Cobalt on Fuchsia you need to register a project and a metric in the Cobalt registry. Note that Cobalt‘s registry repo is imported into a Fuchsia checkout at //third_party/cobalt_config. (The terminology config is sometimes, confusingly, used to refer to Cobalt’s registry.)

Update your BUILD.gn

Add import("//third_party/cobalt/metrics_registry.gni")

Add an invocation of metrics_registry in order to generate source code files containing constants corrsponding to the contents of your metrics registration. This facilitates your interaction with Cobalt's API. You must specify your project_id as it appears in projects.yaml.

We generate source code files for C++, Dart and Rust. Specify which languages you want generated by setting the parameters generate_cc, generate_dart, and generate_rust. These default to false. For example to generate C++ code for the memory project whose ID is 3509424520 you would add this invocation:

metrics_registry("memory_metrics_registry") {
  # This must match the ID of our Cobalt project as specified in:
  # third_party/cobalt_config/projects.yaml
  project_id = 3509424520
  namespace = "cobalt_registry"
  generate_cc = true
}

The string memory_metrics_registry is arbitrary and names the GN target so you can refer to it later. The optional namespace parameter specifies a C++ namespace into which the constant definitions will be included.

The generated code files are slightly different for each language. For C++ we generate a header file called <target_name>.cb.h where <target_name> is the name you gave to the metrics_registry target. Using the example above the generated file will be memory_metrics_registry.cb.h.

The generated code files will be created within the target gen dir for the metrics_registry target. For example assuming that the metrics_registry target given above occurs in //src/developer/memory/monitor/BUILD.gn, and assuming standard default values for GN parameters, the generated C++ file will be

out/default/gen/src/developer/memory/monitor/memory_metrics_registry.cb.h

You can peruse the generated file to see what constants are generated that can help you interact with the Cobalt API. Some examples are

• The string name of the customer and project
• The integer ID of the customer, project and metrics
• Enums for the event codes

Add a dependency on the metrics_registry target

Add the metrics_registry target to the deps of any target that needs to depend on the generated code. Using our example from above, we would likely include :memory_metrics_registry in the deps of a source_set target for a C++ library that include .cc or .h files that #include memory_metrics_registry.cb.h.

Include the generated code files

Using the example from above we would add the line

#include "src/developer/memory/monitor/memory_metrics_registry.cb.h"

to any source file that needed to references the generated constants.

Initiate a connection to Cobalt's LoggerFactory Interface

Cobalt‘s LoggerFactory is a system service that is made available to every Fuchsia component and is served by Cobalt’s FIDL service. Before your program can start logging to Cobalt, it needs to establish a connection to the Cobalt FIDL service via this interface. The exact details of how this is done depend on a number of factors including

• which programming language you are using
• which version of the component framework is being used
• whether you are using synchronous or asynchronous FIDL
• whether you are using any client libraries as opposed to raw FIDL.

For example, to directly use synchronous FIDL and Components V1 you would write code similar to this:

sys::ComponentContext* context = SomehowGetTheContext();
fuchsia::cobalt::LoggerFactorySyncPtr logger_factory;
context->svc()->Connect(logger_factory.NewRequest());

There are wrapper libraries for Cobalt in C++ and Rust located here. You may use one of these libraries instead of directly using the raw FIDL code. We do not describe those libraries in this document and below we only describe the raw FIDL code.

Get a Cobalt Logger, passing in your project ID.

Continuing with the syncronous FIDL example from above

fuchsia::cobalt::Status status;
fuchsia::cobalt::LoggerSyncPtr logger;
logger_factory->CreateLoggerFromProjectId(cobalt_registry::kProjectId,
                                      logger.NewRequest(), &status);

Here cobalt_registry::kProjectId is a generated constant and the namespace cobalt_registry was specified in the example usage of metrics_registry above.

Instrument your code to gather the metrics data you wish to log to Cobalt.

This is entirely dependent on your application.

Log to Cobalt

The Logger protocol contains several methods corresponding to the different Cobalt metric types. For example the LogEvent() method corresponds to a Cobalt metric of type EVENT_OCCURRED, which is used to describe a simple occurrence in which the only data logged to Cobalt is an enum describing which event it is that occurred. Continuing with our code example from above:

logger->LogEvent(cobalt_registry::kSomeMetricId, DimensonName::EnumName, &status)

Here the names kSomeMetricId, DimensionName, and EnumName all refer to names in the generated code.