Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fintegrations%2Fai-observability%2Fcodex-cli.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fintegrations%2Fai-observability%2Fcodex-cli.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

# 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[​](#supported-environments "Direct link to Supported environments")

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

## What you need[​](#what-you-need "Direct link to What you need")

* A Coralogix account with a **Send-Your-Data [API key](https://docs-docusaurus.kinsta.page/user-guides/account-management/api-keys/send-your-data-api-key/.md)**. 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[​](#set-up "Direct link to Set up")

### Install[​](#install "Direct link to 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[​](#configure "Direct link to 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[​](#make-it-permanent "Direct link to 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[​](#validate-the-integration "Direct link to 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[​](#monitor-data-in-coralogix "Direct link to 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[​](#import-the-dashboard "Direct link to 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[​](#data-available "Direct link to Data available")

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

### Data scopes[​](#data-scopes "Direct link to Data scopes")

Codex CLI emits logs and traces. Use [data scopes](https://docs-docusaurus.kinsta.page/user-guides/account-management/user-management/scopes/.md) to restrict which Codex CLI data each user can see. See [Code agents observability — Data scopes](https://docs-docusaurus.kinsta.page/user-guides/ai/code-agents/.md#data-scopes) for the per-agent breakdown.

## Complete configuration[​](#complete-configuration "Direct link to 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](https://github.com/coralogix/ai-agent-instrumentation/tree/master/codex).

## Configuration examples[​](#configuration-examples "Direct link to Configuration examples")

### Activate trace export[​](#activate-trace-export "Direct link to 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[​](#activate-prompt-logging "Direct link to 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[​](#tag-events-with-an-environment-name "Direct link to Tag events with an environment name")

```
[otel]

environment = "prod"
```

## Telemetry reference[​](#telemetry-reference "Direct link to 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[​](#data-reference "Direct link to Data reference")

### Log events[​](#log-events "Direct link to 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[​](#traces "Direct link to 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[​](#advanced-configuration "Direct link to 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[​](#permissions "Direct link to 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://docs-docusaurus.kinsta.page/user-guides/aaa/access-control/permissions/.md).

## Troubleshoot[​](#troubleshoot "Direct link to 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[​](#next-steps "Direct link to Next steps")

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