Generic Grouping and Relationship Primitives for GenAI Semantic Conventions

[KazChe]

Area(s)

area:gen-ai

What's missing?

Two primitives that would let frameworks express structure without requiring new span types:

1. Sub-trace grouping - there is no way to say "these spans belong to the same logical unit" (a round, a task, a step) without creating a parent span solely for grouping purposes. Without this, backends must infer grouping from span order, which is brittle and breaks when retries, internal framework spans, or nested agents appear between the expected spans (as demonstrated in Adding ReAct Iterations Spans in Reasoning-Acting Agents semantic-conventions-genai#81 discussion).

2. Typed relationships - there is no way to express "this tool execution was triggered by that LLM output" for example or "this agent delegates to that agent". Without this, backends can not trace causality through an agent's decision chain. They can see that a tool was called, but not which LLM output caused it. OTel span links already exists in the spec (links-between-spans) and could serve this purpose, but they are not used anywhere in the GenAI conventions today.

Current State

GenAI semantic conventions (as of v1.40.0+) provide a solid foundation:

Type	Coverage
Agent Spans	create_agent, invoke_agent
Workflow Spans	invoke_workflow
LLM Spans	inference, embeddings, retrieval
Tool Spans	execute_tool
Evaluation	gen_ai.evaluation.result event
Identity	gen_ai.tool.call.id, gen_ai.agent.id, gen_ai.conversation.id

SIG is currently receiving many proposals where each introduce new span types to address specific GenAI patterns:

Issue	Proposed Span Type	Purpose
open-telemetry/semantic-conventions-genai#81	ReAct iteration span	Group LLM + tool cycles into rounds (ReAct)
open-telemetry/semantic-conventions-genai#55	gen_ai.workflow + gen_ai.task	workflow orchestration and task decomposition
open-telemetry/semantic-conventions-genai#37	gen_ai.task.*	Task lifecycle, subtasks, scheduling
open-telemetry/semantic-conventions-genai#57	orchestrate_tools	Group tool invocation cycles
open-telemetry/semantic-conventions-genai#86	gen_ai.skill	Skill lifecycle (loading, filtering, invocation)
open-telemetry/semantic-conventions-genai#41	gen_ai.agent.skills.*	Agent skill attributes
open-telemetry/semantic-conventions-genai#35	Tasks, actions, agents, teams, artifacts, memory	Full agentic ontology

Each of these proposals although well motivated, but taken together they represent an N+1 span type problem: every new GenAI pattern (rounds, tasks, skills, orchestration, guardrails, memory) gets its own span type with its own attributes

This creates several risks:

• Instrumentation burden: libraries must implement an ever growing set of span types
• Backend fragmentation: each backend must understand each span type to render it meaningfully
• Cross-framework inconsistency: what LangChain calls a "round", CrewAI calls a "task", and DSPy calls a "module step"

What already works well (pattern to follow)

OTel GenAI conventions already use generic primitives successfully:

• gen_ai.operation.name - an extensible enum (chat, invoke_agent, execute_tool etc) that lets frameworks declare what a span represents without needing a separate span definition per operation
• session.id - a generic attribute in the OTel registry (not GenAI-specific) that any domain can use for session grouping
• gen_ai.tool.type - a generic field (function, extension, datastore) rather than separate span types per tool kind.

These are "box of shapes" primitives: OTel defines the shape vocabulary, frameworks decide which shapes to use.

Describe the solution you'd like

1. Generic Grouping Attributes

Two new attributes in the gen_ai registry:

Attribute	Type	Description	Example
gen_ai.group.id	string	Identifier for a logical group of spans within a trace	"round-3", "task-research", "step-plan"
gen_ai.group.type	string (open enum)	Type of the logical group	"react_round", "task", "planning_step", "skill"

How this subsumes existing proposals:

The idea is straightforward: instead of defining a new span type for each concept, instrumentations add gen_ai.group.id and gen_ai.group.type as attributes on the spans they are already emitting today (e.g., chat, execute_tool, invoke_agent). The grouping is expressed by giving related spans the same gen_ai.group.id value, no new span definitions, no new parent spans required.

Concrete example of grouping ReAct rounds:

Consider a ReAct agent that takes 2 rounds to answer a question. Today an instrumentation already emits these spans:

invoke_agent research_agent
├── chat gpt-4              <- round 1: LLM decides to call a tool
├── execute_tool web_search  <- round 1: tool executes
├── chat gpt-4              <- round 2: LLM reviews result and calls another tool
├── execute_tool summarize   <- round 2: tool executes
└── chat gpt-4              <- final: LLM produces answer

Without a grouping primitive, a backend must guess which spans belong to which round by pattern-matching on span order which breaks when retries, internal framework spans, or nested agents appear (as discussed in open-telemetry/semantic-conventions-genai#81).

With the grouping primitive, the instrumentation simply tags each span with a shared group ID:

invoke_agent research_agent
├── chat gpt-4               {gen_ai.group.id: "round-1", gen_ai.group.type: "react_round"}
├── execute_tool web_search   {gen_ai.group.id: "round-1", gen_ai.group.type: "react_round"}
├── chat gpt-4               {gen_ai.group.id: "round-2", gen_ai.group.type: "react_round"}
├── execute_tool summarize    {gen_ai.group.id: "round-2", gen_ai.group.type: "react_round"}
└── chat gpt-4               (no group, means this is final answer, and not part of a react cycle)

The spans are the same ones the instrumentation already produces today. No new span types or wrapper spans are introduced. The only addition is two attributes (gen_ai.group.id and gen_ai.group.type) on those spans. Now any backend can:

• Count rounds by counting distinct gen_ai.group.id values where gen_ai.group.type is "react_round", in this case, 2
• Group spans by round for visualization display
• Alert on agents exceeding N rounds

No new span type was defined and no wrapper span was created. The structure is explicit and not inferred.

By "add" we mean: include gen_ai.group.id and gen_ai.group.type as referenced attributes in the existing span definitions in spans.yaml (e.g., under span.gen_ai.invoke_agent.client and span.gen_ai.execute_tool.internal), the same way attributes like gen_ai.agent.name or gen_ai.tool.call.id are referenced today. Instrumentations would then set these attributes when creating those spans.

Proposal	Current approach (new span type)	With grouping primitive (attributes on spans already being emitted)
#3419 ReAct Iterations Spans	Define a new react_iteration span that wraps each LLM+tool cycle	Add gen_ai.group.type = "react_round" and a shared gen_ai.group.id to the chat and execute_tool spans that the instrumentation already produces
#2912 Add Tasks	Define a new gen_ai.task span type	Add gen_ai.group.type = "task" and a shared gen_ai.group.id to the invoke_agent / execute_tool spans that already represent the work
#2993 Add Tool orchestration	Define a new orchestrate_tools span	Add gen_ai.group.type = "tool_cycle" and a shared gen_ai.group.id to the chat and execute_tool spans within the cycle
#3540 Add skill	Define a new gen_ai.skill span type	Add gen_ai.group.type = "skill" and a shared gen_ai.group.id to the spans emitted during skill execution

Key design decisions:

• gen_ai.group.type is an open enum, frameworks define their own values, OTel does not prescribe what a "round" or "task" means
• Multiple group memberships can be expressed by recording the attribute on multiple spans with the same gen_ai.group.id
• Requirement level: recommended on invoke_agent, execute_tool, and invoke_workflow spans
• This does not prevent frameworks from also creating parent spans for visualization hierarchy, it just provides an alternative that doesn't require it

2. Typed Span Links for GenAI Relationships

OTel span links already support expressing non-parent/child relationships between spans. The GenAI conventions should document and recommend their use.

Span links are not unknown to the GenAI SIG and they have come up in a few specific discussions:

• Spans for evaluation results in addition to events semantic-conventions-genai#33 proposes span links for evaluation -> target binding
• Gen AI Evaluation Result #2563 discusses them as a mechanism for correlating evaluation events with scored spans
• MCP semantic conventions #2083 references them in the context of MCP semantic conventions

However in each case span links are proposed as a solution for one narrow use case.They have not been considered as a general-purpose relationship primitive across GenAI conventions. This proposal suggests elevating them to that role.

Proposed guidance:

Instrumentations should consider using span links to express causal or semantic relationships between GenAI spans that are not captured by the parent-child hierarchy. When creating a span link, instrumentations should set an attribute on the link describing the relationship type.

Suggested link relationship types:

Relationship	Description	Example
triggered_by	The span was triggered by the linked span's output	Tool execution triggered by LLM tool_call response
delegates_to	This agent delegates work to the linked agent	parent agent invoking a sub-agent
evaluates	Evaluation targets the linked span	Evaluation event referencing the span it scores

Note: open-telemetry/semantic-conventions-genai#33 proposes span links for evaluation->target binding, validating this approach and this proposal is a generalization of that pattern.

Example:

invoke_agent main_agent
├── chat gpt-4                     (span_id: A)
│   └── response includes a tool_call: "search"
├── execute_tool search            (span_id: B, link: {span_id: A, type: "triggered_by"})
└── gen_ai.evaluation.result       (link: {span_id: B type: "evaluates"})

Relationship to Existing Proposals

This proposal is complementary to, not a replacement for the existing proposals. It offers a design principle:

• For proposals that need a new span type (for example Add Workflows/Agents/Tasks to gen_ai semantic-conventions-genai#55 workflows): the span type may still be valuable, but the grouping primitive provides a lighter weight alternative for simpler cases
• For proposals that primarily need grouping (#3419 ReAct rounds, Add tool orchestration span to gen-ai spans Semantic Conventions semantic-conventions-genai#57 tool orchestration) the grouping primitive may be sufficient without a new span type
• For proposals that need relationships (#2626 evaluation spans): typed span links provide the mechanism

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}

[lmolkova]

can you please describe the problem we're solving with this proposal and summarize what's being proposed in 1-2 sentences?

[KazChe]

Thank you for the feedback @lmolkova

can you please describe the problem we're solving with this proposal and summarize what's being proposed in 1-2 sentences?

Problem: GenAI conventions lack primitives for grouping related spans into logical units (rounds, tasks, steps) and expressing causal relationships between them, forcing each new concept to become its own span type

Proposal: Add gen_ai.group.id and gen_ai.group.type attributes to existing span definitions for grouping, and recommend typed span links for causal relationships so frameworks can express structure without new span types.

[Cirilla-zmh]

@KazChe Thanks for your proposal! The strengths of the proposal are in great detail, so I’d just like to raise my concerns. :)

Add gen_ai.group.id and gen_ai.group.type attributes to existing span definitions for grouping

This proposal does not seem available enough yet. Consider the following:

• A group may be nested, meaning that an operation can belong to groups across multiple dimensions. For example, it may belong to the "main agent", while also being part of the second ReAct iteration.
• Taking the ReAct step span as an example, if we do not introduce such a span and instead add a group.id to each of its intended child spans, the instrumentation implementation would become more difficult and complex.

recommend typed span links for causal relationships so frameworks can express structure without new span types.

It sounds promising, but it would be very difficult to implement, to the point that the additional cost introduced by this proposal may outweigh its advantages.

For example, in an agent built with LiteLLM and LangChain, how would I add a link from a execute_tool span created by LangChain to an inference span created by LiteLLM?

[KazChe]

Thank you @lmolkova, these are exactly the kind of concrete objections that make the proposal stronger (or reveal it needs rethinking) 🙂

The point about OTel context propagation being built for parent spans, not custom attributes, is well taken. I underestimated the instrumentation complexity that would shift it back to library authors, and regarding the cross-library span link scenario (LangChain+LiteLLM) I see that it is a clear gap I did not think through.

[lmolkova]

Problem: GenAI conventions lack primitives for grouping related spans into logical units (rounds, tasks, steps) and expressing causal relationships between them, forcing each new concept to become its own span type

how does this problem manifest for users? What is the real problem, why not having grouping is a problem?

[ckazz]

how does this problem manifest for users? What is the real problem, why not having grouping is a problem?

The userfacing manifestation: when a user opens a trace from an agentic workflow what they see is a flat or inconsistently structured list of spans with no reliable signal for which spans belong to the same logical unit. Debugging "why did my agent fail on attempt number 3?" requires manually correlating spans by timestamp. Observability platforms can not build generic iteration-level views or aggregations because the grouping signal isn't in the data in any standardized form.

The real problem is that the spec has no stable abstraction to offer for expressing logical structure in agentic workflows, so every time a new pattern emerges (ReAct iterations, planning phases, tool-selection rounds), the only recourse is to propose a new span type.

[Krishnachaitanyakc]

The N+1 span type problem is real — I've been thinking about this exact tension while
working on agent instrumentation.

One case where I think grouping and dedicated operations solve different problems:

An agent planning phase. The agent calls an LLM to decompose a task, then executes each
step. You could tag those spans with gen_ai.group.type = "plan", but you'd lose the
duration of the planning phase itself — how long did the agent spend deciding what to do
vs. actually doing it? The chat call that generates the plan is causally a child of
the planning decision, not a sibling that happens to share a group tag.

execute_tool exists as its own operation for the same reason — it could be a grouped
chat span, but tool-specific attributes and the timing of the tool phase justify a
dedicated operation.

So maybe: grouping for loose structural relationships (correlating spans in a ReAct round
or conversation turn), and dedicated operations where the phase has its own meaningful
duration and hierarchy. They'd work together rather than replace each other.

Where do you see the line between "this is just a grouping concern" and "this needs its
own operation"?

[KazChe]

Addressing @Cirilla-zmh feedback
Nested/multi-dimensional group membership:

"A group may be nested, meaning that an operation can belong to groups across multiple dimensions."

W3C Baggage supports multiple keys simultaneously, so a span can carry gen_ai.group.id=round-1, gen_ai.group.type=react_iteration, and gen_ai.agent.id=main-agent at the same time, each set via baggage.set_baggage() and copied to attributes by BaggageSpanProcessor. No arrays and no wrapper spans.

Cross-library span linking (LangChain + LiteLLM):

"How would I add a link from an execute_tool span created by LangChain to an inference span created by LiteLLM?"

Two findings here:

Grouping works without coordination Both instrumentors are registered on the same TracerProvider. BaggageSpanProcessor copies baggage to all spans regardless of which library created them LiteLLM's completion span carries gen_ai.group.id=round-1 even though LiteLLM knows nothing about the convention.

Causality requires payload-level propagation. When LiteLLM's completion span ends (after litellm.completion() returns, its context is no longer active, so in-process context propagation can't link the subsequent execute_tool span to it. The fix: inject traceparent into the tool call payload while the parent span is still active, and extract it at tool execution time. This is the same pattern HTTP uses for cross-service propagation, applied to LLM tool call envelopes.

Please see here for more details to this

---

Addressing @lmolkova question
"How does this problem manifest for users?"

The baseline demo shows it directly: a multi round ReAct agent produces a flat span list as chat, execute_tool, chat, execute_tool, chat with no signal for which spans belong to which round or which llm call triggered which tool. Debugging "why did my agent fail on attempt 3?" requires manually correlating spans by timestamp

---

Addressing @Krishnachaitanyakc question
"Where do you see the line between 'this is just a grouping concern' and 'this needs its own operation'?"

The prototype confirms your intuition, they complement each other. Grouping (Baggage) handles loose structural correlation: "these spans belong to the same round." Dedicated operations (execute_tool, chat) handle phases with their own meaningful duration and hierarchy. Payload traceparent bridges the two by establishing causal parent-child links between operations that grouping alone can not express.

---

prototype repo at: https://github.com/KazChe/otel-genai-semconv-grouping-causality-prototype
more detailed response here: https://github.com/KazChe/otel-genai-semconv-grouping-causality-prototype/blob/main/ISSUE_RESPONSE.md