# 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](https://coralogix.com/docs/user-guides/account-management/api-keys/send-your-data-api-key/index.md)**. In Coralogix, navigate to **Settings**, then **API Keys**.
- Your Coralogix OTLP endpoint: `ingress.[[DOMAIN_VALUE]]: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:

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

### Configure

1. Copy the example environment file:

   ```bash
   cp .env.example .env
   ```

1. Open `.env` and set the following values:

   - `CX_API_KEY` — your Send-Your-Data API key
   - `CX_OTLP_ENDPOINT` — your OTLP endpoint (`ingress.[[DOMAIN_VALUE]]:443`)

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

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

1. Run Codex:

   ```bash
   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`:

```bash
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.
1. Navigate to **Explore**, then **Tracing** to view session traces.
1. 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**.
1. 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](https://coralogix.com/docs/user-guides/account-management/user-management/scopes/index.md) to restrict which Codex CLI data each user can see. See [Code agents observability — Data scopes](https://coralogix.com/docs/user-guides/ai/code-agents/#data-scopes) for the per-agent breakdown.

## Complete configuration

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

```toml
[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](https://github.com/coralogix/ai-agent-instrumentation/tree/master/codex).

## 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

```toml
[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](https://developers.openai.com/codex/config-advanced).

## 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](https://coralogix.com/docs/user-guides/account-management/user-management/create-roles-and-permissions/index.md).

## 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`.

## Next steps

Once your integration is set up, explore [Code agents](https://coralogix.com/docs/user-guides/ai/code-agents/index.md) to monitor token usage, costs, tool calls, code changes, and session data across all your coding agents.