Export traces, logs and metrics with OpenTelemetry

The Aspect CLI exports a trace for every invocation: the task, each Bazel build or test it runs, the failed actions, and every test and test attempt. It sends them over OTLP, together with the CLI’s logs and metrics on test results, the action cache and its own start-up time, to any backend that accepts OpenTelemetry. The metrics and Bazel’s exact timings on action, test and test_attempt spans require Aspect CLI v2026.46.21 or later.

Send to a collector

Set the standard OpenTelemetry environment variables:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com:4317
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer $OTEL_TOKEN"
aspect test //...

Variable	Default	Values
`OTEL_EXPORTER_OTLP_ENDPOINT`	none	The collector URL, for every signal
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	none	A URL for one signal, used as given. Overrides `OTEL_EXPORTER_OTLP_ENDPOINT` for that signal
`OTEL_EXPORTER_OTLP_PROTOCOL`	`grpc`	`grpc` or `http/protobuf`. With `http/protobuf`, `/v1/traces`, `/v1/logs` and `/v1/metrics` are appended to `OTEL_EXPORTER_OTLP_ENDPOINT`
`OTEL_EXPORTER_OTLP_HEADERS`	none	Comma-separated `key=value` pairs sent with every export
`OTEL_EXPORTER_OTLP_TIMEOUT`	`10000`	Milliseconds to wait for each export request
`OTEL_RESOURCE_ATTRIBUTES`	none	Comma-separated `key=value` resource attributes added to everything exported, such as `deployment.environment=ci`

In CI, set them from a secret. The Telemetry feature registers an exporter from the endpoint variables; set discover_endpoints = False to stop it. The headers, timeout and resource attributes still apply to every OTLP exporter, including those registered in config.axl. Everything exported carries the resource attributes service.name=aspect-cli and service.version.

Honeycomb

export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io:443
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=$HONEYCOMB_API_KEY,x-honeycomb-dataset=aspect-cli-metrics"

Use https://api.eu1.honeycomb.io:443 for an EU team. Traces land in the aspect-cli dataset and metrics in the one x-honeycomb-dataset names.

Datadog

Enable the OTLP receiver on the Datadog Agent running on the CI machine:

datadog.yaml

otlp_config:
  receiver:
    protocols:
      grpc:
        endpoint: localhost:4317
  logs:
    enabled: true

Then point the CLI at the Agent:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

An OpenTelemetry Collector with the Datadog exporter works the same way.

Configure exporters in config.axl

For more than one collector, a signal routed to its own collector, extra resource attributes, or credentials read at run time, register exporters in .aspect/config.axl:

.aspect/config.axl

def config(ctx: ConfigContext):
    token = ctx.std.env.var("OTEL_TOKEN")
    if token:
        ctx.telemetry.exporters.add(
            url = "https://otel.example.com:4317",
            headers = {"authorization": "Bearer " + token},
            signals = ["traces"],
            resource_attributes = {"deployment.environment": "ci"},
        )

ctx.telemetry.exporters.add takes:

Argument	Default	Values
`url`	none	The OTLP endpoint. With `http/protobuf`, the full URL including `/v1/traces`, `/v1/logs` or `/v1/metrics`
`protocol`	`grpc`	`grpc` or `http/protobuf`
`headers`	`{}`	Sent with every export: credentials, tenant routing
`signals`	all	A subset of `traces`, `logs` and `metrics`
`resource_attributes`	`{}`	Added to the resource of everything this exporter sends. Metric exporters share one resource; where two set a key differently, the first registered wins

A feature’s implementation can call the same function through its FeatureContext, for example to register an exporter only on one CI host. For a single invocation, pass the endpoint as a flag. It repeats, and each one uses gRPC with every signal:

aspect build //... --telemetry:endpoint='https://otel.example.com:4317;authorization=Bearer xyz'

What is exported

One trace per invocation:

