Repository navigation
Define external references for generative AI inference content - #490
Conversation
|
|
f08e25a to
f5e81ce
Compare
There was a problem hiding this comment.
🟡 Changes recommended
The scenario does not cover the new span attributes, and the model omits the promised cardinality warnings.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Defines external GenAI content references and an event reporting asynchronous storage outcomes.
Changes:
- Adds three reference attributes and storage statuses.
- Adds a reference scenario covering stored, failed, and dropped uploads.
- Regenerates documentation and compliance reports.
File summaries
| File | Description |
|---|---|
model/gen-ai/registry.yaml |
Defines references and statuses. |
model/gen-ai/spans.yaml |
Adds references to spans. |
model/gen-ai/events.yaml |
Defines the result event. |
reference/scenarios/opentelemetry-util-genai/scenario.py |
Implements upload scenarios. |
reference/scenarios/opentelemetry-util-genai/README.md |
Documents scenario scope. |
reference/scenarios/opentelemetry-util-genai/pyproject.toml |
Configures dependencies. |
reference/scenarios/opentelemetry-util-genai/data.json |
Records conformance output. |
reference/scenarios/opentelemetry-util-genai/conformance.yaml |
Configures scenario execution. |
reference/src/semconv_genai/semconv_model.py |
Registers the event. |
reference/src/semconv_genai/report.py |
Adds its documentation link. |
reference/src/semconv_genai/data_files.py |
Orders the event in reports. |
reference/reports/invoke-agent-internal-span.md |
Reports reference coverage. |
reference/reports/invoke-agent-client-span.md |
Reports reference coverage. |
reference/reports/inference-span.md |
Reports reference coverage. |
reference/reports/gen-ai-content-storage-result-event.md |
Reports event coverage. |
reference/reports/gen-ai-client-inference-operation-details-event.md |
Reports reference coverage. |
reference/README.md |
Lists the new event scenario. |
docs/registry/attributes/gen-ai.md |
Regenerates the attribute registry. |
docs/gen-ai/openai.md |
Regenerates OpenAI conventions. |
docs/gen-ai/gen-ai-spans.md |
Documents external storage references. |
docs/gen-ai/gen-ai-events.md |
Documents the result event. |
docs/gen-ai/gen-ai-agent-spans.md |
Regenerates agent span tables. |
docs/gen-ai/azure-ai-inference.md |
Regenerates Azure conventions. |
docs/gen-ai/aws-bedrock.md |
Regenerates Bedrock conventions. |
docs/gen-ai/anthropic.md |
Regenerates Anthropic conventions. |
changelog.d/+.enhancement.md |
Adds the release note. |
Review details
Suppressed comments (2)
model/gen-ai/registry.yaml:951
- The PR description says the attribute notes call out high cardinality, but this warning only mentions sensitive paths. Add the omitted cardinality warning so instrumentation authors understand the span cost risk described by the proposal.
> This attribute may contain sensitive information such as storage paths.
model/gen-ai/registry.yaml:1001
- The PR description says the attribute notes call out high cardinality, but this warning only mentions sensitive paths. Add the omitted cardinality warning so instrumentation authors understand the span cost risk described by the proposal.
> This attribute may contain sensitive information such as storage paths.
- Files reviewed: 26/27 changed files
- Comments generated: 2
- Review effort level: Balanced
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
There was a problem hiding this comment.
🟡 Changes recommended
The scenario misreports upload-hook calls as inference and fails for non-empty tool definitions.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Suppressed comments (1)
reference/scenarios/opentelemetry-util-genai/scenario.py:193
- This second
chatspan also reports an inference operation even though the only library call is the upload completion hook. Perreference/CONTRIBUTING.md:101-113, a scenario may emit inference only for a library that owns the model-call boundary; move this reference-enrichment case to an actual provider or framework operation span instead.
with _reference_tracer.start_as_current_span(
"chat",
kind=SpanKind.CLIENT,
attributes={"gen_ai.operation.name": "chat"},
) as span:
- Files reviewed: 26/27 changed files
- Comments generated: 2
- Review effort level: Balanced
Pull request dashboard statusMerged · refreshed 2026-10-27 17:02 UTC Status above doesn't look right?
|
There was a problem hiding this comment.
🟡 Changes recommended
Several content-bearing span types lack matching reference attributes, and invoke-agent coverage remains unproven.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
- Files reviewed: 30/32 changed files
- Comments generated: 2
- Review effort level: Balanced
Zhuoxi2000
left a comment
There was a problem hiding this comment.
As a backend implementer, refs need a predictable stored format. Could the spec say writers SHOULD store the attribute's JSON? Otherwise readers cannot resolve refs across vendors.
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Directionally, looks good!
Process wise:
- please follow guidance established in open-telemetry/semantic-conventions#4102 - mark the original attributes with
unbounded_size: trueannotation. - we'll also need to wait for open-telemetry/opentelemetry-weaver-packages#75 and update version to new commit once it lands. [UPDATE] Merged, please update the version here to enable new policies
# Conflicts: # docs/gen-ai/gen-ai-events.md # docs/gen-ai/gen-ai-spans.md # reference/scenarios/anthropic/scenario.py
|
@lmolkova thanks, both items are in commit
The branch is also merged with current |
|
@lmolkova thanks, the comments from the 2026-10-13 review are addressed in
Annotating |
| note: | | ||
| This attribute identifies an external representation of the complete | ||
| value that would otherwise be recorded in `gen_ai.input.messages`. | ||
| Consumers MUST treat the URI as opaque. |
There was a problem hiding this comment.
Semantic conventions are not authoritative for consumers of telemetry, only for producers controlled by otel, plus it does not seem to be necessary to put any expectations on consumers.
An example of how it's used in the wild https://docs.cloud.google.com/stackdriver/docs/instrumentation/collect-view-multimodal-prompts-responses- the upload behavior and consumption are controlled by the same platform; credentials, destination, and consumption etc are all controlled by the same entity. It's easy to imagine that any other company can have a distro that uploads using their custom code to a storage of their preference with access model aligned with telemetry producer.
I think opaque can't come with MUST and I don't think it's helpful at all. Why do we care in semantic conventions about it?
…back Keep the content upload configuration from main next to the external reference wording, update the `changelog.d` fragment to name the four reference attributes, and let the Anthropic scenario upload into a `mkdtemp()` directory instead of flushing the private wrapped hook.

Description
Fixes #45.
Adds opt-in
_refattributes that point to complete system instructions, input messages, output messages and tool definitions held in external storage. Each value is an absolute URI, and the convention does not prescribe its scheme, layout, serialization, retention or access mechanism.Uploading content and emitting references should be enabled separately from the flags that record the inline content attributes. Following open-telemetry/semantic-conventions#4102, the four inline counterparts are annotated
unbounded_size: true, and the policy pin moves so the_refand unbounded policies run here.Motivation
Complete prompts, messages and tool schemas can be too large or too sensitive to put on spans, yet incident triage and quality evaluation need them. A reference lets an operator go from an inference span to the stored content without making inline capture the only option.
The three original reference names and the one-attribute-per-value shape come from issue #45 and open-telemetry/semantic-conventions#2750. Tool definitions are added because they have the same storage need as system instructions and
opentelemetry-util-genaialready uploads them.Prototype
The Anthropic scenario sends a Messages request to the mock server with system instructions, input messages and a tool definition, enables the upload hook through
OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload, and records all four references on the inference span and the operation details event.The references sit in the shared content group next to their inline counterparts, so the invoke agent spans inherit them as well. No agent scenario emits them yet.
Checklist
Towncrierfragment added underchangelog.d/for any change to the conventions that a consumer would care about