From 7ee2034914ed703a0902583338ee90ac0bd6ca25 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 24 Aug 2026 14:08:10 +0200 Subject: [PATCH 1/2] feat(core): Add low cardinality span name fallbacks --- packages/core/src/constants.ts | 9 --- packages/core/src/shared-exports.ts | 3 +- packages/core/src/tracing/spans/spanNames.ts | 81 ++++++++++++++++++++ 3 files changed, 83 insertions(+), 10 deletions(-) create mode 100644 packages/core/src/tracing/spans/spanNames.ts diff --git a/packages/core/src/constants.ts b/packages/core/src/constants.ts index 725ce8de427d..7fdc380faf0d 100644 --- a/packages/core/src/constants.ts +++ b/packages/core/src/constants.ts @@ -1,11 +1,2 @@ export const DEFAULT_ENVIRONMENT = 'production'; export const DEV_ENVIRONMENT = 'development'; - -/** - * The name of a pageload span when span streaming is enabled and no parameterized route is - * available. Span names have to be low cardinality, so a raw URL must never be used instead. - * - * This is a span name only: it must never be set as the scope's transaction name, which is what - * error events are grouped by. - */ -export const PAGELOAD_SPAN_NAME_FALLBACK = 'Pageload'; diff --git a/packages/core/src/shared-exports.ts b/packages/core/src/shared-exports.ts index 8e9a72c851e0..453da4491bbc 100644 --- a/packages/core/src/shared-exports.ts +++ b/packages/core/src/shared-exports.ts @@ -10,6 +10,7 @@ export type { OfflineStore, OfflineTransportOptions } from './transports/offline export type { IntegrationIndex } from './integration'; export * from './tracing'; export * from './semanticAttributes'; +export * from './tracing/spans/spanNames'; export type { RawAttributes } from './attributes'; export { createEventEnvelope, createSessionEnvelope } from './envelope'; export { @@ -136,7 +137,7 @@ export { MAX_BODY_BYTE_LENGTH, } from './utils/request'; export type { MaxRequestBodySize } from './utils/request'; -export { DEFAULT_ENVIRONMENT, DEV_ENVIRONMENT, PAGELOAD_SPAN_NAME_FALLBACK } from './constants'; +export { DEFAULT_ENVIRONMENT, DEV_ENVIRONMENT } from './constants'; export { spanKindToName } from './spanKind'; export type { SpanKind, SpanKindNumber } from './spanKind'; export { addBreadcrumb } from './breadcrumbs'; diff --git a/packages/core/src/tracing/spans/spanNames.ts b/packages/core/src/tracing/spans/spanNames.ts new file mode 100644 index 000000000000..f8c3fd086d1d --- /dev/null +++ b/packages/core/src/tracing/spans/spanNames.ts @@ -0,0 +1,81 @@ +// This file contains constants for fallback span names to be used, when no +// better-suited, low-cardinality span name is available. +// Only relevant when span streaming is enabled. + +/** + * Fallback name for pageload spans when no better-suited span name is available. + * @see https://getsentry.github.io/sentry-conventions/names/#browser-pageload + */ +export const PAGELOAD_SPAN_NAME_FALLBACK = 'Pageload'; + +/** + * Fallback name for navigation spans when no better-suited span name is available. + * @see https://getsentry.github.io/sentry-conventions/names/#browser-navigation + */ +export const NAVIGATION_SPAN_NAME_FALLBACK = 'Navigation'; + +/** + * Fallback name for db spans when no better-suited span name is available. + * @see https://getsentry.github.io/sentry-conventions/names/#db-queries + */ +export const DB_SPAN_NAME_FALLBACK = 'Database operation'; + +/** + * Fallback name for gen_ai agent spans when no better-suited span name is available. + * @see https://getsentry.github.io/sentry-conventions/names/#gen_ai-agent + */ +export const GEN_AI_AGENT_SPAN_NAME_FALLBACK = 'Generative AI agent operation'; + +/** + * Fallback name for gen_ai model spans when no better-suited span name is available. + * @see https://getsentry.github.io/sentry-conventions/names/#gen_ai-inference + */ +export const GEN_AI_INFERENCE_SPAN_NAME_FALLBACK = 'Generative AI model operation'; + +/** + * Fallback name for graphql spans when no better-suited span name is available. + * @see https://getsentry.github.io/sentry-conventions/names/#graphql-graphql + */ +export const GRAPHQL_SPAN_NAME_FALLBACK = 'GraphQL Operation'; + +/** + * Fallback name for http.(client|server) spans when no better-suited span name is available. + * @see https://getsentry.github.io/sentry-conventions/names/#http + */ +export const HTTP_SPAN_NAME_FALLBACK = 'HTTP'; + +/** + * Fallback name for messaging spans when no better-suited span name is available. + * @see https://getsentry.github.io/sentry-conventions/names/#messaging + */ +export const MESSAGING_SPAN_NAME_FALLBACK = 'Messaging'; + +/** + * Fallback name for mcp server spans when no better-suited span name is available. + * @see https://getsentry.github.io/sentry-conventions/names/#mcp-server + */ +export const MCP_SERVER_SPAN_NAME_FALLBACK = 'MCP server operation'; + +/** + * Fallback name for mcp notification spans when no better-suited span name is available. + * @see https://getsentry.github.io/sentry-conventions/names/#mcp-notification + */ +export const MCP_NOTIFICATION_SPAN_NAME_FALLBACK = 'MCP notification'; + +/** + * Fallback name for resource spans when no better-suited span name is available. + * @see https://getsentry.github.io/sentry-conventions/names/#resource-resources + */ +export const RESOURCE_SPAN_NAME_FALLBACK = 'Resource'; + +/** + * Fallback name for router spans when no better-suited span name is available. + * @see https://getsentry.github.io/sentry-conventions/names/#routing-router + */ +export const ROUTER_SPAN_NAME_FALLBACK = 'Router'; + +/** + * Fallback name for request handler spans when no better-suited span name is available. + * @see https://getsentry.github.io/sentry-conventions/names/#resource-resources + */ +export const REQUEST_HANDLER_SPAN_NAME_FALLBACK = 'Request Handler'; From a8febdbe365d926fc942568dbb6de28b5ec4c53c Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 24 Aug 2026 14:17:47 +0200 Subject: [PATCH 2/2] update path in skill --- .agents/skills/port-span-names/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.agents/skills/port-span-names/SKILL.md b/.agents/skills/port-span-names/SKILL.md index 9d83279a7b92..f966b8830dd1 100644 --- a/.agents/skills/port-span-names/SKILL.md +++ b/.agents/skills/port-span-names/SKILL.md @@ -11,7 +11,7 @@ Span names must be low cardinality, per the [Sentry span name conventions](https This only applies when span streaming is enabled. With `traceLifecycle: 'static'` every span name must stay byte-identical to before. `pageload` was ported first. Read it as the reference implementation before starting: -`packages/core/src/spanNames.ts` (the constant), `packages/browser/src/tracing/browserTracingIntegration.ts` +`packages/core/src/tracing/spans/spanNames.ts` (the constant), `packages/browser/src/tracing/browserTracingIntegration.ts` (a start site plus the scope guard in `startBrowserTracingPageLoadSpan`), and `grep -rn PAGELOAD_SPAN_NAME_FALLBACK packages/*/src` for the full set of call sites. @@ -32,14 +32,14 @@ These are non-negotiable. Every one of them was arrived at by rejecting the alte 4. **Only the name changes.** Do not touch `sentry.source`, `url.template`, `http.route`, or any other attribute. They keep describing where the name came from. 5. **Do not derive the name from attributes in code.** The conventions describe names as attribute templates, but you implement them by reusing the value the site _already_ has for `url.template` / `http.route`. No attribute lookups, no generic template resolver. 6. **No helpers, no abstraction.** An inline ternary at each site. A shared `const` for the fallback string is fine (and required, see rule 6); a function that sets names or attributes is not. -7. **The fallback must never reach `scope.setTransactionName`.** The scope's transaction name is what error events are grouped by, so it keeps the raw URL or the parameterized route — never `Pageload`/`Navigation`/etc. Export the fallback as a constant from `packages/core/src/spanNames.ts` so the guard cannot drift. +7. **The fallback must never reach `scope.setTransactionName`.** The scope's transaction name is what error events are grouped by, so it keeps the raw URL or the parameterized route — never `Pageload`/`Navigation`/etc. Export the fallback as a constant from `packages/core/src/tracing/spans/spanNames.ts` so the guard cannot drift. 8. **`sentry.segment.name` must never diverge from the segment span's name.** Any code that stamps it on a child span has to read it off the segment span, not off the scope. ## 1. Look up the convention Read and find the op. Each op lists attribute templates in priority order, ending in a static fallback — that fallback is your name. Examples: `pageload` → `Pageload`, `navigation` → `Navigation`, database ops → `Database operation`. -Add it next to `PAGELOAD_SPAN_NAME_FALLBACK` in `packages/core/src/spanNames.ts` and export it from `shared-exports.ts`. Every package imports it from `@sentry/core` directly — no re-export from `@sentry/browser` is needed. +Add it next to `PAGELOAD_SPAN_NAME_FALLBACK` in `packages/core/src/tracing/spans/spanNames.ts` and export it from `shared-exports.ts`. Every package imports it from `@sentry/core` directly — no re-export from `@sentry/browser` is needed. ## 2. Find every site that names a span with this op