root                    the whole invocation; startup_ms
├─ startup.<step>       one per start-up step: roots, builtins, store, cli, …
├─ eval                 loading .axl files
├─ execute.configs
├─ execute.features
└─ execute.task         task_name, task_id, exit_code
   └─ ctx.bazel.build   flags; one per Bazel build or test the task runs
      └─ events
         └─ build_tool  Bazel version, server pid, invocation uuid
            ├─ action        label, mnemonic, exit_code, command_line, failure_detail
            ├─ test          label, status, attempt_count, shard_count, cached
            └─ test_attempt  label, status, run, shard, attempt, cached

Span	Status is error when
`execute.task`	The task exits non-zero
`action`	The action failed
`test`	The test’s final status is failed, timed out, failed to build, a remote failure, or Bazel stopped before testing. Flaky passes are ok
`test_attempt`	That attempt failed. A flaky test shows a failed attempt under a passing `test`

action, test and test_attempt take their start and end times from Bazel. A cached test did no work in this build, so its test_attempt and test are zero-length spans at the moment the build reported the result, with cached set. A test with only some attempts cached spans the attempts that ran. Match a test_attempt to its test by label. Bazel reports only failed actions to the CLI. To get an action span for every action, add --build_event_publish_all_actions to your .bazelrc. On a large build that is a lot of spans. startup_ms on root is the time from the CLI starting until the task begins, not counting the launcher. The startup.<step> spans, together with eval, execute.configs and execute.features, show where that time went. Span events on build_tool record each target’s result (target_completed), the parsed command line (options_parsed) and every external download (fetch). Logs are the CLI’s own log lines, not Bazel’s output.

Spans carry Bazel command lines and flags, as Bazel and the CLI received them. Give your tracing backend the same access controls as your CI logs.

Metrics

Metric	Type	Attributes
`bazel.test.results`	Counter of test targets	`status`, and `cached` when every run came from a cache
`bazel.test.attempt.duration`	Histogram, seconds, of attempts that ran in this build	`status`
`bazel.action_cache.lookups`	Counter of Bazel’s local action cache lookups	`result` (`hit` or `miss`), and the miss `reason`
`aspect.cli.startup.duration`	Histogram, seconds, from the CLI starting until the task begins	`task`, the task’s name

None carries a target label, so the number of series stays bounded however large the repository. Metrics use delta temporality and are exported every 30 seconds and when the CLI exits. Set OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE or OTEL_METRIC_EXPORT_INTERVAL to change either.

Debug locally

ASPECT_DEBUG=1 prints the CLI’s log lines and trace events to stderr, including the exporters it registered:

telemetry: 2 exporter(s) registered:
  - file:stderr [compact] signals=traces,logs,metrics
  - otlp:https://api.honeycomb.io:443 [grpc] headers=x-honeycomb-team signals=traces,logs,metrics

It also prints how long the CLI took to start the task, step by step:

startup [aspect] "build started in 70ms (tracing 0ms, roots 0ms, root_module 0ms, builtins 1ms, store 0ms, modules 0ms, sources 0ms, user_config 0ms, discover 63ms, configs 0ms, cli 3ms, dispatch 0ms, features 0ms, exporters 0ms, other 3ms)"

To write them, including the start-up line, to a file instead, register a file exporter. It appends; format is compact or jsonl:

.aspect/config.axl

def config(ctx: ConfigContext):
    ctx.telemetry.exporters.add(file = "/tmp/aspect-trace.jsonl", format = "jsonl")

The CLI flushes its exporters as it exits, waiting up to 5 seconds for each signal. Set ASPECT_TELEMETRY_SHUTDOWN_TIMEOUT_MS to change that.

Get started

Platform

Aspect Cloud

Aspect Enterprise

Aspect CLI

Bazel

Learning

Export traces, logs and metrics with OpenTelemetry

Send to a collector

Honeycomb

Datadog

Configure exporters in config.axl

What is exported

Metrics

Debug locally