Skip to main content
OTelSessionExporter turns the exporter callbacks into OpenTelemetry spans and metrics, so any backend your OpenTelemetry SDK already ships to can show integrity scores next to the rest of your traces. It writes through the OpenTelemetry providers in your process and has no destination of its own.

​
Install

The extra installs opentelemetry-api, opentelemetry-sdk and opentelemetry-exporter-otlp (1.20 or later). The module imports without them; constructing the exporter raises ImportError with the install hint.

​
Register it

By default the exporter uses the global tracer and meter providers, so configure the service name, OTLP endpoint and exporters the standard way, for example with OTEL_SERVICE_NAME and OTEL_EXPORTER_OTLP_ENDPOINT. Group telemetry by agent with the service.name resource attribute; the exporter keeps its own metric attributes low-cardinality.

​
Constructor

All arguments are keyword-only.
​
TracerProvider | None
default:"None"
Tracer provider to use instead of the global one.
​
MeterProvider | None
default:"None"
Meter provider to use instead of the global one.
​
bool
default:"False"
Also attach raw content, truncated to 512 characters, as span events. See Content and privacy.
​
Callable[[], AttestationChain] | None
default:"None"
Returns the adapter’s attestation chain. When set, the exporter verifies chain signatures at session end and records the result on the session span.
​
set[bytes] | None
default:"None"
Raw Ed25519 public keys that signatures must verify against. Used with chain_provider.
To report signature verification:
Without trusted_keys, a chain signed with any key verifies against the public keys embedded in its own records, so a forged chain passes. Pin the keys wherever the chain crosses a trust boundary. An unsigned record counts as a verification failure. Adapters sign records only when constructed with a signing_key, so on an adapter without one, chain_provider marks every session span as ERROR.

​
Traces

Each session is one trace.
  • agentegrity.session is the root span. It opens at on_session_start and closes at on_session_end.
  • agentegrity.<event_type> is a child span for every event, for example agentegrity.pre_tool_use. It starts and ends inside on_event.
If the exporter receives an event for a session it never saw start (it was registered late, or on_session_start failed), it opens a parentless agentegrity.session span with agentegrity.session.lazy = true so the event is not lost.

​
Session span attributes

Set at start: Set at end, from the session summary: hash_linked shows only that records are linked by unkeyed SHA-256 hashes, which anyone holding the chain can recompute, so a false value does not mark the span as an error. A failed signature verification sets the session span status to ERROR. When chain_provider is not set, the signature attributes are absent, which keeps “not checked” distinct from “failed”.

​
Event span attributes

agentegrity.topology.multi_agent is true only for topologies with two or more members.

​
Span events

  • agentegrity.enforcement.denial is added when the verdict is block or escalate, with the action and composite score.
  • agentegrity.health.<event_type> is added for instrumentation-health events, and the span status is set to ERROR. Health events are capture_failure, subagent_orphan and every <channel>_overflow event; see Events and wire format.

​
Metrics

agentegrity.enforcement.denials counts every block and escalate verdict. It does not check whether enforcement was on or whether an approval handler later approved the action, so treat it as a count of denying verdicts. The exporter does not emit OpenTelemetry log records. Enforcement and health signals appear as span events plus the counters above.

​
Content and privacy

Raw prompts, tool arguments and tool output never go into span attributes. For the five content keys listed above, the exporter writes a 16-character prefix of the value’s SHA-256 hash, so you can correlate identical content without seeing it. With capture_content=True, each present content value is also attached as a span event named agentegrity.content.<key> with the first 512 characters of the value. Span events can be dropped at the collector if you turn this on and later need to strip it.

​
Failure behavior

Every callback catches its own exceptions and logs a warning on the agentegrity.exporters.otel logger. A broken OpenTelemetry setup cannot reach the agent. describe() returns only {"type": "OTelSessionExporter"}, because the destination is set by your OpenTelemetry configuration.