Metadata-Version: 2.4
Name: openinference-instrumentation-codex
Version: 0.2.1
Summary: OpenInference instrumentation for Codex CLI/SDK telemetry
Author: OpenInference
License: Apache-2.0
License-File: LICENSE
Keywords: codex,openinference,opentelemetry,tracing
Requires-Python: <3.14,>=3.9
Requires-Dist: openinference-semantic-conventions>=0.1.0
Requires-Dist: opentelemetry-api>=1.25.0
Requires-Dist: opentelemetry-instrumentation>=0.46b0
Provides-Extra: otlp
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25.0; extra == 'otlp'
Requires-Dist: opentelemetry-sdk>=1.25.0; extra == 'otlp'
Provides-Extra: test
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25.0; extra == 'test'
Requires-Dist: opentelemetry-sdk>=1.25.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: ruff>=0.5.0; extra == 'test'
Description-Content-Type: text/markdown

# 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 |
| External callers | Orchestration layer | Run Codex and pass event streams into the proxy |
| Trace backends | OTLP collectors and sinks | Receive OTLP traces emitted by this package |

## How It Works

```mermaid
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](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 |

Caller workspaces should treat this repo as a black box and consume released package versions when they need 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](docs/DIAGRAM.md) | System diagram |
| [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | Contribution flow |
| [docs/SECURITY.md](docs/SECURITY.md) | Security scope and reporting |
| [docs/CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md) | Collaboration standards |
| [docs/CONTACT.md](docs/CONTACT.md) | Private contact path |
| [AGENTS.md](AGENTS.md) | Repo-specific agent guidance |
