Skip to main content
Trace Codex CLI agent turns and tool calls in Phoenix for full observability.
Trace your Codex CLI sessions in Phoenix with the coding-harness-tracing toolkit — every turn shows up as a trace with the model call, each tool it runs, and token usage, grouped into its session. No application code changes required: the toolkit hooks into Codex’s notify events and streams OpenInference spans to Phoenix.

​
Launch Phoenix

The fastest way to get started with Phoenix is by signing up for a free Phoenix Cloud account. If you prefer, you can also run Phoenix in a notebook, self-host it, or use it directly from your terminal. Go to the settings page in your Phoenix instance to find your endpoint and API key. A self-hosted Phoenix defaults to http://localhost:6006; the API key is only required when auth is enabled.

​
Install

The curl installer is the simplest — it runs a short wizard that saves your Phoenix credentials for you. Use a local clone if you’d rather run the installer from a checkout of the source. macOS / Linux:
Windows (PowerShell):

​
Local clone

The installer prompts for your backend — select Phoenix, then enter your endpoint and optional API key — and your project name. Open a new shell after install so the update takes effect.

​
Configuration

Credentials live in ~/.arize/harness/config.json. To override per category, set environment variables in ~/.codex/arize-env.sh — the notify hook sources this file automatically. Env values take precedence over config.json.
On the Phoenix backend, set the project name with PHOENIX_PROJECT (or PHOENIX_PROJECT_NAME); ARIZE_PROJECT_NAME is Arize-only and ignored here. ARIZE_TRACE_ENABLED is a backend-agnostic harness setting and keeps the ARIZE_ prefix regardless of destination.

​
Redaction controls

Each ARIZE_LOG_* flag accepts "true" or "false" and defaults to "true". Set to "false" to opt out per category:

​
Observe

Once tracing is enabled, Codex activity is streamed to Phoenix. You’ll see:
  • Turn traces — each agent turn (user prompt to assistant response) as a parent LLM span
  • Tool call spans — one per tool decision and result pair
  • Session grouping — all turns from the same session grouped by session.id
  • Model and token usage — model name plus prompt, completion, and total token counts on every turn span

Codex turns grouped together in a single session view

Drill into any turn trace to inspect the full span tree, including the parent model generation and child tool calls.

Detailed trace view for a Codex turn

​
Reference

For the full list of environment variables, default file paths, and troubleshooting steps, see the Codex tracing README.

​
Uninstall

​
Resources

Arize Coding Harness Tracing

OpenInference

Codex CLI