openinference-instrumentation-codex 0.2.0

OpenInference instrumentation for Codex CLI/SDK telemetry

openinference-instrumentation-codex

OpenInference instrumentation for Codex event streams, with a lightweight OTel proxy for process-based tracing.

Repo Boundary

Repo	Role	Contract with this repo
openinference-instrumentation-codex	Instrumentation library and OTel proxy	Owns event adapters, span building, and the codex-otel-proxy CLI
codexops	Investigation orchestrator	Runs plain Codex and tees event streams into the proxy
codexops-otel	Trace sink	Receives the OTLP traces this repo emits through the configured exporter

How It Works

flowchart LR
    source["Codex CLI JSONL or app-server events"] --> adapter["event adapter"]
    adapter --> builder["CodexTraceBuilder"]
    builder --> spans["codex.session tree"]
    spans --> exporter["OTLP exporter"]

See docs/DIAGRAM.md for the boundary view.

Repo Map

Path	Purpose
src/openinference/instrumentation/codex/	Library source and OTel proxy
tests/	Unit, integration, and e2e coverage
examples/	Minimal usage examples
scripts/	Helper scripts
docs/	Human docs

Install

Use case	Command
Base package	pip install openinference-instrumentation-codex
Proxy with OTLP exporter support	pip install "openinference-instrumentation-codex[otlp]"
Local development	uv sync --extra test

Public Surfaces

Surface	Purpose
codex-otel-proxy --transport cli-jsonl	Observe codex exec --json JSONL and build spans
codex-otel-proxy --transport app-server	Observe app-server JSON notifications and build spans
CodexCliJsonlAdapter	Normalize CLI JSONL events
CodexAppServerEventAdapter	Normalize app-server notifications
CodexTraceBuilder	Build the codex.session tree
CodexInstrumentor	Fallback SDK instrumentation

Config

Env var	Default	Meaning
OPENINFERENCE_CODEX_ENABLED	true	Enable instrumentation
OPENINFERENCE_CODEX_CAPTURE_INPUTS	false	Capture prompt input content
OPENINFERENCE_CODEX_CAPTURE_OUTPUTS	false	Capture model output content
OPENINFERENCE_CODEX_CAPTURE_TOOL_OUTPUTS	false	Capture tool result content
OPENINFERENCE_CODEX_CAPTURE_RAW_RESPONSE_EVENTS	false	Capture raw app-server response events
OPENINFERENCE_CODEX_REDACT_INPUTS	true	Redact sensitive patterns
OPENINFERENCE_CODEX_MAX_ATTRIBUTE_LENGTH	4096	Truncate serialized attributes
OPENINFERENCE_CODEX_PRESERVE_ORIGINAL_ATTRIBUTES	true	Keep source attributes under codex.original.*
OPENINFERENCE_CODEX_PROVIDER	unset	Map the observed provider onto llm.provider
OPENINFERENCE_CODEX_DEBUG	false	Enable debug behavior in instrumentation config

The proxy keeps trace export opt-in. Set OTEL_TRACES_EXPORTER=otlp plus the standard OTLP endpoint env when you want exported traces. Each observed Codex stream produces one codex.session root span; codex.turn and item/tool spans hang below it, and callers can attach job identity with repeated --root-attribute KEY=VALUE flags.

Development

Command	Purpose
uv run ruff check .	Lint the repo
uv run pytest	Run tests
docker compose -f docker-compose.phoenix.yml up --build --abort-on-container-exit --exit-code-from codex-live-smoke	Run the Phoenix smoke test

Within the CodexOps workspace, codexops should treat this repo as a black box and update the submodule pointer when it needs a new proxy revision.

Releases

Item	Value
Strategy	release-please simple
Source of truth	version.txt
Extra release files	pyproject.toml, _version.py
Merge style	squash merge with Conventional Commit PR titles

Project Docs

Doc	Purpose
docs/DIAGRAM.md	System diagram
docs/CONTRIBUTING.md	Contribution flow
docs/SECURITY.md	Security scope and reporting
docs/CODE_OF_CONDUCT.md	Collaboration standards
docs/CONTACT.md	Private contact path
AGENTS.md	Repo-specific agent guidance