OpenTelemetry Codex
Use this skill when the operator asks to add OpenTelemetry (OTEL) instrumentation or telemetry export for Codex workflows in a repository.
Direct trigger phrase: Install OpenTelemetry.
Input Contract
Accept input as: PROJECT_PATH OTLP_ENDPOINT MODE
Mode:
plan: produce an implementation plan only
execute (default): apply configuration and validate telemetry emission
Examples:
$opentelemetry-codex /path/to/repo http://127.0.0.1:4318 execute
$opentelemetry-codex /path/to/repo https://otel-collector.internal:4318 plan
Preconditions
- Confirm the target project is in scope for modification.
- Detect project runtime/language before choosing instrumentation package(s).
- Confirm an OTLP endpoint exists (collector or vendor gateway).
- Configure Codex OTEL via
config.toml blocks, not shell env vars.
- Default local telemetry storage path is
PROJECT_PATH/OpenTelemetry.
Execution Workflow
- Baseline inventory:
- detect primary runtime and dependency manager,
- identify existing telemetry/logging framework.
- if
PROJECT_PATH/OpenTelemetry/install_opentelemetry.sh exists, prefer it as the default implementation path for consistency across clones.
- Configure Codex OTEL in
config.toml:
[otel]
service_name = "codex-agent" (or project-specific service name)
log_user_prompt = true (when operator wants prompt logging)
exporter = "otlp-http"
[otel.exporter."otlp-http"]
endpoint = "<OTLP_ENDPOINT>"
protocol = "json" (use binary when compact transport is preferred)
- Use supported exporter variants (
otlp-http, otlp-grpc, statsig, none) and valid protocol values when applicable.
- Do not rely on
OTEL_* shell environment variables for primary wiring.
- Install/Bootstrap (preferred path):
- run
"$PROJECT_PATH/OpenTelemetry/install_opentelemetry.sh" when available.
- this should prepare the local runtime and ensure telemetry output files exist.
- Add startup wiring so telemetry initializes at process start.
- default runner should be
"$PROJECT_PATH/OpenTelemetry/run_codex_with_otel.sh" for user-friendly operation.
- when using an OpenTelemetry Collector, configure a
file exporter writing to:
"$PROJECT_PATH/OpenTelemetry/otel-logs.jsonl"
"$PROJECT_PATH/OpenTelemetry/otel-traces.jsonl" (if traces are persisted locally)
Add a minimal smoke operation that should emit telemetry (single request/task run).
Validate:
- process starts successfully,
- OTEL exporter attempts/acknowledges delivery,
- collector/backend receives signal data (trace/log/metric as available).
- local files under
"$PROJECT_PATH/OpenTelemetry" are created and non-empty when file export is enabled.
- Document exact run commands and outputs for reproducibility.
Codex Data Capture Guidance
When instrumenting Codex workflows, capture at least:
- command execution lifecycle (start/end/error),
- task identifiers and branch/repo context,
- high-level agent role labels (
planner, researcher, etc.),
- latency and status outcomes.
Do not export secrets, raw credentials, or full sensitive payloads in spans/logs.
Use redaction or attribute allow-lists for safety.
Reporting Requirements
For each implementation, include:
- runtime and OTEL package(s) installed,
- exact config changes (file paths and
config.toml OTEL blocks),
- local storage path used:
PROJECT_PATH/OpenTelemetry,
- verification commands and resulting output,
- timestamp (UTC ISO 8601),
- confirmed telemetry signals observed,
- follow-up hardening recommendations.
1---2name: opentelemetry-codex3description: Install and configure OpenTelemetry for Codex-oriented workflows, including OTLP exporter setup, collector endpoint wiring, and validation that traces/logs/metrics are emitted and stored under PROJECT_PATH/OpenTelemetry.4---56# OpenTelemetry Codex78Use this skill when the operator asks to add OpenTelemetry (OTEL) instrumentation or telemetry export for Codex workflows in a repository.9Direct trigger phrase: `Install OpenTelemetry`.1011## Input Contract1213Accept input as: `PROJECT_PATH OTLP_ENDPOINT MODE`1415Mode:16- `plan`: produce an implementation plan only17- `execute` (default): apply configuration and validate telemetry emission1819Examples:20- `$opentelemetry-codex /path/to/repo http://127.0.0.1:4318 execute`21- `$opentelemetry-codex /path/to/repo https://otel-collector.internal:4318 plan`2223## Preconditions24251. Confirm the target project is in scope for modification.262. Detect project runtime/language before choosing instrumentation package(s).273. Confirm an OTLP endpoint exists (collector or vendor gateway).284. Configure Codex OTEL via `config.toml` blocks, not shell env vars.295. Default local telemetry storage path is `PROJECT_PATH/OpenTelemetry`.3031## Execution Workflow32331. Baseline inventory:34- detect primary runtime and dependency manager,35- identify existing telemetry/logging framework.36- if `PROJECT_PATH/OpenTelemetry/install_opentelemetry.sh` exists, prefer it as the default implementation path for consistency across clones.37382. Configure Codex OTEL in `config.toml`:39- `[otel]`40- `service_name = "codex-agent"` (or project-specific service name)41- `log_user_prompt = true` (when operator wants prompt logging)42- `exporter = "otlp-http"`43- `[otel.exporter."otlp-http"]`44- `endpoint = "<OTLP_ENDPOINT>"`45- `protocol = "json"` (use `binary` when compact transport is preferred)46- Use supported exporter variants (`otlp-http`, `otlp-grpc`, `statsig`, `none`) and valid protocol values when applicable.47- Do not rely on `OTEL_*` shell environment variables for primary wiring.48493. Install/Bootstrap (preferred path):50- run `"$PROJECT_PATH/OpenTelemetry/install_opentelemetry.sh"` when available.51- this should prepare the local runtime and ensure telemetry output files exist.52534. Add startup wiring so telemetry initializes at process start.54- default runner should be `"$PROJECT_PATH/OpenTelemetry/run_codex_with_otel.sh"` for user-friendly operation.55- when using an OpenTelemetry Collector, configure a `file` exporter writing to:56 - `"$PROJECT_PATH/OpenTelemetry/otel-logs.jsonl"`57 - `"$PROJECT_PATH/OpenTelemetry/otel-traces.jsonl"` (if traces are persisted locally)58595. Add a minimal smoke operation that should emit telemetry (single request/task run).60616. Validate:62- process starts successfully,63- OTEL exporter attempts/acknowledges delivery,64- collector/backend receives signal data (trace/log/metric as available).65- local files under `"$PROJECT_PATH/OpenTelemetry"` are created and non-empty when file export is enabled.66677. Document exact run commands and outputs for reproducibility.6869## Codex Data Capture Guidance7071When instrumenting Codex workflows, capture at least:72- command execution lifecycle (start/end/error),73- task identifiers and branch/repo context,74- high-level agent role labels (`planner`, `researcher`, etc.),75- latency and status outcomes.7677Do not export secrets, raw credentials, or full sensitive payloads in spans/logs.78Use redaction or attribute allow-lists for safety.7980## Reporting Requirements8182For each implementation, include:83- runtime and OTEL package(s) installed,84- exact config changes (file paths and `config.toml` OTEL blocks),85- local storage path used: `PROJECT_PATH/OpenTelemetry`,86- verification commands and resulting output,87- timestamp (UTC ISO 8601),88- confirmed telemetry signals observed,89- follow-up hardening recommendations.