Prototype setting / getting inference span and event on / from the context

[DylanRussell]

Description

The creation of the inference span/event can happen at different levels in the call stack by different instrumentation libraries; we use the context to avoid duplication.

Key points:

• Most of the reuse logic is inside the GenAIInvocation base class so it can be extended to any invocation type.
• Spans are write-only: Attributes cannot be read back from a span once written. The invocation subclass explicitly applies safe start attributes (server.address and server.port), and instrumentations can set attributes (invocation.attributes[...]) or invocation properties (e.g., invocation.top_p = ...) post-creation to override them on the span and event.
• Instrumentations should check invocation.already_started: if True, they can skip request/response parsing and only set missing or override attributes.
• While point-in-time events cannot be enriched retroactively, inference events are created on the request path and only emitted on the response path, making in-place enrichment possible.
• Instrumentations both inside and outside this repo should adopt this pattern. Relevant semantic conventions PR: open-telemetry/semantic-conventions-genai#475.
• Includes google-genai as the reference implementation and scripts/prototype_inference_deduplication.py to demo the behavior.

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)

How has this been tested?

Unit tests

Checklist

• Followed the style guidelines of this project
• Changelog updated if the change requires an entry
• Unit tests added
• Documentation updated

[Copilot]

Pull request overview

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Adds a well-known context entry for the active GenAI inference span so different instrumentations can detect/reuse it and avoid emitting duplicate inference spans.

Changes:

• Introduces opentelemetry.util.genai.context helpers to set/get an inference span in OpenTelemetry context.
• Updates InferenceInvocation to attach its span under the inference-span context key during invocation start.
• Adds unit tests and documentation guidance for downstream instrumentations to check for an existing inference span.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
util/opentelemetry-util-genai/src/opentelemetry/util/genai/context.py	Adds context helpers and establishes the inference-span context key.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_invocation.py	Adds a context creation hook and uses it before attaching context.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_inference_invocation.py	Ensures inference invocations publish their span into the inference-span context key.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/init.py	Exposes the new context helper API at the package top level.
util/opentelemetry-util-genai/tests/test_context.py	Adds tests validating context behavior and interoperability.
AGENTS.md	Documents how to avoid duplicate inference spans using get_current_inference_span().
.github/instructions/instrumentation.instructions.md	Adds guidance to check get_current_inference_span() before creating a duplicate span.

---

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

[opentelemetry-pr-dashboard]

Pull request dashboard status

Closed · refreshed 2026-09-18 14:32 UTC

Status above doesn't look right?

• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.