Skip to content

About

OpenTelemetry Collector connector for normalized Codex and Claude Code traces

Resources

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

488 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Coding-agent OpenTelemetry connector

An organization adopting AI coding agents receives telemetry in as many shapes as it runs agents. This connector normalizes those shapes into one canonical trace vocabulary so the same queries measure token usage — and the cost derived from it — across every agent. Latency and tool activity ride the same spans. Prompt text, tool arguments, and tool output never enter canonical output, so usage visibility does not require collecting what developers type. docs/design.md records the use case and design goals.

This repository provides an external OpenTelemetry Collector connector and an OCB-built distribution for coding-agent traces:

  • Codex: correlates structured codex.* OTLP logs into one canonical trace per user turn; with otel.trace_exporter set, its native spans normalize through the traces edge too.
  • Cursor: correlates native cursor.telemetry OTLP logs (Enterprise beta, metrics + logs only) into one canonical trace per activity burst, keyed on cursor.conversation.id. Chat spans carry per-request token usage; the wire reports tool calls only as metrics without correlation IDs, so canonical traces have no execute_tool children.
  • OpenCode: renames its native Vercel AI SDK spans (ai.streamText, ai.streamText.doStream, ai.toolCall) into one invoke_agent opencode canonical trace per model step, dropping internal instrumentation spans and all content attributes.
  • GitHub Copilot: normalizes native GenAI-semconv traces from Copilot CLI and VS Code Chat (invoke_agent/chat/execute_tool) through the shared GenAI-semconv edge
  • Claude Code: preserves its native span hierarchy and normalizes the interaction, LLM, and tool span names and attributes into the same canonical vocabulary; with claude_code.chat_source: logs the LLM chat spans are synthesized from the api_request/api_error log records instead, adding the per-request cost and API failure status the traces wire lacks.
  • GenAI semconv sources: normalizes native traces from opentelemetry-instrumentation-openai-v2 (legacy and latest semconv spellings; util-genai ≥ 1.0b0 ignores OTEL_SEMCONV_STABILITY_OPT_IN), direct opentelemetry-util-genai users, and the Strands Agents SDK into the same canonical vocabulary, stripping prompt/completion/tool content from canonical output.
  • Pi: normalizes native traces emitted by the @amaster.ai/pi-telemetry extension for the Pi coding agent. Each user input becomes one invoke_agent pi root per agentic iteration, with chat <model> and execute_tool <tool> children; exporter-local Langfuse baggage and raw usage blobs never reach canonical output.
  • OpenHands: normalizes native OpenTelemetry traces from the OpenHands SDK (Laminar instrumentation, scope lmnr.tracer) into one canonical invoke_agent openhands trace per conversation, keyed on the SDK's session id. Delegate subagents arrive as sibling traces sharing the conversation id. Streamed completions carry no token usage upstream. Enable export with OTEL_EXPORTER_OTLP_TRACES_ENDPOINT plus OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf.

The canonical tree is:

invoke_agent <agent>
├── chat <model>
└── execute_tool <tool>

The raw vendor logs and traces export separately. Normalization never copies prompt text, tool arguments, or tool output into canonical output, on any edge.

Canonical output uses a closed attribute vocabulary documented in docs/canonical-attributes.md, with a raw → canonical mapping matrix per harness under docs/harnesses/ and the upstream research record in docs/harnesses.md. For which OTel signal types (traces, logs, metrics) each harness natively supports, independent of what the connector normalizes, see docs/otel-signals.md.

Supported harnesses

These are the sources the connector sorts today, and what each needs. The logs edge (coding_agent on a logs pipeline) correlates structured logs into canonical traces. The traces edge (coding_agent/claude on a traces pipeline) normalizes native traces in place. Detection within an edge is automatic. No per-source connector setting exists.

