[cpsievert]

Ports the OpenTelemetry stack ellmer merged on 2026-10-20: tidyverse/ellmer#1143, tidyverse/ellmer#1147, tidyverse/ellmer#1148, tidyverse/ellmer#1149, tidyverse/ellmer#1174, tidyverse/ellmer#1175, plus the prerequisites they build on (tidyverse/ellmer#1142 time-to-first-token, tidyverse/ellmer#1160 Content tool results as otel parts).

Summary

Metrics alongside spans (all from the GenAI semantic conventions): gen_ai.client.inference.duration / operation.input_tokens / operation.output_tokens histograms, gen_ai.client.inference.usage.* monotonic counters (input/output/cache-read/reasoning tokens, tagged gen_ai.token.modality="unknown"), gen_ai.client.inference.time_to_first_chunk and time_per_output_chunk histograms for streams, gen_ai.execute_tool.duration, and gen_ai.invoke_agent.{duration,inference_calls,tool_calls}. Histograms are created with the semconv's advised explicit bucket boundaries when the installed opentelemetry-api supports explicit_bucket_boundaries_advisory (detected by signature, so older versions keep working). Instruments are created lazily from a module-level meter, so everything is a no-op without an SDK configured.

Richer spans. Chat spans now record server.address/server.port (via the new Provider.base_url), the request parameters actually sent (gen_ai.request.*, including gen_ai.request.stream and a best-effort reasoning level across OpenAI/Anthropic/completions/Google kwargs shapes), gen_ai.output.type for structured output, finish reasons (gen_ai.response.finish_reasons as a proper string[] — Python OTel supports array attributes where R's otel could not), cache-read/reasoning token counts, time to first chunk, and (with content capture enabled) gen_ai.tool.definitions, including the private structured-output tool used by Anthropic/Bedrock (new Provider.structured_output_tool() hook). gen_ai.provider.name now maps to the well-known semconv values. The invoke_agent span is now internal kind and records duration, inference/tool call counts, and token totals.

Reliability of statuses and errors. Successful chat spans get an OK status — but stamped lazily, only once turn assembly and cleanup have completed, because the SDK treats Ok as final (the spec's Ok > Error > Unset total order) and an earlier stamp would mask a late failure such as a truncated data_model response (regression tests included; ellmer's record_chat_otel_span_status() has the same latent masking and could use the same fix). Failed, cancelled (StreamController.cancel()), and interrupted (e.g. abandoned streams, keyboard interrupt) requests now report an error status and error.type on spans and the duration metrics; the sync agent loop now closes its inner generator deterministically (mirroring the async path) so abandoned streams unwind child-before-parent on all Python implementations. Tool results holding Content values (e.g. images) convert to otel parts instead of stringifying.

Also: Provider.value_reasoning_tokens() hook (OpenAI Responses + Completions implementations).

Verification

19 new OpenTelemetry tests in tests/test_otel.py (metrics via InMemoryMetricReader, span attributes, span kinds, cancel/interrupt/error paths, tool definitions, structured-output tool modes, advised bucket boundaries) plus updates to the existing suite. Full test suite (1370 passed), ruff, and pyright pass locally; docs/get-started/monitor.qmd gains a Metrics section and updated attribute lists.

Deliberate divergences from ellmer

• gen_ai.response.finish_reasons is a proper string[] (ellmer emits a scalar, blocked on No way to record a length-1 character vector as an array attribute r-lib/otel#48).
• Request params are recorded before the request, so failed requests carry them too (ellmer records after chat_perform succeeds; chatlas drops unsupported params at set-time, so no request-time filtering is needed).
• Tool definitions include user tools even when data_model is set (chatlas sends both in the request; ellmer suppresses user tools for structured-output requests).