> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Observability with OpenTelemetry

> OpenTelemetry exporter for AIP integrity checkpoints and AAP verification results

**OpenTelemetry exporter for [AIP](/protocols/aip/specification) integrity checkpoints and [AAP](/protocols/aap/specification) verification results.**

Send AIP/AAP telemetry to any OTel-compatible observability platform — Langfuse, Arize Phoenix,
Datadog, Grafana — with zero custom code.

## Why

AIP and AAP produce rich alignment telemetry: integrity verdicts, concerns, verification results,
coherence scores, drift alerts. But this data is only useful if it's observable. This exporter
bridges the gap between protocol output and your existing observability stack by mapping everything
onto [OpenTelemetry](https://opentelemetry.io/) spans, events, and metrics.

```
AIP/AAP Protocol Output ──→ aip-otel-exporter ──→ OTel SDK ──→ Your Platform
                                                      │
                                                      ├── Langfuse
                                                      ├── Arize Phoenix
                                                      ├── Datadog
                                                      ├── Grafana / Tempo
                                                      └── Any OTLP endpoint
```

## Three integration layers

| Layer | TypeScript | Python | OTel SDK? | Use Case |
| - | - | - | - | - |
| **Manual API** | `@mnemom/aip-otel-exporter` | `aip-otel-exporter[otel]` | Yes | Full control, works everywhere |
| **Auto-instrumentation** | `@mnemom/aip-otel-exporter/auto` | `AIPInstrumentor` | Yes | Wraps AIP/AAP calls automatically |
| **CF Workers adapter** | `@mnemom/aip-otel-exporter/workers` | — | No | Cloudflare Workers edge runtime |

## Quick start

### TypeScript

```bash theme={null}
npm install @mnemom/aip-otel-exporter @opentelemetry/api
```

```typescript theme={null}
import { createAIPOTelRecorder } from "@mnemom/aip-otel-exporter";

const recorder = createAIPOTelRecorder({ tracerProvider });

recorder.recordIntegrityCheck(signal);    // AIP integrity check → span
recorder.recordVerification(result);       // AAP verification → span
recorder.recordCoherence(result);          // AAP coherence → span
recorder.recordDrift(alerts, count);       // AAP drift detection → span
```

### Python

```bash theme={null}
pip install aip-otel-exporter[otel]
```

```python theme={null}
from aip_otel_exporter import AIPOTelRecorder

recorder = AIPOTelRecorder(tracer_provider=provider)

recorder.record_integrity_check(signal)
recorder.record_verification(result)
recorder.record_coherence(result)
recorder.record_drift(alerts, traces_analyzed=50)
```

## Span hierarchy

Spans are created as children of the current active span via `context.active()`:

```
your_application_span
  ├── aip.integrity_check
  │    ├── event: aip.concern (one per concern)
  │    └── event: aip.drift_alert (when drift active)
  ├── aap.verify_trace
  │    └── event: aap.violation (one per violation)
  ├── aap.check_coherence
  └── aap.detect_drift
       └── event: aap.drift_alert (one per alert)
```

## Attributes reference

For the complete attributes and metrics reference, see [OTel Attributes](/specifications/otel-attributes).

### `aip.integrity_check` — 31 attributes + 4 GenAI SemConv fields

| Attribute | Type | Source |
| - | - | - |
| `aip.integrity.checkpoint_id` | string | checkpoint |
| `aip.integrity.verdict` | string | checkpoint (clear / review\_needed / boundary\_violation) |
| `aip.integrity.agent_id` | string | checkpoint |
| `aip.integrity.card_id` | string | checkpoint |
| `aip.integrity.session_id` | string | checkpoint |
| `aip.integrity.thinking_hash` | string | checkpoint (SHA-256) |
| `aip.integrity.proceed` | boolean | signal |
| `aip.integrity.recommended_action` | string | signal |
| `aip.integrity.concerns_count` | int | signal |
| `aip.integrity.analysis_model` | string | analysis\_metadata |
| `aip.integrity.analysis_duration_ms` | float | analysis\_metadata |
| `aip.integrity.thinking_tokens` | int | analysis\_metadata |
| `aip.integrity.truncated` | boolean | analysis\_metadata |
| `aip.integrity.extraction_confidence` | float | analysis\_metadata |
| `aip.conscience.consultation_depth` | string | conscience\_context |
| `aip.conscience.values_checked_count` | int | conscience\_context |
| `aip.conscience.conflicts_count` | int | conscience\_context |
| `aip.attestation.input_commitment` | string | attestation |
| `aip.attestation.chain_hash` | string | attestation |
| `aip.attestation.merkle_root` | string | attestation |
| `aip.attestation.signature_verified` | boolean | attestation |
| `aip.attestation.certificate_id` | string | attestation |
| `aip.attestation.zk_proven` | boolean | attestation |
| `aip.attestation.zk_proof_time_ms` | float | attestation |
| `aip.window.size` | int | window\_summary |
| `aip.window.integrity_ratio` | float | window\_summary (0.0-1.0) |
| `aip.window.drift_alert_active` | boolean | window\_summary |
| `aip.integrity.output_hash` | string | output\_analysis |
| `aip.integrity.output_tokens` | int | output\_analysis |
| `aip.integrity.output_truncated` | boolean | output\_analysis |
| `aip.integrity.analysis_scope` | string | output\_analysis |
| `gen_ai.evaluation.verdict` | string | GenAI SIG forward-compat |
| `gen_ai.evaluation.score` | float | GenAI SIG forward-compat |
| `gen_ai.system` | string | upstream LLM provider attribution |
| `gen_ai.request.model` | string | upstream LLM provider attribution |

`mnemom.span.role` (`customer` / `verifier`) is also set on some spans so you can filter
verifier-internal traffic out of per-provider SLOs.

All fields are duck-typed and optional-chained — a missing field is skipped rather than
throwing, so partial checkpoints still produce a valid (if sparser) span.

### `aap.verify_trace` — 8 attributes

| Attribute | Type |
| - | - |
| `aap.verification.result` | boolean |
| `aap.verification.similarity_score` | float |
| `aap.verification.violations_count` | int |
| `aap.verification.warnings_count` | int |
| `aap.verification.trace_id` | string |
| `aap.verification.card_id` | string |
| `aap.verification.duration_ms` | float |
| `aap.verification.checks_performed` | string (comma-separated) |

### `aap.check_coherence` — 5 attributes

| Attribute | Type |
| - | - |
| `aap.coherence.compatible` | boolean |
| `aap.coherence.score` | float (0.0-1.0) |
| `aap.coherence.proceed` | boolean |
| `aap.coherence.matched_count` | int |
| `aap.coherence.conflict_count` | int |

### `aap.detect_drift` — 2 attributes

| Attribute | Type |
| - | - |
| `aap.drift.alerts_count` | int |
| `aap.drift.traces_analyzed` | int |

## Metrics

9 metric instruments for aggregate monitoring:

| Metric | Type | Labels |
| - | - | - |
| `aip.integrity_checks.total` | Counter | verdict, agent\_id |
| `aip.concerns.total` | Counter | category, severity |
| `aip.analysis.duration_ms` | Histogram | verdict |
| `aip.window.integrity_ratio` | Histogram | — |
| `aip.drift_alerts.total` | Counter | — |
| `aap.verifications.total` | Counter | verified |
| `aap.violations.total` | Counter | type, severity |
| `aap.verification.duration_ms` | Histogram | — |
| `aap.coherence.score` | Histogram | compatible |

### Sideband findings (Trust Posture detectors)

A separate recorder, `recorder.recordSidebandFinding(finding)`, covers fleet-level sideband
detector firings (coherence, fault-line, fleet, drift — see [Tuning Sideband
Detection](/guides/sideband-detection)) rather than per-turn AIP/AAP results. It emits a
`safe_house.sideband.finding` span carrying `safe_house.sideband.source`, `.axis`, `.team_id`,
`.finding_count`, `.severity`, and `.pattern_type`, with one span event per affected agent.

## Dashboard templates

Pre-built dashboards are available in the [aip-otel-exporter repository](https://github.com/mnemom/aip-otel-exporter/tree/main/packages/typescript/dashboards):

* **grafana-aip-overview\.json** — Fleet-wide integrity monitoring
* **grafana-aip-detail.json** — Per-agent deep-dive
* **datadog-aip-overview\.json** — Datadog importable dashboard

See the [dashboards README](https://github.com/mnemom/aip-otel-exporter/blob/main/packages/typescript/dashboards/README.md) for import instructions.

## Platform examples

Integration examples are available in the [examples directory](https://github.com/mnemom/aip-otel-exporter/tree/main/packages/typescript/examples):

| Platform | File |
| - | - |
| Langfuse | `langfuse.ts` |
| Arize Phoenix | `arize-phoenix.ts` |
| Datadog | `datadog.ts` |
| Cloudflare Workers | `cloudflare-workers.ts` |

## Performance

Every recorder call (`recordIntegrityCheck`, `recordVerification`, `recordCoherence`,
`recordDrift`) and the Workers-adapter helpers (`createOTLPSpan`, `serializeExportPayload`) ship
with their own Vitest benchmark (`npm run bench` in the TypeScript package) — run it against your
own hardware and Node version for current numbers. All of them are attribute-mapping and JSON
serialization only (no network I/O), so the overhead they add on your hot path is sub-millisecond.

## Design principles

* **Duck-typed inputs** — No hard dependency on AIP/AAP packages. Works with any compatible shape.
* **Graceful degradation** — Missing fields are silently skipped, never throws.
* **Zero-overhead Workers** — CF Workers adapter uses only `fetch()` + `crypto`, no OTel SDK.
* **GenAI SIG forward-compat** — `gen_ai.evaluation.*` aliases for future OTel GenAI SIG alignment.

## Standards alignment

The exporter follows [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/)
for span naming and attribute structure. Forward-compatible aliases (`gen_ai.evaluation.*`) track
the emerging [OTel GenAI SIG](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/gen-ai)
conventions for AI/ML observability.

This exporter is part of the Mnemom trust plane:

* **[AIP](/protocols/aip/specification)** — Agent Integrity Protocol (per-turn thinking analysis)
* **[AAP](/protocols/aap/specification)** — Agent Alignment Protocol (behavioral verification)
* **aip-otel-exporter** — This package (observability bridge)

## See also

| Document | Description |
| - | - |
| [CHANGELOG](https://github.com/mnemom/aip-otel-exporter/blob/main/CHANGELOG.md) | Release history |
| [CONTRIBUTING](https://github.com/mnemom/aip-otel-exporter/blob/main/CONTRIBUTING.md) | Development setup and contribution guide |
| [Security Policy](https://github.com/mnemom/aip-otel-exporter/blob/main/docs/SECURITY.md) | Security policy and threat model |
| [TypeScript README](https://github.com/mnemom/aip-otel-exporter/blob/main/packages/typescript/README.md) | TypeScript package documentation |
| [Python README](https://github.com/mnemom/aip-otel-exporter/blob/main/packages/python/README.md) | Python package documentation |
| [Dashboards README](https://github.com/mnemom/aip-otel-exporter/blob/main/packages/typescript/dashboards/README.md) | Dashboard import instructions |

## Versions

| Package | Version |
| - | - |
| `@mnemom/aip-otel-exporter` (npm) | 0.13.0 |
| `aip-otel-exporter` (PyPI) | 0.5.0 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.