feat(core): Add low cardinality span name fallbacks (#23516)

Adds and exports fallback span name constants from `@sentry/core` which
we can use to migrate span names to be low-cardinality when span
streaming is enabled.

Doing this upfront to avoid merge/rebase conflicts when we split up the
name migration. Thanks @nicohrubec for the suggestion!

All fallbacks taken from:
https://getsentry.github.io/sentry-conventions/attributes/

ref #22350

Author: Lms24

.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 <https://getsentry.github.io/sentry-conventions/names/> 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
 

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';

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';

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';