> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Export traces, logs and metrics with OpenTelemetry

> Send Aspect CLI traces, logs and metrics to Honeycomb, Datadog or any OpenTelemetry collector over OTLP.

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:

```shell theme={null}
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](https://aspect.build/docs/cli/reference/features#telemetry) 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

```shell theme={null}
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:

```yaml title="datadog.yaml" theme={null}
otlp_config:
  receiver:
    protocols:
      grpc:
        endpoint: localhost:4317
  logs:
    enabled: true
```

Then point the CLI at the Agent:

```shell theme={null}
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`:

```python title=".aspect/config.axl" theme={null}
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`](https://aspect.build/docs/axl/types/exporters) 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:

```shell theme={null}
aspect build //... --telemetry:endpoint='https://otel.example.com:4317;authorization=Bearer xyz'
```

## What is exported

One trace per invocation:

```text theme={null}
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.

> [!WARNING]
>
> 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:

```text theme={null}
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:

```text theme={null}
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`:

```python title=".aspect/config.axl" theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.