OpenTelemetry

OpenTelemetry

DeepSigma exports decision infrastructure telemetry via OpenTelemetry spans and metrics.

Exporter

OtelExporter (src/adapters/otel/exporter.py) converts sealed episodes, drift events, coherence reports, tool calls, and LLM completions into OTel span trees and metrics.

Exporter selection (environment-based):

1. OTLP gRPC — OTEL_EXPORTER_OTLP_ENDPOINT set (port 4317)
2. OTLP HTTP — endpoint ends with :4318 or /v1/traces
3. Console — fallback when no endpoint is configured

Span Registry

All span names, attribute keys, and metric names are registered in src/adapters/otel/spans.py. The CI test test_otel_span_registry enforces that every start_as_current_span and set_attribute call references a registered constant.

Span Types

Span	Description
decision_episode	Root span for a sealed decision episode
phase.{name}	Child span per phase (context, plan, act, verify)
drift_event	Drift detection event
coherence_evaluation	Coherence scoring event
tool_call	Individual tool invocation within a phase
llm.completion	LLM API call with token tracking
connector.{name}.{op}	Auto-instrumented connector operation

Metrics

Metric	Type	Description
sigma.episodes.total	Counter	Total decision episodes exported
sigma.episode.latency_ms	Histogram	End-to-end episode latency
sigma.drift.total	Counter	Total drift events
sigma.coherence.score	Gauge	Latest coherence score (0-100)
sigma.tool.latency_ms	Histogram	Per-tool-call latency
sigma.llm.latency_ms	Histogram	Per-LLM-call latency
sigma.llm.tokens.total	Counter	Total LLM tokens consumed

Connector Auto-Instrumentation

src/adapters/otel/instrumentation.py provides two mechanisms:

@traced decorator — wraps any method in an OTel span:

from adapters.otel.instrumentation import traced

class SharePointConnector:
    @traced("sharepoint", operation="list_items")
    def list_items(self, site_id: str) -> list:
        ...

InstrumentedConnector mixin — auto-wraps all public methods:

from adapters.otel.instrumentation import InstrumentedConnector

class SnowflakeConnector(InstrumentedConnector):
    connector_name = "snowflake"
    def query(self, sql: str): ...  # automatically instrumented

W3C Trace Context Propagation

from adapters.otel.instrumentation import inject_trace_context, extract_trace_context

# Outbound: inject traceparent into HTTP headers
headers = inject_trace_context({"Authorization": "Bearer ..."})

# Inbound: extract traceparent from incoming request
ctx = extract_trace_context(request.headers)

Related Pages

• Degrade Ladder — degradation triggers
• Runtime Flow — where telemetry is emitted
• SLOs and Metrics — metric targets