Open in ChatGPTOpen in Claude

Codex CLI integration with Coralogix

Codex CLI ships with built-in OpenTelemetry support, which means you can send its full telemetry—API requests, tool calls, user activity, and session traces—directly to Coralogix with no custom code required. Once connected, every Codex CLI session streams live data to Coralogix, giving you visibility into usage patterns and session behavior across your development team.

Supported environments

• OS: macOS, Linux (*nix)
• Shell: bash, zsh
• Requires envsubst (included in most Linux distributions and macOS through gettext)

What you need

• A Coralogix account with a Send-Your-Data API key. In Coralogix, navigate to Settings, then API Keys.
• Your Coralogix OTLP endpoint: ingress.eu2.coralogix.com:443. Use the domain selector at the top of this page to select your region.
• Codex CLI installed on your machine.
• envsubst available in your shell (included in most Linux distributions and macOS through gettext).

Set up

Install

Clone the Coralogix AI agent instrumentation repository and navigate to the Codex directory:

git clone https://github.com/coralogix/ai-agent-instrumentation.git
cd ai-agent-instrumentation/codex

Configure

1. Copy the example environment file:

   cp .env.example .env

2. Open .env and set the following values:

   • CX_API_KEY — your Send-Your-Data API key
   • CX_OTLP_ENDPOINT — your OTLP endpoint (ingress.eu2.coralogix.com:443)

3. Load the credentials and apply the OpenTelemetry configuration to Codex:

   set -a; source .env; set +a
   envsubst < config.toml.example >> ~/.codex/config.toml

4. Run Codex:

   codex

   Codex CLI sessions now stream telemetry to Coralogix.

Make it permanent

To load credentials automatically in every new terminal session, add the following to ~/.zshrc:

if [ -f "/path/to/codex/.env" ]; then
  set -a; source "/path/to/codex/.env"; set +a
fi

Validate the integration

After running a Codex CLI session, confirm that data is flowing:

1. In Coralogix, navigate to Logs and filter by your service name to see API requests and tool call events.
2. Navigate to Explore, then Tracing to view session traces.
3. Navigate to Dashboards and open the Codex dashboard to see user activity.

Monitor data in Coralogix

Code Agents dashboard reads from archive only

The AI Center Code Agents dashboard for Codex reads from your S3 archive. The dashboard does not show data stored in Frequent Search, so route your Codex telemetry to archive storage.

Import the dashboard

1. In Coralogix, navigate to Dashboards, then select New Dashboard, then Import from JSON.
2. Upload coralogix-codex-dashboard.json from the cloned repository.

Data available

Signal	Where in Coralogix
API requests and tool calls	Logs
Session traces	Tracing
User activity	Dashboard

Data scopes

Codex CLI emits logs and traces. Use data scopes to restrict which Codex CLI data each user can see. See Code agents observability — Data scopes for the per-agent breakdown.

Complete configuration

After envsubst resolves your credentials, the resulting ~/.codex/config.toml looks like this:

[otel]
environment = "production"
log_user_prompt = false

[otel.exporter.otlp-http]
endpoint = "https://ingress.<your-region>.coralogix.com/v1/logs"
protocol = "binary"

[otel.exporter.otlp-http.headers]
"Authorization" = "Bearer <YOUR_CX_API_KEY>"
"CX-Application-Name" = "codex"
"CX-Subsystem-Name" = "codex-sessions"

[otel.trace_exporter.otlp-http]
endpoint = "https://ingress.<your-region>.coralogix.com/v1/traces"
protocol = "binary"

[otel.trace_exporter.otlp-http.headers]
"Authorization" = "Bearer <YOUR_CX_API_KEY>"
"CX-Application-Name" = "codex"
"CX-Subsystem-Name" = "codex-sessions"

Codex supports two separate OTel export pipelines: otel.exporter for log events and otel.trace_exporter for traces. Each pipeline has its own endpoint (note the /v1/logs and /v1/traces suffixes), protocol, and authentication headers. Coralogix uses the custom CX-Application-Name and CX-Subsystem-Name headers to route signals.

For the source template and additional details, see codex in the GitHub repository.

Configuration examples

Activate trace export

The full config.toml.example already includes both log and trace exporter blocks. If you only want logs without traces, remove the [otel.trace_exporter.otlp-http] block and its [otel.trace_exporter.otlp-http.headers] section from your ~/.codex/config.toml.

Activate prompt logging

Set log_user_prompt = true in the [otel] block to include prompt text in codex.user_prompt log events. Prompt logging is off by default.

Tag events with an environment name

[otel]
environment = "prod"

Telemetry reference

The AI Center Code Agents dashboard surfaces the most common session, API, and tool-call signals out of the box. To explore every log event, span attribute, and trace span that Codex CLI emits — and use those signals as the basis for your own Custom Dashboards or alerts — see the Codex CLI advanced configuration reference.

