audit-otlp

Bridge audit-trail's local HMAC-chained NDJSON to Sentry/Datadog-grade observability via OTLP/JSON spans. Closes audit findings F-021 + F-024. The exporter is stdlib-only — no OpenTelemetry SDK dep — so the operator can run it in air-gapped environments and let their own collector handle protobuf encoding and vendor routing. 1. Read-only on audit.jsonl. The exporter never mutates the source log. 2. Do NOT install the opentelemetry-sdk pip package. The exporter emits OTLP/JSON; the operator's collector translates to wire format. 3. Each emitted span MUST carry trace_id (32 hex) and span_id (16 hex). When the source row lacks trace_id, derive it from prev_hash so the forensic chain stays joinable to the observability stream. 4. Never echo secret values into spans. The audit.jsonl source has already masked them; pass-through only. 5. Treat the OTLP collector config as operator-owned — surface the example, don't deploy it.

<decision_tree> IF user asks "how do I send audit events to Datadog/Sentry": → Walk them through the three pieces: 1. The exporter at scripts/otel-exporter.py (stdlib, offline-first) 2. The example collector config at scripts/otel-config.example.yaml 3. The required env vars (DD_API_KEY, SENTRY_DSN, OTEL_EXPORTER_OTLP_ENDPOINT) → Show the canonical pipe: python ${CLAUDE_PLUGIN_ROOT}/scripts/otel-exporter.py
${CLAUDE_PLUGIN_ROOT}/state/audit.jsonl --follow
| curl -s -XPOST http://localhost:4318/v1/traces
-H 'content-type: application/json' --data-binary @-

IF user asks for a one-shot export (not follow mode): → Run: python "${CLAUDE_PLUGIN_ROOT}/scripts/otel-exporter.py"
"${CLAUDE_PLUGIN_ROOT}/state/audit.jsonl" → Pipe the stdout into their collector or save to a file.

IF user asks "what fields does the span carry": → Quote the closure schema verbatim: agent.id, tool.name, tool.duration_ms, tool.bytes_in, tool.bytes_out, network.dest_host, policy.outcome, error.type, plus trace_id and span_id. Source-row prev_hash rides as audit.prev_hash for forensic correlation.

IF user asks to smoke-test the exporter: → Pipe a synthetic line through and confirm OTLP/JSON shape: echo '{"event":"tool_use","ts":"2026-04-15T14:23:00Z","tool":"Write","duration_ms":42,"bytes_in":120,"bytes_out":0,"prev_hash":"GENESIS","policy_outcome":"allowed"}'
| python "${CLAUDE_PLUGIN_ROOT}/scripts/otel-exporter.py" /dev/stdin → Confirm: top-level resourceSpans key, span has traceId/spanId, attributes include tool.name + policy.outcome.

IF audit.jsonl is empty: → Tell the operator: nothing to export yet; events accumulate as the PostToolUse hook fires.

IF the operator asks about protobuf encoding: → "The exporter emits OTLP/JSON. The OTLP collector handles protobuf encoding to the backend's wire format. This is a deliberate offline- first choice — no OpenTelemetry SDK dependency." </decision_tree>

<output_format>

OTLP Export Status

• Exporter: scripts/otel-exporter.py
• Collector config: scripts/otel-config.example.yaml
• Source log: state/audit.jsonl (HMAC-chained, R8 EMA-tracked)
• Backends: Datadog LLM Observability, Sentry AI Agent Monitoring
• Closure: F-021 (OTLP traces) + F-024 (Sentry/Datadog parity)

Quick start

python scripts/otel-exporter.py state/audit.jsonl --follow \
  | curl -s -XPOST $OTEL_EXPORTER_OTLP_ENDPOINT/v1/traces \
         -H 'content-type: application/json' --data-binary @-

Span fields

Attribute	Source row field	Notes
agent.id	agent_id / session_id	session correlator
tool.name	tool	Write/Edit/Bash/etc
tool.duration_ms	duration_ms	int
tool.bytes_in/out	bytes_in/out	int
network.dest_host	dest_host	only for net-touching
policy.outcome	policy_outcome	allowed/blocked/warn
error.type	error_type	exception class
trace_id	derived from prev_hash	32 hex
span_id	UUID v4 (16 hex)	per span
</output_format>

<failure_modes>

• F02 fabrication: never claim spans were delivered to Datadog/Sentry without seeing the collector's confirmation. The exporter only emits OTLP/JSON; delivery is the collector's contract.
• F08 tool mis-invocation: don't shell out to the opentelemetry-sdk Python package. The exporter is stdlib-only by design.
• F14 version drift: if the operator's Datadog Agent is older than v7.42 it can't receive OTLP natively — point them at the datadog exporter block in otel-config.example.yaml as a fallback path. </failure_modes>