Skip to content

feat(exporters): OpenTelemetry session exporter (traces + metrics) - #38

Merged
requie merged 1 commit into
mainfrom
feature/otel-exporter
Jul 28, 2026
Merged

feat(exporters): OpenTelemetry session exporter (traces + metrics)#38
requie merged 1 commit into
mainfrom
feature/otel-exporter

Conversation

@requie

@requie requie commented Jul 28, 2026

Copy link
Copy Markdown
Collaborator

Add OTelSessionExporter, a SessionExporter that translates the live session callback stream into OpenTelemetry traces and metrics so any OTLP backend can render per-agent integrity posture. Rides the existing register_exporter() seam with zero adapter changes; emits through the global OTel providers by default, so the deploying process configures resource and endpoint the standard way.

  • Traces: one trace per session (agentegrity.session root + a child span per evaluated event). Integrity data under a stable agentegrity.* namespace; gen_ai.* emitted opportunistically for interop, never load-bearing (those conventions are still in development).
  • Metrics: evaluation, enforcement-denial, and health counters; composite and per-layer score histograms; evaluation latency; active sessions. Low-cardinality dims — per-agent grouping rides service.name.
  • Chain integrity follows the 0.8.1 trust model: hash_linked (linkage only, never errors a span by itself) is kept distinct from signatures_verified (real tamper-evidence via verify_signatures, sets ERROR on failure). The signature attribute is omitted when no check ran so "not checked" != "failed"; pass trusted_keys to pin a real trust anchor.
  • Enforcement denials count block and escalate, since 0.8.1 made escalate fail closed. Health counting covers capture_failure, subagent_orphan, and the dynamic _overflow family from the 0.8.1 buffer caps.
  • Privacy: raw prompt/tool content is hashed into attributes, never stored verbatim; opt-in capture_content adds truncated span events.
  • Single-member topologies are dimensioned but not flagged multi_agent, so a degenerate topology of one does not inflate the fleet view.

Logs are recorded as span events plus counters; a dedicated OTLP logs signal is deferred until the Python logs SDK leaves experimental.

New [otel] extra. 18 tests against in-memory OTel span/metric readers (97% branch coverage on the module); no live collector needed in CI.

Add OTelSessionExporter, a SessionExporter that translates the live
session callback stream into OpenTelemetry traces and metrics so any OTLP
backend can render per-agent integrity posture. Rides the existing
register_exporter() seam with zero adapter changes; emits through the
global OTel providers by default, so the deploying process configures
resource and endpoint the standard way.

- Traces: one trace per session (agentegrity.session root + a child span
  per evaluated event). Integrity data under a stable agentegrity.*
  namespace; gen_ai.* emitted opportunistically for interop, never
  load-bearing (those conventions are still in development).
- Metrics: evaluation, enforcement-denial, and health counters; composite
  and per-layer score histograms; evaluation latency; active sessions.
  Low-cardinality dims — per-agent grouping rides service.name.
- Chain integrity follows the 0.8.1 trust model: hash_linked (linkage
  only, never errors a span by itself) is kept distinct from
  signatures_verified (real tamper-evidence via verify_signatures, sets
  ERROR on failure). The signature attribute is omitted when no check
  ran so "not checked" != "failed"; pass trusted_keys to pin a real
  trust anchor.
- Enforcement denials count block and escalate, since 0.8.1 made escalate
  fail closed. Health counting covers capture_failure, subagent_orphan,
  and the dynamic <channel>_overflow family from the 0.8.1 buffer caps.
- Privacy: raw prompt/tool content is hashed into attributes, never
  stored verbatim; opt-in capture_content adds truncated span events.
- Single-member topologies are dimensioned but not flagged multi_agent,
  so a degenerate topology of one does not inflate the fleet view.

Logs are recorded as span events plus counters; a dedicated OTLP logs
signal is deferred until the Python logs SDK leaves experimental.

New [otel] extra. 18 tests against in-memory OTel span/metric readers
(97% branch coverage on the module); no live collector needed in CI.
@cursor

cursor Bot commented Jul 28, 2026

Copy link
Copy Markdown

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

@requie
requie merged commit 2acdb39 into main Jul 28, 2026
9 checks passed
@requie
requie deleted the feature/otel-exporter branch July 28, 2026 19:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant