Documentation
¶
Overview ¶
Package otel is the module overview for Scope's OpenTelemetry integration. It declares no API of its own; every adapter lives in a subpackage listed below.
The module adds traces, metrics, and model exception events to Core's capabilities from the outside. Development exporters write all three OTel signals to log/slog. Core itself never imports OpenTelemetry: a wrapper here is an ordinary decorator, and this module invents no tracer, meter, registry, or observation abstraction. The official API is the vendor-neutral layer.
Adapters ¶
Adapters are split by the contract they wrap, so one generic config never mixes different lifecycles:
- chat: chat call and lazy stream.
- embedding, image, moderation, rerank, speech, transcription: one modality each.
- eval: a generic Evaluator result.
- rag: retrieval.
- tool: tool invocation.
- history: history store and conversation listing.
- vectorstore: the vector-store capabilities.
- agent: managed Process activation, Step, and Effect, through an Observer bound as an agent.EventListener. WrapDispatcher propagates Effect spans into downstream calls. Agent and tool durations use gen_ai.invoke_agent.duration and gen_ai.execute_tool.duration, matching their invocation spans.
Chat and speech streaming record gen_ai.client.operation.time_to_first_chunk and gen_ai.client.operation.time_per_output_chunk at chunk arrival. Chat includes metadata-only deltas. Token metrics retain known usage even when generation fails. Response model identity is recorded only when reported by the provider. Cache and reasoning token counts are subsets of the totals.
The a2a and mcp modules are protocol integrations and use the official OTel API directly at their own call boundary, so this module has no adapter for them.
What never enters telemetry ¶
Prompts, queries, documents, media, audio, transcripts, and evaluation subjects stay out. An adapter records identity, counts, latency, outcome, and a stable low-cardinality error classification, because error.type is a metric dimension and a provider message would create one time series per string. Adapters project provider errors as classified types rather than raw messages. Model decorators emit gen_ai.client.operation.exception through an optional LoggerProvider at WARN severity. The official log API correlates these events with the failed model span; no separate logging facade or exporter configuration is introduced by the decorators.
Cancellation and deadlines use context.canceled and context.deadline_exceeded. Model adapters classify malformed requests and responses with their capability's stable error name. Other errors follow the official semconv.ErrorType convention, including a supplied ErrorType method or the concrete Go error type.
Development sinks ¶
The slog subpackage implements the three official SDK exporter interfaces, writing one slog record per span, metric batch, and log record. Exporter errors belong to the SDK's error handler, never the business return value. Flushing is synchronous rather than batched, and an error span is promoted to error level. In production the composition root swaps these for the official OTLP exporters; the wrappers and the Core protocol code do not change.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package agent adapts Agent Framework events to the official OpenTelemetry tracing and metrics APIs.
|
Package agent adapts Agent Framework events to the official OpenTelemetry tracing and metrics APIs. |
|
Package chat instruments Core chat capabilities with OpenTelemetry.
|
Package chat instruments Core chat capabilities with OpenTelemetry. |
|
Package embedding instruments Core embedding calls with OpenTelemetry.
|
Package embedding instruments Core embedding calls with OpenTelemetry. |
|
Package eval instruments generic Scope evaluation calls with OpenTelemetry.
|
Package eval instruments generic Scope evaluation calls with OpenTelemetry. |
|
Package history instruments conversation-history capabilities with OpenTelemetry.
|
Package history instruments conversation-history capabilities with OpenTelemetry. |
|
Package image instruments Core image-generation calls with OpenTelemetry.
|
Package image instruments Core image-generation calls with OpenTelemetry. |
|
internal
|
|
|
errortelemetry
Package errortelemetry owns the content-free projection of classified failures.
|
Package errortelemetry owns the content-free projection of classified failures. |
|
Package moderation instruments Core moderation calls with OpenTelemetry.
|
Package moderation instruments Core moderation calls with OpenTelemetry. |
|
Package rag instruments retrieval capabilities with OpenTelemetry.
|
Package rag instruments retrieval capabilities with OpenTelemetry. |
|
Package rerank instruments Core reranking calls with OpenTelemetry.
|
Package rerank instruments Core reranking calls with OpenTelemetry. |
|
Package slog sinks all three OpenTelemetry signals — Traces, Metrics, and Logs — into a log/slog logger, so every span, metric, and log line from any Scope module lands in one structured stream correlated by trace_id / span_id.
|
Package slog sinks all three OpenTelemetry signals — Traces, Metrics, and Logs — into a log/slog logger, so every span, metric, and log line from any Scope module lands in one structured stream correlated by trace_id / span_id. |
|
Package speech instruments Core speech-synthesis calls with OpenTelemetry.
|
Package speech instruments Core speech-synthesis calls with OpenTelemetry. |
|
Package tool instruments Core tool execution with OpenTelemetry.
|
Package tool instruments Core tool execution with OpenTelemetry. |
|
Package transcription instruments Core transcription calls with OpenTelemetry.
|
Package transcription instruments Core transcription calls with OpenTelemetry. |
|
Package vectorstore instruments Core vector-store capabilities with OpenTelemetry.
|
Package vectorstore instruments Core vector-store capabilities with OpenTelemetry. |