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; withotel.trace_exporterset, its native spans normalize through the traces edge too. - Cursor: correlates native
cursor.telemetryOTLP logs (Enterprise beta, metrics + logs only) into one canonical trace per activity burst, keyed oncursor.conversation.id. Chat spans carry per-request token usage; the wire reports tool calls only as metrics without correlation IDs, so canonical traces have noexecute_toolchildren. - OpenCode: renames its native Vercel AI SDK spans (
ai.streamText,ai.streamText.doStream,ai.toolCall) into oneinvoke_agent opencodecanonical 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: logsthe LLM chat spans are synthesized from theapi_request/api_errorlog 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 ignoresOTEL_SEMCONV_STABILITY_OPT_IN), directopentelemetry-util-genaiusers, 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-telemetryextension for the Pi coding agent. Each user input becomes oneinvoke_agent piroot per agentic iteration, withchat <model>andexecute_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 canonicalinvoke_agent openhandstrace 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 withOTEL_EXPORTER_OTLP_TRACES_ENDPOINTplusOTEL_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.
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/protobufLeave 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.
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.
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.yamlRegenerate the component's mdatagen artifacts after editing metadata.yaml:
./scripts/generate.shThe 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 thecoding_agentblock into the per-edgecodex:andcursor: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 keycapture_identitystays at the top level, andsignalsmoved into thecodex: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:
signalswas a top-level list ([logs, traces]) that gated each whole router, so turning a signal off also stopped unrelated edges; it is nowcodex.signals, a Codex-block list whose default enables the logs edge only. Setcodex: {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.
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.
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.yamlMount 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.
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.
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.shThe 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.0The 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.0The 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.
- OpenTelemetry Collector Builder
- OpenTelemetry Collector connectors
- OpenTelemetry GenAI semantic conventions
- Codex observability and telemetry
- Cursor OpenTelemetry Export
- Cursor OpenTelemetry wire reference
- Claude Code monitoring
- Claude Code third-party endpoints
- OpenCode Go models and providers
- OpenRouter API reference
- AWS S3 exporter
- File storage extension
- opentelemetry-instrumentation-openai-v2
- Strands Agents traces
- OpenHands SDK observability