Traces and metrics for conversations.
Traces (OpenTelemetry)
| Span | Where | Attributes |
|---|---|---|
super_pi.gateway.request | each HTTP request | http.request.method, url.path, http.response.status_code |
super_pi.turn | one user submit, from input to idle | super_pi.conversation.id, super_pi.task.id |
chat <model> | one provider call | gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens |
execute_tool <name> | one tool call | gen_ai.tool.name, super_pi.tool.error |
A request span is the parent of the turn span, the turn span of its provider and tool spans.
A span that fails has status error and the reason as its message.
Spans are no-ops until an exporter is configured. Set OTEL_EXPORTER_OTLP_ENDPOINT
(for example http://localhost:4318) and the app exports over OTLP/HTTP. The standard
OTEL_SERVICE_NAME and OTEL_RESOURCE_ATTRIBUTES apply.
Metrics (:telemetry, Prometheus)
The same code emits :telemetry events: [:super_pi, :turn | :llm | :tool, :stop] with a
:duration in native units, plus :input_tokens and :output_tokens for :llm.
metrics/0 defines counters, duration histograms and token sums over them. The gateway
serves them at GET /metrics in Prometheus text format, behind the same authentication as
the rest of the API.
Prompt and completion text and tool arguments are never put in a span or a metric.
Summary
Functions
Makes ctx current in this process. Pair it with current_ctx/0.
The current trace context. Capture it before spawning a process that continues the work.
Runs fun inside a provider-call span. fun returns the responder's result, {:ok, message}
or {:error, reason}. Token counts come from message["usage"].
Telemetry.Metrics definitions for the events above.
The Prometheus text exposition of the metrics, or an empty string if the reporter is not running.
Starts a span, makes it current in this process, and returns a handle for stop_span/3.
parent is a context from current_ctx/0, or nil for the current one.
Ends the span and restores the previous context. status is :ok or {:error, reason}.
Returns the duration in native time units. attributes are added before it ends.
Runs fun inside a tool-call span. fun returns a tool result map; "is_error" marks failure.
Starts the span for a turn. Call turn_stop/2 when the conversation is idle again.
Types
Functions
Makes ctx current in this process. Pair it with current_ctx/0.
The current trace context. Capture it before spawning a process that continues the work.
Runs fun inside a provider-call span. fun returns the responder's result, {:ok, message}
or {:error, reason}. Token counts come from message["usage"].
Telemetry.Metrics definitions for the events above.
The Prometheus text exposition of the metrics, or an empty string if the reporter is not running.
Starts a span, makes it current in this process, and returns a handle for stop_span/3.
parent is a context from current_ctx/0, or nil for the current one.
Ends the span and restores the previous context. status is :ok or {:error, reason}.
Returns the duration in native time units. attributes are added before it ends.
Runs fun inside a tool-call span. fun returns a tool result map; "is_error" marks failure.
Starts the span for a turn. Call turn_stop/2 when the conversation is idle again.