> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.comet.com/docs/opik/llms.txt.

# Observability for OpenAI Codex with Opik

> Configure OpenAI Codex OpenTelemetry export to send trace telemetry to Opik.

[OpenAI Codex](https://developers.openai.com/codex) supports opt-in OpenTelemetry export through Codex configuration files.

## When this guide applies

Use this guide if you run Codex (CLI/IDE/app) and want its OTEL trace exporter to send telemetry to Opik.

> **Warning**
>
> **Know what Codex's trace exporter sends before you rely on it.** Codex exports its internal
> tracing spans (`session_loop`, `handle_responses`, `append_items`, `auth`, ...), not LLM-call
> spans. Conversation facts arrive as span **events** (`codex.user_prompt`, `codex.api_request`,
> `codex.tool_result`, `codex.turn_ttft`) that Opik stores under `opentelemetry.events` in span
> metadata, carrying the model name, tool names, durations and prompt *length*. The trace signal
> never includes the prompt text, the response text, token counts or cost, even with
> `log_user_prompt = true`; Codex sends those to its **logs** exporter (`otel.exporter`), which
> Opik does not ingest. Use this integration for Codex operational telemetry. For per-user token
> and cost attribution across Codex sessions, use [Cost Intelligence](/cost-intelligence/overview).

> **Note**
>
> This guide covers telemetry flowing **from Codex to Opik**. For the other direction — letting Codex
> read your traces, score outputs and run evaluations — register the
> [Opik MCP server](/mcp-server) with it. One command, `uvx opik mcp configure`, installs the server
> and the Opik skills without the SDK. The two are independent, and you can use either or both.

> **Looking to reduce Codex spend rather than review sessions?**
>
> Opik shows you **what Codex did**. If the question is **where the tokens went and how to spend
> fewer of them**, that is [Cost Intelligence](/cost-intelligence/overview): every Codex API call
> captured on the wire and attributed to system prompt, tools, MCP servers and user input, per
> user and per repository, with policy controls that typically cut spend by 15% to 30%. Only
> counts and metadata leave the machine, never content. It runs side by side with the OTel export
> on this page.

> **Warning**
>
> Codex redacts prompt text unless `log_user_prompt = true`. With the default `false`, Opik traces
> show structure, timing and token counts but not what the developer typed. Enable it only if your
> policy allows prompt export.

> **Note**
>
> The block structure below follows the current Codex runtime config shape used in local `config.toml` (`[otel.trace_exporter.otlp-http]`).

## Where to configure Codex

Codex reads configuration from:

* user config: `~/.codex/config.toml`
* project config: `.codex/config.toml`

See [Codex config basics](https://developers.openai.com/codex/config-basic).

## Opik OTLP trace endpoint modes

For Opik OTEL endpoint behavior, see [Opik OpenTelemetry overview](/integrations/opentelemetry).

#### Opik Cloud

```toml
[otel]
environment = "prod"
log_user_prompt = false

[otel.trace_exporter.otlp-http]
endpoint = "https://www.comet.com/opik/api/v1/private/otel/v1/traces"
protocol = "binary"
headers = { "Authorization" = "<your-api-key>", "Comet-Workspace" = "<your-workspace>", "projectName" = "<your-project-name>" }
```

Required headers:

* `Authorization`
* `Comet-Workspace`

Optional headers:

* `projectName` (recommended)

#### Enterprise deployment

```toml
[otel]
environment = "prod"
log_user_prompt = false

[otel.trace_exporter.otlp-http]
endpoint = "https://<comet-deployment-url>/opik/api/v1/private/otel/v1/traces"
protocol = "binary"
headers = { "Authorization" = "<your-api-key>", "Comet-Workspace" = "<your-workspace>", "projectName" = "<your-project-name>" }
```

Required headers:

* `Authorization`
* `Comet-Workspace`

Optional headers:

* `projectName` (recommended)

#### Self-hosted instance

```toml
[otel]
environment = "prod"
log_user_prompt = false

[otel.trace_exporter.otlp-http]
endpoint = "http://localhost:5173/api/v1/private/otel/v1/traces"
protocol = "binary"
headers = { "projectName" = "<your-project-name>" }
```

Required headers:

* none by default (depends on your self-hosted auth setup)

Optional headers:

* `projectName` (recommended)
* auth headers if your instance enforces auth

## Example intent and minimal valid setup

Intent:
Route Codex OTEL trace export to Opik with project/workspace attribution.

Applies when:
You have enabled Codex OTEL export and selected OTLP/HTTP exporter in config.

Required fields:

* an `[otel.trace_exporter.otlp-http]` table. The table itself selects the exporter; do **not**
  also write `trace_exporter = "otlp-http"` as a string under `[otel]`, Codex rejects the file
  with `cannot extend value of type string with a dotted key`.
* `endpoint`
* `protocol` (`binary` or `json`, binary recommended)

Optional fields:

* `headers` (`projectName` strongly recommended)
* `otel.environment`
* `otel.log_user_prompt` (keep `false` unless policy allows prompt export)

Minimal valid config:

```toml
[otel]
log_user_prompt = false

[otel.trace_exporter.otlp-http]
endpoint = "https://www.comet.com/opik/api/v1/private/otel/v1/traces"
protocol = "binary"
headers = { "Authorization" = "<your-api-key>", "Comet-Workspace" = "<your-workspace>", "projectName" = "<your-project-name>" }
```

## Validation

1. Run a Codex session after updating `config.toml`.
2. Confirm OTLP HTTP requests are sent to `/otel/v1/traces`.
3. Verify traces appear in the expected Opik workspace/project. Expect many short internal
   traces per session (`auth`, `turn/start`, `codex.exec`, ...); open a `session_loop` or
   `dispatch_tool_call_with_terminal_outcome` span and look under **Metadata →
   opentelemetry.events** for the `codex.*` events.

## Notes

* Codex telemetry export is opt-in.
* Prompt text and token usage are only available on the logs signal (`otel.exporter`), which Opik does not receive.
* Keep `log_user_prompt = false` unless your policy explicitly allows prompt text export.
* If your Codex build uses a different exporter key path, align with your installed version's config reference.

## Source references

* [Codex security and OTEL opt-in](https://developers.openai.com/codex/security/)
* [Codex config basics](https://developers.openai.com/codex/config-basic)
* [Codex config reference](https://developers.openai.com/codex/config-reference)
* [Opik OpenTelemetry overview](/integrations/opentelemetry)