Data reference

Log events

Event	What it captures
codex.conversation_starts	Model, reasoning settings, sandbox and approval policy — one event per session
codex.api_request	attempt, duration_ms, http.response.status_code, error details — one event per API call
codex.sse_event	Stream event kind, success/failure, duration_ms; on response.completed: input_token_count, output_token_count, cached_token_count, reasoning_token_count, tool_token_count
codex.websocket_request	duration_ms per request
codex.websocket_event	Per-message event.kind, success/failure, error
codex.user_prompt	prompt_length; prompt content redacted unless log_user_prompt = true
codex.tool_decision	tool_name, approved/denied, whether the decision came from config or the user
codex.tool_result	tool_name, duration_ms, success, output snippet

Traces

Codex emits a trace per session when you configure trace_exporter. Spans cover the full turn lifecycle, including API calls and tool executions. All spans use service name codex_cli_rs. The top-level span for each session uses the name session_loop, with child spans for individual API calls and tool invocations.

Note

Metrics export is not yet supported by Codex CLI.

Advanced configuration

Option	Default	Purpose
log_user_prompt	false	Include prompt text in codex.user_prompt log events
environment	"production" (in template)	Tag all events with an environment name
exporter	"none"	Set to otlp-http or otlp-grpc to activate log export
trace_exporter	—	Same values as exporter; activates trace export

Permissions

Resource	Action	Description
Send-Your-Data API key	Ingest logs and traces	Required to export OTel signals to Coralogix

For details, see Roles and permissions.

Troubleshoot

No data appears after running a session

Cause: Codex flushes telemetry on exit.

Fix: type /exit to end the session cleanly instead of closing the terminal.

Logs appear but traces do not

Cause: trace_exporter is not set in ~/.codex/config.toml.

Fix: add trace_exporter = "otlp-http" to the [otel] block.

envsubst substitutes variables as empty strings

Cause: credentials were not loaded into the shell before running envsubst.

Fix: run set -a; source .env; set +a in the same shell session before running envsubst.

The Code Agents dashboard shows zero everywhere but Codex logs are in Coralogix

Start by ruling out storage routing: the dashboard reads Codex telemetry from your S3 archive and ignores data held only in Frequent Search (see Monitor data in Coralogix). If you already route Codex logs to archive storage and the dashboard is still empty, the shape of the logs is the problem.

Cause: Coralogix wraps every OTLP log record in a logRecord object, and the dashboard reads Codex signals from inside it. When something reshapes or deletes that object after ingest, the dashboard queries an empty field and every widget reports zero. The telemetry itself is intact: it arrived, Coralogix stored it, and you can still search it in Logs. Only the dashboard loses sight of it.

The reshaping almost always comes from a parsing rule. A rule group whose rule matcher sets no application, subsystem, or severity runs on every log in the account, Codex included, so a group built for a different application still reshapes Codex logs. The step that empties the dashboard is a Remove Fields rule that lists logRecord among its excluded fields — usually paired with an earlier step that copies the nested fields to the top level first.

Confirm it

1. In Coralogix, navigate to Logs, open a recent Codex log, select its more actions menu, then select View Raw Log. If the log has no logRecord object, a parsing rule removed it.
2. Navigate to Data Flow, then Parsing Rules. Look for an active rule group whose rule matcher leaves the application, subsystem, and severity fields blank, and check its rules for a Remove Fields step that removes logRecord.

Fix

Pick the option that fits the rule group's original purpose. The flattening might be deliberate and other dashboards might depend on it, so confirm the group's intent before you change it.

Option	What to change	Trade-off
Scope the rule group	Set the rule matcher to the applications the group serves, which leaves Codex logs untouched.	A rule matcher can only include applications, not exclude them, so you have to list every application that needs the group.
Turn the rule group off	Deactivate the group if it turns out to be experimental or obsolete.	Every application relying on the flattened fields loses them.
Keep logRecord	Remove logRecord from the Remove Fields rule's excluded fields and leave the rest of the list in place.	The smallest edit, and nothing downstream breaks, but Coralogix then stores the affected fields twice, which raises log volume and cost.

Parsing rules run at ingest, so any of these changes applies to new logs only. Logs already in storage keep their current shape and the dashboard does not backfill. After the change, run a few more Codex sessions, then query an explicit range of several days that covers the new data.

An account-wide rule group affects every AI Center screen built on OTLP logs, so check the Claude Code dashboard and the Evaluations screens as well.

Not the cause

The Total Cost of Ownership (TCO) Optimizer priority your traces land in is not the cause. The Codex dashboard runs on logs, and average latency is the only widget that reads traces, so traces in the Low priority leave the rest of the dashboard unaffected. If the whole dashboard is empty, look at the logs, not the traces.

Next steps

Once your integration is set up, explore Code agents to monitor token usage, costs, tool calls, code changes, and session data across all your coding agents.