OpenAI Codex tracing with Langfuse

What is Codex? Codex is OpenAI's agentic coding tool. It runs in your terminal (and IDE), understands your codebase, edits code, runs commands, and can spawn subagents to work on tasks in parallel.

What is Langfuse? Langfuse is an open-source AI engineering platform. It helps teams trace agentic applications, debug issues, evaluate quality, and monitor costs in production. Use Langfuse Cloud (hosted by Langfuse, free tier, no infrastructure to run) or self-host it.

codex plugin marketplace add langfuse/codex-observability-plugin

What can this integration trace?

Using Codex's plugin hooks, this integration reads the transcript Codex writes for each session and sends it to Langfuse. You can monitor:

• User inputs: every prompt you send to Codex, including any images you attach. Images are stored as Langfuse media objects and rendered in the trace.
• Model responses: assistant messages and reasoning summaries for each model call in a turn
• System prompts: Codex's base instructions, its developer-role messages, and the injected <environment_context>, sent with every model call and measured on the turn so you can see when the system prompt changed
• Tool calls: shell commands (exec_command, shell), file edits (apply_patch), MCP tools, web search, and subagent spawns (spawn_agent), with their inputs, outputs, and error status
• Token usage: input, output, cached, and reasoning tokens per model call, so you can monitor cost
• Model metadata: model, provider, reasoning effort, and the Codex CLI version behind each turn
• Subagents: subagent threads resolved from their own transcripts and nested under the spawning turn
• Skills: a skill:<name> tag on every turn that invoked a skill, whether you invoked it explicitly or the agent picked it up itself
• Sessions: all turns from one Codex session grouped together for replay
• Timing: accurate, backdated start and end times for every step

Interrupted turns, where you cancel Codex mid-response, are uploaded as well and flagged as interrupted. Prompts, tool inputs, and tool outputs are captured in full and are never truncated.

How it works

Codex provides a plugin system with hooks that run custom commands at lifecycle points. This integration uses the Stop hook, which runs after each Codex turn.

1. The plugin registers a Stop hook that runs each time Codex finishes a turn.
2. The hook reads Codex's session transcript (the rollout file).
3. Turns are reconstructed and converted into Langfuse traces using the Langfuse TypeScript SDK.
4. All turns from the same session are grouped using a shared session_id.
5. A small sidecar file records which turns were already uploaded, so resuming a session never creates duplicates.

Tracing is opt-in via the TRACE_TO_LANGFUSE environment variable. The hook fails open, so if anything goes wrong it logs and exits without blocking your Codex session.

Quick start

codex plugin marketplace add langfuse/codex-observability-plugin

codex plugin add tracing@codex-observability-plugin

[features]
hooks = true

[plugins."tracing@codex-observability-plugin"]
enabled = true

[hooks.state."tracing@codex-observability-plugin:hooks/hooks.json:stop:0:0"]
enabled = true

export TRACE_TO_LANGFUSE="true"
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://cloud.langfuse.com" # 🇪🇺 EU region

{
  "enabled": true,
  "public_key": "pk-lf-...",
  "secret_key": "sk-lf-...",
  "base_url": "https://cloud.langfuse.com"
}

cd your-project
codex

Environment variables

The credential variables also accept a LANGFUSE_CODEX_ prefix (for example LANGFUSE_CODEX_PUBLIC_KEY), which takes precedence over the standard variable.

Every variable has an equivalent key in langfuse.json, using the lower-case name without the prefix. For example LANGFUSE_CODEX_SKILL_TAGS becomes "skill_tags", and TRACE_TO_LANGFUSE becomes "enabled".

Troubleshooting

No traces appearing in Langfuse

1. The plugin isn't installed or enabled. Run codex plugin add tracing@codex-observability-plugin, then confirm hooks = true under [features] and that the tracing@codex-observability-plugin plugin is enabled in ~/.codex/config.toml. Run codex plugin list and codex features list to check both.
2. The Stop hook is disabled. Approve the Langfuse Stop hook when Codex prompts you. If the hook has already been trusted, verify that its generated entry under [hooks.state] has enabled = true. A plugin update changes the hook hash and can require a fresh review.
3. Tracing isn't turned on. TRACE_TO_LANGFUSE must be the exact string "true" and visible to the Codex process, unless you enabled tracing in ~/.codex/langfuse.json. Also verify the public key starts with pk-lf-.
4. Restart and test again. Fully restart Codex, start a new session, and send two short messages before checking Langfuse.
5. Enable debug logging. Set LANGFUSE_CODEX_DEBUG=true to log to stderr and surface the actual cause. Add LANGFUSE_CODEX_FAIL_ON_ERROR=true to turn a silent upload failure into a visible hook error.

Authentication errors

Verify your API keys are correct and that LANGFUSE_BASE_URL matches the region your keys belong to:

• EU region: https://cloud.langfuse.com
• US region: https://us.cloud.langfuse.com
• Japan region: https://jp.cloud.langfuse.com
• HIPAA region: https://hipaa.cloud.langfuse.com

Data privacy

When enabled, the plugin uploads completed Codex transcript data to Langfuse, including prompts, attached images, assistant messages, reasoning summaries, system prompts, tool inputs and outputs, model metadata, and token usage. This content is captured in full and is not truncated, so do not enable tracing for sessions containing data you do not want stored in Langfuse.

Resources

• Langfuse Codex Plugin (GitHub)
• OpenAI Codex documentation
• Langfuse Sessions
• Langfuse TypeScript SDK
• Tracing coding agents with Langfuse