openinference-instrumentation-codex 0.4.0

OpenInference traces for persisted Codex sessions and native OTLP telemetry

openinference-instrumentation-codex

This package exports Codex activity as OpenInference codex.turn traces from persisted session files or native OTLP telemetry.

Prerequisites

Goal	Requirements
Install and run the package	Python >=3.10,<3.14 and an OTLP trace destination
Forward persisted sessions	Read access to $CODEX_HOME/sessions/**/*.jsonl
Receive native telemetry	A Codex producer configured to send OTLP logs and traces
Run development workflows	make, uv, and Docker for container or Phoenix checks

Quick Start

python -m pip install "openinference-instrumentation-codex[otlp]"

export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:6006/v1/traces
export OTEL_RESOURCE_ATTRIBUTES='openinference.project.name=codex-local'

codex-jsonl-forwarder --codex-home "${CODEX_HOME:-$HOME/.codex}" \
  --state-path .run/codex-jsonl-forwarder-state.json

Persisted-session forwarding can include prompts, responses, and tool results. Restrict the destination or configure the relevant OPENINFERENCE_CODEX_CAPTURE_* values before processing sensitive sessions.

Surfaces

Surface	Primary use
codex-jsonl-forwarder	Export existing or watched persisted sessions
codex-otlp-interceptor	Receive native Codex OTLP logs and traces
codex-session-enricher	Add persisted-session content to an existing native turn

Repo Map

Path	Use it for
src/openinference/instrumentation/codex/	Package implementation and CLI entrypoints
tests/	Unit, integration, end-to-end, and evidence-backed coverage
scripts/	Capture, smoke, and artifact-validation helpers
examples/	Example package usage
docs/	Detailed contracts, diagrams, and human project docs

Documentation

Document	Use it for
AGENTS.md	Concise file routing
docs/AGENTS.details.md	Surface contracts, mappings, evidence, tooling, and validation
docs/DIAGRAMS.md	Visual package-flow orientation
docs/CONTRIBUTING.md	Contribution expectations
docs/SECURITY.md	Vulnerability reporting
CHANGELOG.md	Release history