Codex CLI

OpenAI’s Codex CLI has a built-in OpenTelemetry exporter that you configure in its config.toml file. One [otel] block sends every Codex tool call, with its arguments and output, to Scout Trails. This page covers setup, rollout to more machines, and how to change or stop what is sent.

Before you start

An ingest key for the machine you are configuring. See Getting an ingest key.
Outbound HTTPS access to ingest.scoutmonitoring.io on port 443. See Network requirements.

Set up Codex on your machine

Open ~/.codex/config.toml in an editor. Create the file if it doesn’t exist. If you set CODEX_HOME, the file is $CODEX_HOME/config.toml.

Add this block, replacing <your-ingest-key> with your key. If the file already has an [otel] table, merge these keys into it rather than adding a second one.

[otel]
log_user_prompt = false

[otel.exporter.otlp-grpc]
endpoint = "https://ingest.scoutmonitoring.io:443"
headers = { "Authorization" = "Bearer <your-ingest-key>" }

Start a new Codex session, either interactive (codex) or non-interactive (codex exec). Codex reads the file at startup.
Ask Codex to do something that uses a tool, such as listing the files in the current directory, then check the dashboard as described in Checking that data arrives. Codex sessions show codex-cli in the Agent column.

What each key does:

Key	Purpose
`log_user_prompt`	`false` keeps the text of your prompts out of the telemetry. Codex sends prompt text only when this is `true`.
`[otel.exporter.otlp-grpc]`	Selects the gRPC exporter for Codex’s log events. The endpoint accepts gRPC only, so don’t use `otlp-http`.
`endpoint`	The Scout Trails ingest endpoint.
`headers`	Your ingest key, sent as `Authorization: Bearer <your-ingest-key>`.

Write the exporter as a nested table

The exporter must be a table named after the exporter. This is correct:

[otel.exporter.otlp-grpc]
endpoint = "https://ingest.scoutmonitoring.io:443"

A plain string does not parse, and Codex refuses to load the configuration:

[otel]
exporter = "otlp-grpc"

The inline form exporter = { otlp-grpc = { endpoint = "...", headers = { ... } } } inside [otel] is equivalent to the nested table and also works.

Other `[otel]` settings

environment tags every event with a name such as "staging" (Codex’s default is "dev"). The dashboard doesn’t display it.
trace_exporter sends Codex’s trace spans. Scout Trails builds Codex tool calls from log events, so you don’t need it.
metrics_exporter controls Codex’s metrics. Don’t point it at the Scout Trails endpoint, which doesn’t accept metrics.

Project-level configuration

Codex also reads .codex/config.toml inside a project, but only for projects you have marked as trusted. Configure the exporter in your user-level ~/.codex/config.toml so it applies to every project, trusted or not.

Roll out to more machines

Each machine needs its own actor and ingest key.

Create an actor for each machine on the Actors & ingest keys tab.
Distribute the [otel] block above with your usual configuration tooling, filling in each machine’s own key in headers.

Using one key on several machines works, but their sessions and tool calls are then attributed to a single actor and can’t be separated in the dashboard. See Actors.

Change the key

Copy the new key from the Actors & ingest keys tab.
Replace the value after Bearer in headers.
Start a new Codex session.

Selecting Rotate key in the dashboard invalidates the old key immediately, so every machine using it stops sending until you update it.

Turn telemetry off

On one machine: delete the [otel.exporter.otlp-grpc] table, or replace it with exporter = "none" under [otel]. Codex’s default is none.
From the dashboard: select Revoke key on the actor, or Deactivate the actor. Ingest rejects the key from then on, and nothing more is stored.