feat(server-utils): Emit low-cardinality gen_ai agent span names when streaming - #23582
Merged
RulaKhaled merged 11 commits intoAug 28, 2026
Conversation
… streaming Fixes #23524 Co-Authored-By: Cursor <cursoragent@cursor.com>
Contributor
size-limit report 📦
|
Streamed invoke_agent names should be derivable from attributes, not only from the span name. Co-Authored-By: Cursor <cursoragent@cursor.com>
…-gen_ai-agent-span-names
…09-emit-low-cardinality-gen_ai-agent-span-names # Conflicts: # docs/migration/v11-end-state.md # packages/server-utils/src/ai/langchain/index.ts
RulaKhaled
marked this pull request as ready for review
August 27, 2026 11:03
RulaKhaled
requested review from
JPeer264 and
isaacs
and removed request for
a team
August 27, 2026 11:03
Lms24
reviewed
Aug 27, 2026
Lms24
left a comment
Lms24
left a comment
Member
There was a problem hiding this comment.
Had one last question, otherwise LGTM!
| expect(span.data?.[GEN_AI_FUNCTION_ID]).toBe('weather_agent'); | ||
| }); | ||
|
|
||
| it('uses `invoke_agent` when span streaming is enabled', () => { |
Member
There was a problem hiding this comment.
q: is gen_ai.function.id the same as gen_ai.agent.name? Just wondering if we can preserve the name here as well, similarly to the execute tool one.
Collaborator
Author
There was a problem hiding this comment.
they're different, gen_ai.agent.name is the name of the agent but gen_ai.function.id is more of a tracing label. i guess we can treat it same as execute tool
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…t` span names Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…agent` names Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
RulaKhaled
added a commit
that referenced
this pull request
Aug 27, 2026
…eaming (#23573) When span streaming is enabled, gen_ai inference span names follow the inference templates: `{operation} {model}` when a model is known, `{operation}` when it is not. Instrumented methods always have an operation, so the convention fallback `Generative AI model operation` is not emitted today. `traceLifecycle: 'static'` keeps the previous names (`chat unknown`). Known models stay in the name in both lifecycles (`chat gpt-4`). The inference ops the SDK emits are `gen_ai.chat`, `gen_ai.embeddings`, `gen_ai.generate_content` and `gen_ai.rerank` — the last three were only added to the conventions' inference rule in [sentry-conventions#579](getsentry/sentry-conventions#579), but the naming here is derived from the operation rather than hardcoded per op, so they were already covered. The Vercel AI channel path never emitted an `unknown` model sentinel, so its names were already conformant; a test now locks that in. The SDK emits no `gen_ai.responses` or `gen_ai.text_completion` spans. `gen_ai.execute_tool` spans keep the tool name in their name (`execute_tool getWeather`) — the tool name is a bounded, resolved value, so it behaves like a known model rather than a high-cardinality identifier. Agent ops (`gen_ai.invoke_agent`, `gen_ai.create_agent`, `gen_ai.handoff`) are out of scope here and handled in #23582 (`JS-3409`). Fixes #23525
6 tasks
…09-emit-low-cardinality-gen_ai-agent-span-names # Conflicts: # MIGRATION.md
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Lms24
approved these changes
Aug 28, 2026
RulaKhaled
deleted the
rolaabuhasna/js-3409-emit-low-cardinality-gen_ai-agent-span-names
branch
August 28, 2026 09:36
47 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
With span streaming enabled (the default),
gen_ai.invoke_agentnames follow the agent span name conventions:{operation} {name}fromgen_ai.agent.name,gen_ai.pipeline.nameorgen_ai.function_id, otherwise{operation}.In practice this only changes LangChain chain spans, and only their prefix. They were named
chain format_prompt, which does not lead with the operation like every other agent span; they are nowinvoke_agent format_prompt. The chain name itself is bounded, so it stays in the name. A chain the SDK cannot name falls back toinvoke_agentrather than carrying theunknown_chainsentinel, the same way a missing model is dropped in #23573.LangGraph agent names and Vercel AI
functionIds are unchanged in both lifecycles — both are bounded, low-cardinality values.The
pipeline.nameandfunction_idtemplates are added in getsentry/sentry-conventions#593. LangChain still emits its chain name onlangchain.chain.name; moving it togen_ai.pipeline.nameis tracked in JS-3452 and should land before v11 ships, so the emitted name matches a published template. Span names are unaffected by that move — they are built from the local chain name, not read back off the attribute.The other two ops in the agent rule need nothing: the SDK emits no
gen_ai.handoffspans, andgen_ai.create_agentwas dropped in v11. Neither is listed in the migration table.The migration entry lives in
MIGRATION.mdrather thandocs/migration/v11-end-state.md, which was removed by #23623.Fixes #23524