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.: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

Copy the example environment file:
```
cp .env.example .env
```
Open .env and set the following values:
- CX_API_KEY — your Send-Your-Data API key
- CX_OTLP_ENDPOINT — your OTLP endpoint (ingress.:443)

Load the credentials and apply the OpenTelemetry configuration to Codex:

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

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:

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

Monitor data in Coralogix

Import the dashboard

In Coralogix, navigate to Dashboards, then select New Dashboard, then Import from JSON.
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

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"

Data reference

Log events

Event	Key attributes
`codex.conversation_starts`	`session.id`, `model`, `approval_policy`, `sandbox_mode`
`codex.api_request`	`session.id`, `model`, `status`, `success`, `duration_ms`
`codex.sse_event`	`session.id`, `kind`, `success`, `duration_ms`, `input_token_count`, `output_token_count`, `cached_token_count`, `model`
`codex.user_prompt`	`session.id`, `length` (content redacted unless `log_user_prompt = true`)
`codex.tool_decision`	`session.id`, `tool`, `approved`, `source`
`codex.tool_result`	`session.id`, `tool`, `success`, `duration_ms`

Every event also carries originator (codex_cli_rs), conversation.id, user.email, and event.name. Use originator = 'codex_cli_rs' as the primary filter when querying Codex events in DataPrime.

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.

Need help? Contact Support.

What's new? Find out here.

LLM? Read llms.txt.

Previous Claude Code

Next Gemini CLI