aip-otel-exporter

OpenTelemetry exporter for AIP integrity checkpoints and AAP verification results.

Python companion to @mnemom/aip-otel-exporter.

Installation

pip install aip-otel-exporter[otel]    # with OpenTelemetry SDK
pip install aip-otel-exporter[auto]    # with auto-instrumentation support
pip install aip-otel-exporter[all]     # all optional dependencies

Quick Start

Manual API

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter

from aip_otel_exporter import AIPOTelRecorder

# Set up OTel
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))

# Create recorder
recorder = AIPOTelRecorder(tracer_provider=provider)

# After an AIP integrity check:
recorder.record_integrity_check(signal)

# After an AAP verification:
recorder.record_verification(result)

# After an AAP coherence check:
recorder.record_coherence(result)

# After AAP drift detection:
recorder.record_drift(alerts, traces_analyzed=50)

Auto-instrumentation

from aip_otel_exporter import AIPInstrumentor

# Automatically wraps AIP/AAP functions to record spans
AIPInstrumentor().instrument()

# Now AIP/AAP calls are automatically traced:
# from aip import AIPClient
# signal = client.check(thinking_block, card)
# ^^^ span is recorded automatically

Direct Functions

For fine-grained control, use the recording functions directly:

from opentelemetry import trace
from aip_otel_exporter.manual import (
    record_integrity_check,
    record_verification,
    record_coherence,
    record_drift,
)

tracer = trace.get_tracer("my-app")
record_integrity_check(tracer, signal)
record_verification(tracer, result)

Span Hierarchy

Spans are created as children of the current active span:

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

aip.integrity_check span — 22 attributes + 2 GenAI SIG aliases

aap.verify_trace span — 8 attributes

aap.check_coherence span — 5 attributes

aap.detect_drift span — 2 attributes

Metrics

from aip_otel_exporter.metrics import (
    create_aip_metrics,
    record_integrity_metrics,
    record_verification_metrics,
    record_coherence_metrics,
    record_drift_metrics,
)

metrics = create_aip_metrics(meter_provider)
record_integrity_metrics(metrics, signal)

Performance

TypeScript benchmarks (Python exhibits comparable characteristics — duck-typed dict input, single span creation):

All operations are sub-0.01ms mean. Zero measurable overhead on hot paths.

Requirements

• Python >= 3.9
• OpenTelemetry SDK >= 1.20.0 (for [otel] extra)

License

Apache 2.0