Tracing (OpenTelemetry)

Opt-in OpenTelemetry tracing for STT, LLM, TTS, and tool calls.

Patter ships opt-in OpenTelemetry tracing that covers the four hot spots on the voice pipeline: STT, LLM, TTS, and tool calls. Every span carries the current getpatter.call.id so you can group by call in your backend.

Enable tracing

Tracing is disabled by default. Install the optional dependency and set the env flag:

pip install 'getpatter[tracing]'
export PATTER_OTEL_ENABLED=1
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318   # any OTLP/HTTP collector

Then call init_tracing once at process start — typically from the same module that creates your Patter client:

from getpatter.observability import init_tracing

init_tracing(
    service_name="my-voice-bot",
    otlp_endpoint="http://localhost:4318",
    resource_attributes={"deployment.environment": "staging"},
)

If PATTER_OTEL_ENABLED is not set, init_tracing returns False and every span becomes a no-op — zero cost when disabled.

Emitted spans

Span name	Fires	Attributes
getpatter.call	One per call (root span)	getpatter.call.id, getpatter.call.direction, getpatter.call.provider_mode
getpatter.stt	One per final transcript	getpatter.stt.text_len, getpatter.stt.confidence
getpatter.endpoint	One per detected end-of-utterance	getpatter.endpoint.silence_ms
getpatter.llm	One per LLM iteration (incl. tool rounds) — wraps the pipeline LLM call so TTFT is measured per turn	getpatter.llm.iteration, getpatter.llm.history_size, getpatter.llm.ttft_ms
getpatter.tts	One per synthesized sentence	getpatter.tts.text_len
getpatter.bargein	One per barge-in event	getpatter.bargein.cancelled_text_len
getpatter.tool	One per tool invocation	getpatter.tool.name, getpatter.tool.transport

All TS spans use the same getpatter.* namespace as Python (the legacy patter.* names were normalised in 0.5.3 — both SDKs now emit identical span names so a single dashboard query works across runtimes).

PII hygiene

Patter never exports user utterances, tool payloads, or LLM content as span attributes. Only sizes, counts, and identifiers are emitted — traces are safe to ship to a shared Jaeger / Honeycomb / Grafana Cloud instance.

Cost and latency attributes (patter.*)

Beyond the spans listed above, every billable hot path stamps patter.cost.* and patter.latency.* attributes on its span starting in 0.6.0. External aggregators (e.g. the patter-agent-runner acceptance suite) read these directly to compute per-call USD and latency without touching the SDK’s pricing table.

Attribute	Type	Where it fires
patter.call_id, patter.side	str	Every cost/latency span (routing tags)
patter.cost.telephony_minutes, patter.telephony, patter.direction	float / str	Twilio + Telnyx adapters on call end
patter.cost.stt_seconds, patter.stt.provider	float / str	Each final transcript (Deepgram, AssemblyAI, Whisper, OpenAI-Transcribe, Soniox, Speechmatics, Cartesia)
patter.cost.tts_chars, patter.tts.provider	int / str	Each synthesis (ElevenLabs, OpenAI, Cartesia, LMNT, Rime)
patter.cost.llm_input_tokens, patter.cost.llm_output_tokens, patter.llm.provider	int / int / str	Each completion (OpenAI, Anthropic, Google Gemini, Groq, Cerebras)
patter.cost.realtime_minutes, patter.realtime.provider	float / str	OpenAI Realtime + ElevenLabs ConvAI on session end
patter.latency.ttfb_ms, patter.latency.turn_ms	float	Per completed agent turn (pipeline mode)

The two routing tags (patter.call_id, patter.side) propagate via asyncio-safe ContextVars set at the top of the per-call WebSocket bridge, so all spans emitted under a call inherit them automatically — no manual wiring per span.

Attach a custom exporter (Patter._attach_span_exporter)

Embedding tools that observe Patter from the outside can wire their own exporter without touching PATTER_OTEL_ENABLED or init_tracing:

from opentelemetry.sdk.trace.export import SpanExporter
from getpatter import Patter

exporter: SpanExporter = my_exporter()  # any OTel SpanExporter
phone = Patter(...)
phone._attach_span_exporter(exporter, side="driver")  # or side="uut" (default)

side is stamped on every cost/latency span this Patter instance emits during its call lifecycle. It exists to disambiguate two-Patter-instances-in-one-process layouts (e.g. driver vs unit-under-test in agent-to-agent acceptance tests). Default is "uut" if you only have one instance.

The leading underscore signals this is not part of the customer-facing API surface — it is a stable, public-but-underscore hook for tooling.

Shutdown

Call shutdown_tracing() during graceful shutdown to flush any pending spans:

from getpatter.observability import shutdown_tracing

shutdown_tracing()

Troubleshooting

No spans appear → confirm PATTER_OTEL_ENABLED=1 is set in the process that calls init_tracing. Quick check:

from getpatter.observability import is_enabled
print(is_enabled())

Collector refuses spans → the endpoint defaults to OTLP/HTTP on port 4318. If you’re running the gRPC-only OTel Collector image, switch to otel/opentelemetry-collector-contrib or enable the HTTP receiver in your collector config.

Tracing has full TypeScript parity since 0.5.3 — span names, attributes, and PII hygiene are identical. See TS Tracing.