feat: Add GenAI agent/tool/retrieval semantic conventions to instrumentation-api-incubator by eternalcuriouslearner · Pull Request #19124 · open-telemetry/opentelemetry-java-instrumentation

eternalcuriouslearner · 2026-07-05T20:56:19Z

Summary

Extends GenAI support in instrumentation-api-incubator with operation types from the new
https://github.com/open-telemetry/semantic-conventions-genai repo, following the direction of #15268.

Adds GenAiOperationAttributesGetter, a shared parent interface exposing getOperationName and getOperationTarget. GenAiSpanNameExtractornow uses this interface to build<operation_name> span names across GenAI span types. The getter is the single source of truth for the operation name, keeping span names aligned withgen_ai.operation.name. Targets follow the spec: request model for inference, gen_ai.agent.namefor create/invoke agent,gen_ai.tool.nameforexecute_tool, and gen_ai.data_source.id` for retrieval.
Adds getter/extractor pairs for agent, tool, and retrieval spans:
- agent: gen_ai.agent.id, gen_ai.agent.name, gen_ai.agent.description,
  gen_ai.agent.version
- tool: gen_ai.tool.name, gen_ai.tool.description, gen_ai.tool.type,
  gen_ai.tool.call.id
- retrieval: gen_ai.data_source.id, with gen_ai.retrieval.query.text behind an explicit
  captureMessageContent opt-in because it may contain sensitive data
Adds inference attributes to the existing extractor: gen_ai.provider.name,
gen_ai.conversation.id, gen_ai.output.type, and gen_ai.request.choice.count
(only emitted when the value is not 1, per semconv guidance).
Renames the provider getter from getSystem to getProviderName. getProviderName is now the
abstract member, and getSystem remains as a deprecated default delegating to it for the
migration period. Bedrock and OpenAI chat/embeddings implementations are updated.

Notes for reviewers

Attribute keys are declared inline with // copied from GenAiIncubatingAttributes, matching the existing convention in this module. We avoid a production dependency on opentelemetry-semconv-incubating; a future PR can switch to the separate GenAI Java semconv artifact once it is published. I am going to work with @trask and update the dependency when a jar is published from the new genai semconv repository.
This intentionally includes breaking changes to the alpha API. External implementations of GenAiAttributesGetter must implement getProviderName, and GenAiSpanNameExtractor.create has a binary-incompatible signature change because it now accepts the parent interface.
Per-operation extractors intentionally do not emit gen_ai.provider.name; the surrounding instrumentor is expected to attach provider identity, matching Migrate generative AI semantic conventions to OTel 1.37.0 #15268.

Out of scope

Memory / plan / invoke_workflow operations
Value<?>-typed opt-in content attributes such as gen_ai.input.messages and gen_ai.retrieval.documents
GenAiInstrumenterFactory convenience builder
Adopting the future semconv-genai Java artifact

CC: @trask @Cirilla-zmh

Introduce comprehensive GenAI semantic-convention support: add new extractor and getter types for agents, tools, and retrieval (GenAiAgent*/GenAiTool*/GenAiRetrieval*), plus a GenAiOperationAttributesGetter for common operation attributes. Update GenAiAttributesExtractor/GenAiAttributesGetter to emit provider name (migrating from deprecated getSystem), conversation id, output type, and conditional request.choice.count handling; and change span-name logic to use an operation target (used by various span types). Add SpanNameExtractors for agents and tools and add unit tests for span naming and the new extractors. Update existing instrumentations (AWS Bedrock and OpenAI chat/embedding) to implement getProviderName while delegating getSystem for compatibility.

…d add retrieval top_k. Make gen_ai.provider.name the primary API and deprecate the legacy getSystem anchor (getSystem now defaults to getProviderName). Add support for gen_ai.retrieval.top_k: introduce a Long getTopK in GenAiRetrievalAttributesGetter and emit GEN_AI_RETRIEVAL_TOP_K in the retrieval attributes extractor (with necessary import and key). Remove two specialized span name extractor classes (GenAiAgentSpanNameExtractor, GenAiToolSpanNameExtractor) and update tests to use the unified GenAiSpanNameExtractor, inline expected attribute keys (avoiding deprecated GenAiIncubatingAttributes), and mock agent/tool getters with CALLS_REAL_METHODS where appropriate. Also remove redundant getSystem overrides from several provider-specific getters (Bedrock, OpenAI chat/embedding) since getProviderName is now the abstract/primary method.

Copilot

Pull request overview

This PR extends GenAI support in instrumentation-api-incubator to cover the new agent, tool, and retrieval operation types from the emerging semantic-conventions-genai spec, building on the direction of #15268. It introduces a shared GenAiOperationAttributesGetter parent interface exposing getOperationName/getOperationTarget, which GenAiSpanNameExtractor now uses to build <operation_name> <target> span names uniformly across GenAI span types. It also adds new getter/extractor pairs for agent, tool, and retrieval spans, extends the inference extractor with additional attributes, and renames the provider getter from getSystem to getProviderName (keeping a deprecated getSystem default for migration).

Changes:

New GenAiOperationAttributesGetter parent interface plus agent/tool/retrieval getter+extractor pairs, with GenAiSpanNameExtractor retargeted to the parent interface (intentional binary-incompatible alpha API change).
Extends GenAiAttributesGetter/GenAiAttributesExtractor with gen_ai.provider.name, gen_ai.conversation.id, gen_ai.output.type, and gen_ai.request.choice.count (only emitted when not 1).
Renames getSystem → getProviderName across the interface and Bedrock/OpenAI implementations, retaining a deprecated getSystem default.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`.../genai/GenAiOperationAttributesGetter.java`	New shared parent interface with `getOperationName`/`getOperationTarget`.
`.../genai/GenAiAttributesGetter.java`	Extends parent interface; adds `getProviderName`, deprecates `getSystem`, adds choice-count/output-type/conversation-id defaults.
`.../genai/GenAiAttributesExtractor.java`	Emits new inference attributes; conditional choice-count emission.
`.../genai/GenAiSpanNameExtractor.java`	Builds span name from `getOperationTarget`; expanded javadoc (retrieval bullet is incomplete).
`.../genai/GenAiAgentAttributesGetter.java` / `...Extractor.java`	New agent getter/extractor for `create_agent`/`invoke_agent`.
`.../genai/GenAiToolAttributesGetter.java` / `...Extractor.java`	New tool getter/extractor for `execute_tool`.
`.../genai/GenAiRetrievalAttributesGetter.java` / `...Extractor.java`	New retrieval getter/extractor with opt-in query-text capture (no test added).
`.../genai/GenAiAgentAttributesExtractorTest.java`, `GenAiToolAttributesExtractorTest.java`, `GenAiSpanNameExtractorTest.java`	New unit tests for agent, tool, and span-name behavior.
`.../awssdk/v2_2/internal/BedrockRuntimeAttributesGetter.java`	Renamed `getSystem` → `getProviderName`.
`.../openai/v1_1/ChatAttributesGetter.java`, `EmbeddingAttributesGetter.java`	Renamed `getSystem` → `getProviderName`.

opentelemetry-pr-dashboard · 2026-07-05T21:00:06Z

Pull request dashboard status

Status last refreshed: 2026-07-26 20:39:06 UTC.

Waiting on: Reviewers
Next step: Review the latest changes.

This automated status or its linked feedback items may be incorrect. If something looks wrong, please report it with the result you expected.

Add comprehensive test suite for GenAiRetrievalAttributesExtractor covering attribute extraction with and without query text, and handling of null values. Update span naming documentation to clarify that retrieval operations include the data source ID when available as per copilot feedback.

laurit · 2026-07-07T08:08:39Z

+
+  /** Returns the value of {@code gen_ai.agent.name}. */
+  @Nullable
+  String getAgentName(REQUEST request);


#15268 used getName. Both db and http getters also add Db and Http respectively to the method names so adding Agent here aligns with them. An alternative would be getGenAiAgentName but that might be too much.

Yeah I spent ton of time trying to come up with a good name and landed on this one as it adds more clarity. I am not keen on getName as it's not intuitive.

I am fine with renaming it to getGenAiAgentName if you feel it's more readable and clear.

@trask do you have any suggestions?

eternalcuriouslearner added 2 commits July 5, 2026 14:33

Copilot AI review requested due to automatic review settings July 5, 2026 20:56

eternalcuriouslearner requested a review from a team as a code owner July 5, 2026 20:56

Copilot started reviewing on behalf of eternalcuriouslearner July 5, 2026 20:56 View session

opentelemetry-pr-dashboard Bot mentioned this pull request Jul 5, 2026

Pull Request Dashboard #18435

Open

Copilot AI reviewed Jul 5, 2026

View reviewed changes

Comment thread ...ava/io/opentelemetry/instrumentation/api/incubator/semconv/genai/GenAiSpanNameExtractor.java Outdated

Comment thread ...telemetry/instrumentation/api/incubator/semconv/genai/GenAiRetrievalAttributesExtractor.java

laurit reviewed Jul 7, 2026

View reviewed changes

eternalcuriouslearner added 2 commits July 8, 2026 23:13

polish: aligning as per pr feedback.

4442eed

Merge branch 'main' into feat/add-genai-instrumentation-semconvs

5ec6ed1

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add GenAI agent/tool/retrieval semantic conventions to instrumentation-api-incubator #19124

feat: Add GenAI agent/tool/retrieval semantic conventions to instrumentation-api-incubator #19124
eternalcuriouslearner wants to merge 5 commits into
open-telemetry:mainfrom
eternalcuriouslearner:feat/add-genai-instrumentation-semconvs

eternalcuriouslearner commented Jul 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

opentelemetry-pr-dashboard Bot commented Jul 5, 2026 •

edited

Loading

Uh oh!

laurit Jul 7, 2026

Uh oh!

eternalcuriouslearner Jul 9, 2026

Uh oh!

eternalcuriouslearner Jul 9, 2026

Uh oh!

laurit Jul 9, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

eternalcuriouslearner commented Jul 5, 2026

Summary

Notes for reviewers

Out of scope

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

opentelemetry-pr-dashboard Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request dashboard status

Uh oh!

laurit Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

eternalcuriouslearner Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

eternalcuriouslearner Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

laurit Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

opentelemetry-pr-dashboard Bot commented Jul 5, 2026 •

edited

Loading