Metadata-Version: 2.4
Name: openinference-instrumentation-codex
Version: 0.4.0
Summary: OpenInference traces for persisted Codex sessions and native OTLP telemetry
Author: OpenInference
License: Apache-2.0
License-File: LICENSE
Keywords: codex,openinference,opentelemetry,tracing
Requires-Python: <3.14,>=3.10
Requires-Dist: openinference-semantic-conventions>=0.1.0
Requires-Dist: opentelemetry-api>=1.25.0
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

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

```bash
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](AGENTS.md) | Concise file routing |
| [docs/AGENTS.details.md](docs/AGENTS.details.md) | Surface contracts, mappings, evidence, tooling, and validation |
| [docs/DIAGRAMS.md](docs/DIAGRAMS.md) | Visual package-flow orientation |
| [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | Contribution expectations |
| [docs/SECURITY.md](docs/SECURITY.md) | Vulnerability reporting |
| [CHANGELOG.md](CHANGELOG.md) | Release history |
