V1 Telemetry Contract

This inventory defines the public telemetry surface ReqLLM preserves through the V1 release line. It records the current runtime behavior; it does not rename, remove, or reinterpret existing events.

Use ReqLLM.Telemetry.stable_events/0 for long-lived integrations and ReqLLM.Telemetry.events/0 when diagnostic tooling needs every emitted event.

Stability levels

• Stable means the event name, required top-level keys, value categories, meaning, and units will remain compatible throughout V1. Additive keys remain possible.
• Stable compatibility has the same guarantee, but exists primarily for established consumers. New consumers should prefer the indicated stable event.
• Experimental means ReqLLM will keep emitting the event in V1, but may add or refine its diagnostic detail. Existing names and keys will not be removed or silently repurposed in V1.

Complete event inventory

All elapsed native values use the VM's :native time unit. Convert them with System.convert_time_unit/3. Retry delay and request timeout options are in milliseconds. OpenTelemetry converts elapsed measurements to seconds without changing the native events.

Stable request metadata

The request base is present on request start, retry, stop, and exception:

The base keys remain present even when their value is nil. Additive metadata does not change the meaning of these keys.

Conditional request metadata

streaming.first_chunk_at is recorded for the first non-empty content output or tool call. Thinking-only and empty chunks do not start the timer. A stream stop, cancellation, or failure continues to use the regular request terminal event.

Nested stable shapes

reasoning always contains supported?, requested?, effective?, requested_mode, requested_effort, requested_budget_tokens, effective_mode, effective_effort, effective_budget_tokens, returned_content?, reasoning_tokens, content_bytes, and channel. Values are booleans, atoms, non-negative integers, or nil; channel is :none, :usage_only, :content_only, or :content_and_usage.

request_options may contain temperature, top_p, top_k, max_tokens, frequency_penalty, presence_penalty, stop_sequences, seed, n, stream?, encoding_formats, conversation_id, service_tier, receive_timeout, total_timeout, stream_idle_timeout, and max_retries. Inference values retain their normalized scalar/list shape; timeout and retry values are milliseconds/counts or :infinity where supported.

Request and response summaries intentionally vary by operation. They contain counts, byte sizes, dimensions, formats, durations, and booleans, never raw binary media or embedding vectors. New summary counters may be added in V1.

Usage correlation metadata

The token usage event always includes model. When available it also includes request_id, operation, mode, provider, and transport; direct low-level emitters historically may omit unavailable correlation values. The tokens map is the existing normalized usage shape and can add provider-neutral counters.

New billing integrations should read usage from request.stop, which combines usage with terminal outcome and timing. The token usage event remains supported for existing handlers.

Redaction contract

Payload capture defaults to :none. In that mode request events contain summaries, normalized options, server location, and usage, but no request_payload or response_payload keys.

With telemetry: [payloads: :raw], payload containers are opt-in but still sanitized:

• reasoning and thinking text is replaced by byte counts and a redaction marker;
• tool callbacks and compiled schemas are removed;
• binary images, files, and audio are represented by size and media metadata;
• embeddings are represented by vector count and dimensions;
• malformed tool argument diagnostics include identifiers and a reason, never the raw fragment.

Reasoning lifecycle events never contain raw reasoning text in either payload mode. Applications remain responsible for treating opt-in prompt, response, and tool argument text as sensitive user data.

Existing operational coverage

No extra V1 event is needed for the roadmap's identified cases:

• planning warnings remain on the request-plan/output diagnostic surfaces;
• terminal outcomes use finish_reason and exception error;
• configured total and idle budgets are present in request_options, while timeout failures preserve their typed error in exception metadata;
• shared stream materialization exposes its result through the response/output contracts and completes through the same request terminal event.

Adding parallel events for these cases would create competing sources of truth. If a future requirement cannot be represented without changing an existing meaning or unit, V1 will add a new namespaced or unit-bearing key/event and retain the legacy field.

OpenTelemetry compatibility

ReqLLM.OpenTelemetry.events/0 remains the request start, stop, and exception subset. Attaching the same handler id twice is collision-safe: :telemetry returns {:error, :already_exists} and only one handler remains installed.

The bridge continues to map:

• request start to span identity, provider, operation, request model, normalized request options, output type, conversation id, and server attributes;
• request stop to finish reasons, response identity/model, usage/cost, optional content, builtin-tool child spans, duration, token, and streaming histograms;
• request exception to error status/type, exception detail, and failure duration.

Native duration and time-to-first-output values remain in native units; mapped span attributes and histograms remain seconds. Content capture remains :none by default, and OpenTelemetry attachment does not enable native raw payload capture. The full attribute list and content modes are documented in the Telemetry guide.