Harness Edge Connector detection Harness-side configuration
Codex logs log records whose event.name starts with codex. [otel] block in user-level ~/.codex/config.toml
Codex (native traces) traces resource groups whose scope equals service.name and hold a Codex marker span (session_task.*, a codex.* attribute, or a codex.tool_result event) trace_exporter in the same [otel] block
Cursor logs instrumentation scope starting with cursor.telemetry Team Settings → OpenTelemetry Export (Enterprise beta), OTLP/HTTP to /v1/logs
Claude Code traces span names starting with claude_code. telemetry env vars with beta trace flag (below)
Claude Code (chats from logs) logs com.anthropic.claude_code.events records with event.name api_request or api_error, when claude_code.chat_source: logs same telemetry env vars plus OTEL_LOGS_EXPORTER=otlp
OpenCode traces instrumentation scope named exactly opencode experimental.openTelemetry: true plus OTLP endpoint env vars
GitHub Copilot traces instrumentation scope starting with github.copilot (GenAI-semconv edge) COPILOT_OTEL_ENABLED=true or set OTEL_EXPORTER_OTLP_ENDPOINT; OTLP/HTTP or file exporter (COPILOT_OTEL_FILE_EXPORTER_PATH)
openai-v2 / util-genai agents traces instrumentation scope starting with opentelemetry.instrumentation.openai_v2 or opentelemetry.util.genai standard OpenTelemetry SDK env vars
Strands Agents SDK traces instrumentation scope starting with strands.telemetry standard OpenTelemetry SDK env vars
Pi traces instrumentation scope starting with @amaster.ai/pi-telemetry, or resource telemetry.sdk.name with the same prefix install the @amaster.ai/pi-telemetry extension and enable its exporter (below)
OpenHands traces instrumentation scope lmnr.tracer whose spans carry OpenHands marker span names or the lmnr.association.properties.metadata.is_delegate=true flag OTEL_EXPORTER_OTLP_TRACES_ENDPOINT plus OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf

Minimal harness-side settings, as exercised by the e2e stacks:

Codex reads [otel] only from the user-level ~/.codex/config.toml and ignores project-local [otel] tables:

[otel]
log_user_prompt = false
exporter = { otlp-http = { endpoint = "http://collector:4318/v1/logs", protocol = "binary" } }

Cursor needs no client setting. An admin points Team Settings → OpenTelemetry Export at the Collector over OTLP/HTTP binary protobuf. Metrics and logs arrive server-side. The connector correlates the logs.

Claude Code exports its native beta traces when these variables reach its process:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://collector:4318/v1/traces
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf

Leave Claude Code's content gates unset so prompt text, tool arguments, tool output, and raw API bodies stay out of the raw destination. For claude_code.chat_source: logs, additionally export the logs signal (OTEL_LOGS_EXPORTER=otlp with the standard OTEL_EXPORTER_OTLP_LOGS_* endpoint/protocol variables) so the api_request/api_error records reach the connector.

