Use gen_ai.client.inference.duration metric instead of gen_ai.client.operation.duration and move inference signals to one file

[lmolkova]

Closes #215

Defines dedicated semantic conventions for Generative AI client inference operations in docs/gen-ai/client-inference.md and introduces the gen_ai.client.inference.duration metric.

Warning

This is a breaking change - gen_ai.client.inference.duration replaces gen_ai.client.operation.duration
for inference-specific cases.

As discussed in #249, this addresses the inference portion of the convention reorganization; other operations will follow in separate PRs.

Key changes:

• Adds gen_ai.client.inference.duration histogram metric.
• Renames streaming chunk metrics gen_ai.client.operation.time_to_first_chunk and gen_ai.client.operation.time_per_output_chunk to gen_ai.client.inference.time_to_first_chunk and gen_ai.client.inference.time_per_output_chunk.
• Renames client inference span type from gen_ai.inference.client to gen_ai.client.inference, aligning span types with metric namespaces ahead of span types becoming meaningful identifiers. Updates provider span refinement IDs to follow <provider>.gen_ai.client.inference. Span name will become meaningful once OTEP: Span type over OTLP opentelemetry-specification#5233 is implemented
• Consolidates inference client span, metrics, and operation details event documentation into docs/gen-ai/client-inference.md.

Open Questions

• Exception events per operation: Currently, exception events use generic gen_ai.client.operation.exception. Do we want an exception event per operation (e.g. gen_ai.client.inference.exception)?

Motivation

gen_ai.client.operation.duration is too vague and applies to any genai client calls. Inference, client agent invocations, fetching responses, uploading files, and cancelling runs are fundamentally different operations with different sets of attributes and characteristics.

The goal is to consistently name signals for inference operation, explicitly document attributes related to them, and document which span, metrics, and events are reported for inferenece calls.

Checklist

• Motivation section filled in above
• Reference scenarios updated for affected libraries
• Towncrier fragment added under changelog.d/ for any change to the conventions that a consumer would care about. Editorial changes (typos, pure rewording, repo tooling) don't need an entry.

[Copilot]

🟡 Changes recommended

Unresolved moderate findings affect metric consistency and reference coverage; a documentation nit also remains.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This breaking PR separates Generative AI inference conventions from generic client-operation conventions, adding dedicated metrics and consolidating documentation.

Changes:

• Adds gen_ai.client.inference.duration.
• Renames inference spans and streaming metrics.
• Updates provider refinements, scenarios, reports, documentation, and changelogs.

File summaries

File	Summary
templates/registry/markdown/span_macros.j2	Updates the span identifier example.
reference/tests/test_metrics.py	Updates tests for the renamed span key.
reference/src/semconv_genai/semconv_model.py	Registers renamed spans and the new metric.
reference/src/semconv_genai/report.py	Updates report links and mappings.
reference/src/semconv_genai/data_files.py	Updates span-name documentation.
reference/scenarios/vertexai/data.json	Updates committed Vertex AI inference signal names.
reference/scenarios/openai/data.json	Updates committed OpenAI inference signal names.
reference/scenarios/mistralai/data.json	Updates committed Mistral inference signal names.
reference/scenarios/litellm/data.json	Updates committed LiteLLM inference signal names.
reference/scenarios/groq/scenario.py	Records the new inference duration metric.
reference/scenarios/groq/data.json	Moderate (3 votes): restores the missing committed Groq span coverage while preserving the renamed span.
reference/scenarios/google-genai/data.json	Updates committed Google GenAI inference signal names.
reference/scenarios/cohere/data.json	Updates committed Cohere inference signal names.
reference/scenarios/claude-agent-sdk/data.json	Updates committed Claude Agent SDK inference signal names.
reference/scenarios/azure-openai/data.json	Updates committed Azure OpenAI inference signal names.
reference/scenarios/azure-ai-inference/data.json	Updates committed Azure AI inference signal names.
reference/scenarios/aws-bedrock/data.json	Updates committed Bedrock inference signal names.
reference/scenarios/anthropic/data.json	Updates Anthropic inference data; it still reports the old duration metric.
reference/scenarios/agent-framework/data.json	Updates Agent Framework inference data; it still reports the old duration metric.
reference/reports/inference-span.md	Updates inference span coverage.
reference/reports/gen-ai-client-operation-duration-metric.md	Updates the existing operation-duration coverage report.
reference/reports/gen-ai-client-inference-operation-details-event.md	Updates the inference event report link.
reference/reports/gen-ai-client-inference-duration-metric.md	Adds the new duration metric report.
reference/README.md	Updates reference coverage tables.
model/gen-ai/spans.yaml	Renames the inference span and refinements.
model/gen-ai/metrics.yaml	Adds and renames inference metrics. Moderate (3 votes): the prohibition conflicts with Anthropic and Agent Framework outputs still using the old metric. Moderate (2 votes): the new streaming signal definitions lack committed reference coverage.
model/gen-ai/events.yaml	Reattaches event attributes to the renamed span.
docs/gen-ai/README.md	Links the consolidated inference documentation.
docs/gen-ai/openai.md	Updates OpenAI inference references.
docs/gen-ai/inference.md	Adds consolidated inference conventions.
docs/gen-ai/gen-ai-spans.md	Moves inference content. Nit (3 votes): removes the trailing literal ->.
docs/gen-ai/gen-ai-metrics.md	Updates metric documentation and links.
docs/gen-ai/gen-ai-events.md	Links consolidated inference event documentation.
docs/gen-ai/azure-ai-inference.md	Updates Azure inference refinements.
docs/gen-ai/aws-bedrock.md	Updates Bedrock refinements.
docs/gen-ai/anthropic.md	Updates Anthropic refinements.
changelog.d/469.breaking.md	Updates the renamed span reference.
changelog.d/+.breaking.md	Documents the breaking signal changes.

Review details

Suppressed comments (1)

model/gen-ai/metrics.yaml:96

• This adds a new model signal, but no committed reference scenario records it. The Groq streaming scenario iterates response chunks and records only inference duration, so the repository does not demonstrate a value derived from consecutive output chunks. Add a real scenario emission based on the stream, or remove this signal until it has reference coverage.

  - name: gen_ai.client.inference.time_per_output_chunk

• Files reviewed: 37/38 changed files
• Comments generated: 4
• Review effort level: Lite (auto)

Note

Copilot is running an experiment and ran this review at Lite.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on the author · refreshed 2026-09-17 08:43 UTC

Move out of draft to request review.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.