Add reasoning, continuation, compaction, prompt attributes, and retrieval top_k

[lmolkova]

What does this change do?

Adds support for reasoning level, continuation, conversation compaction, and prompt template attributes to InferenceInvocation, and updates RetrievalInvocation to record integer gen_ai.retrieval.top_k.

Attributes added/updated

• gen_ai.request.reasoning.level: Request reasoning effort/level.
• gen_ai.request.previous_response.id: Previous response ID for continuation requests.
• gen_ai.conversation.compacted: Flag indicating conversation history was compacted.
• gen_ai.prompt.name: Prompt template identifier.
• gen_ai.prompt.version: Prompt template version.
• gen_ai.prompt.variable.<key>: Prompt template input variables.
• gen_ai.retrieval.top_k: Integer top-k documents requested (replaces gen_ai.request.top_k on retrieval spans).

Why?

Catches up with GenAI semantic conventions updates:

• Retrieval top-k: Replaces gen_ai.request.top_k (float) with dedicated integer gen_ai.retrieval.top_k on retrieval spans.
• Reasoning: Introduces gen_ai.request.reasoning.level for reasoning models.
• Continuation: Introduces gen_ai.request.previous_response.id for multi-turn continuations.
• Compaction: Introduces gen_ai.conversation.compacted for compacted context.
• Prompts: Standardizes prompt management metadata (name, version, and dynamic variable.<key> attributes).

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on maintainers · refreshed 2026-09-05 01:26 UTC

Merge when ready.

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.

[Copilot]

🟡 Changes recommended

Request attributes must be available when spans start so head samplers can inspect them.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Aligns inference and retrieval telemetry attributes with GenAI semantic conventions.

Changes:

• Adds reasoning, continuation, compaction, and prompt attributes.
• Migrates retrieval top_k to an integer attribute.
• Adds tests and changelog entries.

File summaries

File	Description
util/opentelemetry-util-genai/tests/test_utils.py	Tests new inference attributes.
util/opentelemetry-util-genai/tests/test_handler_retrieval.py	Tests integer retrieval top_k.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_retrieval_invocation.py	Updates retrieval top_k telemetry.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_inference_invocation.py	Implements new inference attributes.
util/opentelemetry-util-genai/.changelog/614.changed	Documents the retrieval attribute change.
util/opentelemetry-util-genai/.changelog/614.added	Documents the new inference attributes.

Review details

Suppressed comments (3)

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_inference_invocation.py:303

• gen_ai.prompt.variable.* is opt-in content and may contain sensitive data, but this loop records it regardless of the configured content-capture mode. In the default NO_CONTENT mode, the new test now exports Alice anyway; EVENT_ONLY also leaks the values onto the span. Gate these attributes independently for span versus event output, as _get_message_attributes(for_span=...) does, and test the disabled modes.

        if self.prompt_variables:
            for k, v in self.prompt_variables.items():
                attrs[f"{_GEN_AI_PROMPT_VARIABLE_PREFIX}{k}"] = str(v)

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_inference_invocation.py:140

• InferenceInvocation is exported from opentelemetry.util.genai.invocation, so this introduces Any into a public field even though every accepted value is only passed to str(). Use Mapping[str, object] instead (and remove the Any import after updating both declarations) to preserve the accepted shapes without disabling type checking.

        self.prompt_variables: Mapping[str, Any] | None = None

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_inference_invocation.py:415

• LLMInvocation remains publicly exposed through opentelemetry.util.genai.types, so this second public declaration also leaks Any. Use Mapping[str, object] here as well and remove the now-unused Any import.

    prompt_variables: Mapping[str, Any] | None = None

• Files reviewed: 6/6 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.