src/cobalt/bin/app/README.md

# 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](https://fuchsia.googlesource.com/cobalt) 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](/sdk/fidl/fuchsia.cobalt).

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](https://fuchsia.googlesource.com/cobalt-registry/+/refs/heads/master). 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](https://fuchsia.googlesource.com/cobalt-registry/+/HEAD/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](https://fuchsia.googlesource.com/fuchsia/+/HEAD/src/lib/cobalt).
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.