Your agent → Dash0
Your agent exports spans and logs straight to Dash0 over OTLP. You don’t need a collector.
Dash0 → Mutagent
A Dash0 source in your workspace pulls the traces for Evaluate and Diagnose.
Helix on your machine can’t read Dash0 directly yet. Connect the source to your workspace and
pull, save the result with
pull-traces --out traces.jsonl, and read that file with a
local JSONL source (format: unitf).Before you start
- A Dash0 dataset that your agent’s traces go to. A dedicated dataset keeps them apart from your other telemetry.
- A read token for Mutagent. In Dash0, open Settings → Auth Tokens and create a token with the Reading permission. Under Dataset, pick Specific datasets and select that dataset. Don’t give Mutagent a token that can ingest or configure.
- Your regional API URL, from Settings → Endpoints → API, for example
https://api.eu-west-1.aws.dash0.com.
Connect the source
With the CLI
You need themutagent CLI, signed in, with a workspace selected (see
Sign in). Keep the token off the command line: export it in your own terminal
and pass the variable’s name with --secret-env.
The token is write-only: no command output ever shows it.
test exits 0 when Mutagent can read the
dataset, and 1 when it can’t, naming the check that failed: credentials_refused, unreachable,
http_error, invalid_response or host_refused. To replace the token later, run
mutagent integrations sources rotate <source-id>.
In the web app
Open Configuration › Integrations and add a trace source. Pick Dash0, then fill in the form:- API endpoint: your regional API URL.
- Dataset: leave it empty for your organization’s default dataset.
- Auth token: the read token.
Pull traces
A pull reads the source’s traces into your workspace. It starts at once and runs on the server:pull-get until the pull’s status is no longer running. Then read the result with
pull-manifest (what the pull holds and how complete it is) and pull-traces (the traces as JSONL,
to stdout or to a file with --out). A source runs one pull at a time.
Send traces from Claude Code
Claude Code can export straight to Dash0’s OTLP endpoint. Set these variables in the environment Claude Code starts in: in your shell, or in theenv block of your user settings
(~/.claude/settings.json) or managed settings. A project’s .claude/settings.json can’t turn
telemetry on.
- Endpoint: your region’s OTLP ingress, from Settings → Endpoints, with no path.
- Headers: the ingest token and the dataset to write to. The
Dash0-Datasetheader works for sending only: Mutagent’s reads put the dataset in the request instead, from the source’s settings. gen_ai.agent.name: the name a pull’s--agent-namematches. Claude Code copies the resource attributes onto every span and log, which Dash0 needs to filter on them. Without it, a trace is matched by itsservice.name.
OTEL_LOG_TOOL_CONTENT=1, which sends tool output (file contents, command
output, web results). Mutagent doesn’t read it, so leave it off.
Traces show in Dash0 shortly after a run ends. Agents that run in Mutagent Cloud don’t
send to Dash0.
Filters and limits
- Size of a pull. At most 5,000 traces; without
--limitthe server reads 500. With--agent-nameor--tag, a pull checks at most 1,000 matching traces, whatever--limitsays; narrow the window to read more. A pull that hits a limit, is throttled by Dash0 or fails partway still succeeds, marked truncated withcomplete: falsein its manifest. - Large traces. Dash0 returns at most 2,000 spans and 200 logs per trace in one read and doesn’t say when it cut a trace. When a trace reaches either count, Mutagent reads it again page by page, up to 10,000 spans and 10,000 logs. Past that the trace is kept partial and the pull is marked truncated.
- What Mutagent reads from Claude Code. Mutagent doesn’t read tool output text, thinking or compaction from a Claude Code trace: a tool call shows its input, never its result.
- Ingest window. Dash0 accepts data timestamped within about 24 hours of now. You can’t send older runs later.
- Retention. Dash0 keeps data for a limited time that depends on your plan. Pull what you want to keep before it ages out.
Troubleshooting
403: access to dataset 'default' is not permitted
403: access to dataset 'default' is not permitted
The token is limited to one dataset, but the request read the default one. Set
--dataset (or
the Dataset field) to the dataset the token is scoped to.A pull returns no traces
A pull returns no traces
Open the dataset in the Dash0 UI and check that it holds traces in the window you pulled. Most
often the harness writes to a different dataset than the source reads, or the runs fall outside
the window. Without
--since, a pull reads only the last 24 hours.The harness sends, but nothing shows up in Dash0
The harness sends, but nothing shows up in Dash0
Dash0 answers 200 even when it stores nothing. Check that the harness’s token has the
Ingesting permission (a token with only Reading can’t write) and that the
Dash0-Dataset header names the dataset you’re looking at. Data timestamped more than about 24
hours away from now is dropped too.test fails with credentials_refused
test fails with credentials_refused
Dash0 refused the token. If the token is scoped to one dataset, check that the source names it
(
--dataset or the Dataset field). Otherwise check that it has the Reading permission,
then replace it with mutagent integrations sources rotate <source-id>.