OpenCode enables its tracer with "experimental": {"openTelemetry": true} in opencode.json and exports wherever OTEL_EXPORTER_OTLP_ENDPOINT points (set OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf). The native AI SDK tracer ships since opencode-ai v1.4.5 (2026-04-15, anomalyco/opencode#22526); the key is still under experimental in 1.19.3 (checked 2026-10-19).

Pi has no native OTel surface. Install the @amaster.ai/pi-telemetry extension (pi install npm:@amaster.ai/pi-telemetry, which registers itself under "packages" in ~/.pi/agent/settings.json) and enable its exporter in the same file:

{
  "pi-telemetry": {
    "serviceName": "pi",
    "otel": { "enabled": true, "endpoint": "http://collector:4318/v1/traces" }
  }
}

GenAI-semconv sources need no keys beyond the standard SDK environment (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf).

No support yet: Cline, Kilo Code CLI, Hermes Agent, and hook- or plugin-based surfaces such as Cursor hooks, other Pi extensions, and OpenCode plugins. docs/harnesses.md records what each exports and why it does not fit today.

Repository layout:

.
├── connector/codingagentconnector/  # the connector component (own Go module)
│   ├── config.go, factory.go        #   public Collector component surface
│   ├── metadata.yaml, doc.go        #   mdatagen source and generate directive
│   ├── internal/codex/              #   stateful log correlation and trace building
│   ├── internal/cursor/             #   burst correlation of native Cursor logs
│   ├── internal/claude/             #   stateless native-span normalization
│   ├── internal/claudelogs/         #   stateless Claude Code chat spans from logs
│   ├── internal/genai/, opencode/,  #   more stateless traces-edge normalizers
│   │   openhands/
│   └── internal/pi/                 #   stateless @amaster.ai/pi-telemetry normalization
├── e2e/                             # real agent runners and OTLP JSON validator
├── examples/otelcol-s3.yaml         # S3 export with persistent local queues
├── examples/otelcol-metrics.yaml    # delta-to-cumulative metrics to Prometheus remote write
├── builder-config.yaml              # pinned OCB distribution
├── compose.e2e-base.yaml            # shared collector included by every e2e stack
└── collector-config.yaml            # raw and canonical pipelines

The connector lives in its own module under connector/codingagentconnector/, matching the layout of components in opentelemetry-collector-contrib and upstreams with minimal changes.

Status

The component is at development stability. Codex reconstruction state is in memory and does not survive Collector restarts. See the design document for decisions, assumptions, and operational limits.

Build

The connector component (connector/codingagentconnector/) and the e2e validator (repo root) are separate Go modules, so run tests in both:

go test ./... && (cd connector/codingagentconnector && go test -race ./...)

Build the custom Collector container:

docker build -t otelcol-coding-agents:dev .

Or install OCB and generate the distribution directly:

builder --config builder-config.yaml
./dist/otelcol-coding-agents --config collector-config.yaml

Regenerate the component's mdatagen artifacts after editing metadata.yaml:

./scripts/generate.sh

Collector configuration

The connector can bridge either logs or traces into a traces pipeline:

connectors:
  coding_agent:
    capture_identity: true
    codex:
      turn_timeout: 10m
      reorder_window: 30s
      max_active_turns: 10000
      max_events_per_turn: 1000
      signals: [logs]
    cursor:
      turn_timeout: 10m
      reorder_window: 30s
      max_active_turns: 10000
      max_events_per_turn: 1000
    claude_code:
      chat_source: traces
  coding_agent/claude:

service:
  pipelines:
    logs/vendor:
      receivers: [otlp]
      exporters: [raw_logs, coding_agent]
    traces/native:
      receivers: [otlp]
      exporters: [raw_traces, coding_agent/claude]
    traces/canonical:
      receivers: [coding_agent, coding_agent/claude]
      exporters: [canonical]

Breaking change: the four tuning keys (turn_timeout, reorder_window, max_active_turns, max_events_per_turn) moved from the top level of the coding_agent block into the per-edge codex: and cursor: blocks. A tuning key left at the top level is now rejected as an unknown key, so move each value under the block whose edge it tunes. The connector-wide key capture_identity stays at the top level, and signals moved into the codex: block (see below).

The codex: and cursor: blocks each tune one logs edge and share nothing: codex: bounds Codex turn correlation, cursor: bounds Cursor activity bursts. Both use the same key names because both bound the same things — a maximum age (turn_timeout), a quiet window (reorder_window), the per-edge concurrent-state bound (max_active_turns), and the per-turn event bound (max_events_per_turn). Each block defaults to the values shown above.

reorder_window starts after the most recently received Codex event. A turn with at least one response.completed event finalizes when that window is quiet. A turn without completion finalizes by turn_timeout, shutdown, a new prompt in the same conversation, or bounded-state eviction.

One coding_agent instance on the logs pipeline claims both log sources: Codex records by their codex.-prefixed event names and Cursor records by their cursor.telemetry instrumentation scope. Cursor has no prompt or completion event on the wire, so each conversation's activity burst finalizes when reorder_window passes with no new record, by turn_timeout, at shutdown, or through bounded-state eviction.

The traces edge auto-detects Claude Code, OpenCode, OpenHands, Codex native spans, and GenAI-semconv sources, so every source enters the same pipeline.

claude_code.chat_source picks which signal emits canonical Claude Code chat spans: traces (default) keeps the native claude_code.llm_request spans; logs drops those spans and synthesizes chat spans from the claude_code.api_request / claude_code.api_error log records instead — the only way to put Claude Code's per-request cost and API failure status on the chat span. Exactly one source emits chat spans, so a request never duplicates. A deployment that splits Claude Code logs and traces across two connector instances must set the same value on both.

capture_identity defaults to true and applies to every coding_agent instance in the pipeline. It controls the PII-bearing identity keys (coding_agent.user.id, coding_agent.user.email, coding_agent.team.id, and the resource host.name) — an upgrade to this connector version starts emitting them immediately. Set capture_identity: false to restore the previous no-identity output. coding_agent.terminal.type carries no identity, so it ships regardless of this setting.

codex.signals chooses between duplicate implementations of the same data on different signals. Only Codex has duplicates — its logs edge and its native traces edge both carry the same turns — so it is a Codex setting rather than a connector-wide one, and the default is [logs] (the logs edge is the richer of the two; see docs/harnesses/codex.md). Valid values are logs and traces; a configured list replaces the default wholesale. With the default, a client sending both Codex signals gets one canonical trace per turn instead of two, and a client sending only native codex traces must set signals: [traces]. Edges with a single implementation (Claude Code, Cursor, Pi, OpenCode, OpenHands, GenAI-semconv) are always constructed and have no such key — claude_code.chat_source is the switch for the Claude Code logs/traces pairing, and it stays separate. Pipeline wiring is the other way to choose signals: a connector instance only sees the signals of the pipelines that list it as an exporter, as the example above does with coding_agent and coding_agent/claude.

Breaking change: signals was a top-level list ([logs, traces]) that gated each whole router, so turning a signal off also stopped unrelated edges; it is now codex.signals, a Codex-block list whose default enables the logs edge only. Set codex: {signals: [traces]} if your clients export Codex native traces only, or [logs, traces] to keep the previous duplicate-turn behavior.

Strands captures prompt and completion content in span events by default and its redaction is opt-in, so the raw trace destination receives content under default agent settings. Configure Strands redaction (gen_ai_unredacted_attributes in OTEL_SEMCONV_STABILITY_OPT_IN) or apply the same access policy to the raw destination and any content store. The canonical pipeline strips content-bearing attributes and events regardless.

Metrics reference deployment

examples/otelcol-metrics.yaml is a reference for the metrics signal, which the connector does not normalize: an OTLP receiver feeds the delta_to_cumulative processor and the prometheus_remote_write exporter. The conversion is needed because Claude Code (and Cursor) export delta temporality by default and the remote-write exporter drops non-cumulative monotonic sums and histograms. The processor keeps per-series state, so a multi-instance deployment must route metrics with routing_key: streamID and give each replica its own series with the collector_replica label (set COLLECTOR_REPLICA per replica; see docs/multi-instance-ha.md). Point PROMETHEUS_RW_ENDPOINT at a remote-write backend and run the example with ./dist/otelcol-coding-agents --config examples/otelcol-metrics.yaml.

S3 reference deployment

examples/otelcol-s3.yaml is a production-oriented reference that stores raw logs, raw native traces, and canonical traces under separate S3 prefixes. Each S3 exporter uses a bounded sending_queue backed by the Collector file-storage extension, so completed batches waiting for S3 can survive a Collector restart.

For more than one Collector instance, see examples/k8s-ha/ for the two-tier Kubernetes deployment and docs/multi-instance-ha.md for the analysis behind it.

Build the distribution, provide a pre-existing bucket, and run the example:

builder --config builder-config.yaml
export OTEL_S3_BUCKET=my-telemetry-bucket
export AWS_REGION=us-east-1
export OTEL_QUEUE_DIRECTORY=/var/lib/otelcol/sending-queue
./dist/otelcol-coding-agents --config examples/otelcol-s3.yaml

Mount OTEL_QUEUE_DIRECTORY on durable local storage with enough capacity; an ephemeral container filesystem defeats restart recovery. Each Collector replica should have its own local volume. The default file-storage limit is 1 GiB per queue database and changes with OTEL_QUEUE_MAX_SIZE_BYTES. Queue capacity is also bounded to 10,000 requests per exporter.

The example intentionally contains no access keys. Supply credentials through the standard AWS SDK credential chain, preferably with a workload, task, or instance role granting only the required bucket access. OTEL_S3_BASE_PREFIX defaults to coding-agent-otel and can be overridden.

The queues persist telemetry that has reached an exporter; they do not persist the connector's active Codex turn-correlation state. Also account for the raw telemetry privacy considerations below before enabling this configuration.

Tests

The default suite (go test) covers event parsing and coercion, config validation, deterministic trace construction/hierarchy/tokens/status/redaction, bounded-state/out-of-order/timeout/shutdown/turn-splitting, factory/lifecycle, Claude native-tree normalization, GenAI semconv normalization, and the e2e trace-validation assertions in e2e/validator.

The live, paid end-to-end tests (real Codex and Claude runs) are opt-in and documented separately in e2e/README.md. More opt-in stacks exercise the remaining harnesses — the openai-v2 ad-hoc agent, Strands, OpenCode, Pi, Copilot CLI, and OpenHands — and every stack shares the same collector base.

CI and releases

GitHub Actions runs formatting, shell syntax, lint, vet, unit/integration tests, race tests, custom Collector builds, Collector/Compose validation, container builds, and GoReleaser configuration checks. Live agent E2Es remain manual and never receive credentials in CI.

Run the same unpaid checks locally before pushing:

./scripts/check.sh

The script needs go, golangci-lint v2.13.1 (the version CI pins; install with go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.1), shellcheck, jq, docker, and goreleaser. It covers gofmt, shell syntax and shellcheck, golangci-lint on both modules, mdatagen freshness, vet, tests and race tests in both modules, Collector build and config validation, Compose validation including the credential-split assertions, container image builds, and goreleaser check — the full unpaid CI surface.

Pushing a semantic version tag such as v0.1.0 runs GoReleaser and creates a GitHub release containing cross-platform custom Collector archives and SHA-256 checksums:

git tag -a v0.1.0 -m "v0.1.0"
git push origin v0.1.0

The same tag also publishes a linux/amd64 container image to ghcr.io/nijave/otel-agent-trace-connector, tagged exactly as the git tag reads:

docker pull ghcr.io/nijave/otel-agent-trace-connector:v0.1.0

The image is the repository Dockerfile and carries the bundled collector-config.yaml as its default --config; deployments that export elsewhere should mount their own config over it.

References

About

OpenTelemetry Collector connector for normalized Codex and Claude Code traces

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages