feat(core): emit low cardinality request handler span names (#23533)

Name `handler` spans after the route they serve when span streaming is
enabled, or `Request handler` if no route set. Static mode left as is.

Drop Fastify and Hapi method, as the template dictates. NestJS and
Elysia resolve no route when the span starts. The NestJS callback name
stays on `nestjs.callback`. Elysia callback name is added to
`code.function.name`, so no information is lost by removing it from the
span name.

Also: correct `REQUEST_HANDLER_SPAN_NAME_FALLBACK`: the conventions
spell the fallback `Request handler`, and its `@see` link pointed at the
resource section.

closes #23533

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: isaacs

MIGRATION.md

@@ -627,6 +627,7 @@ The following span names were adjusted:
 | ------------ | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
 | `pageload`   | The parameterized route, or the raw URL path if the SDK couldn't resolve one (`/users/123`)                                 | The parameterized route, or `Pageload` if the SDK has none                                                           |
 | `router`     | Framework-specific, sometimes containing the raw URL (`/users/123`, `SvelteKit Route Change`)                               | The span's `http.route`, or `Router` if the SDK has none                                                             |
+| `handler`    | Framework-specific, often carrying the request method (`GET /users/:id`, `route-handler`, `getUser`)                        | The span's `http.route`, or `Request handler` if the SDK has none                                                    |
 | `graphql`    | The graphql phase and, for operations, the operation name (`query GetUser`, `graphql.parse`, `graphql.resolve user.0.name`) | The operation type, or the processing type where there is none (`GraphQL query`, `GraphQL parse`, `GraphQL resolve`) |
 | `resource.*` | The resource URL, relative to the page origin for same-origin resources (`/assets/app.js`)                                  | The resource domain (`cdn.example.com`), or `Resource` if the SDK has none                                           |
 
@@ -642,6 +643,8 @@ For the same reason, `useOperationNameForRootSpan` no longer renames the enclosi
 
 Only the Express, Koa and Hapi integrations resolve a route template for `router` spans. Angular, Ember and SvelteKit have none when the span starts, so their router spans are named `Router`.
 
+Only the Express, Fastify and Hapi integrations resolve a route template for `handler` spans. NestJS and Elysia have none when the span starts, so their request handler spans are named `Request handler`. The handler function name stays on an attribute: `nestjs.callback` for NestJS, and `code.function.name` for Elysia, which now sets it on every lifecycle handler span.
+
 Child spans of a service or root span carry its name in their `sentry.segment.name` attribute, so that changes with it. If you group or filter spans by segment name in dashboards or alerts, update those references.
 
 `ignoreSpans` is evaluated when a span **starts**, at which point a span might not yet have its final name. For example, an unresolved pageload span name is named `'Pageload'` and might receive its final, resolved route name later.

dev-packages/node-integration-tests/suites/tracing/fastify-streamed/instrument.mjs

@@ -0,0 +1,10 @@
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  tracesSampleRate: 1.0,
+  transport: loggingTransport,
+  traceLifecycle: 'stream',
+});

dev-packages/node-integration-tests/suites/tracing/fastify-streamed/scenario.mjs

@@ -0,0 +1,23 @@
+import { sendPortToRunner } from '@sentry-internal/node-integration-tests';
+import Fastify from 'fastify';
+
+const app = Fastify();
+
+app.get(
+  '/test-transaction/:id',
+  {
+    preHandler: function routePreHandler(_request, _reply, done) {
+      done();
+    },
+  },
+  async () => {
+    return {};
+  },
+);
+
+const run = async () => {
+  await app.listen({ port: 0, host: 'localhost' });
+  sendPortToRunner(app.server.address().port);
+};
+
+run();

dev-packages/node-integration-tests/suites/tracing/fastify-streamed/test.ts

@@ -0,0 +1,29 @@
+import { afterAll, describe, expect } from 'vitest';
+import { cleanupChildProcesses, createEsmAndCjsTests } from '../../../utils/runner';
+
+describe('fastify auto-instrumentation (streamed)', () => {
+  afterAll(() => {
+    cleanupChildProcesses();
+  });
+
+  createEsmAndCjsTests(__dirname, 'scenario.mjs', 'instrument.mjs', (createRunner, test) => {
+    test('names request handler spans after their route', async () => {
+      const runner = createRunner()
+        .expect({
+          span: container => {
+            const handlerSpans = container.items.filter(item => item.attributes['sentry.op']?.value === 'handler');
+
+            expect(handlerSpans).not.toHaveLength(0);
+            for (const span of handlerSpans) {
+              expect(span.name).toBe('/test-transaction/:id');
+            }
+          },
+        })
+        .start();
+
+      await runner.makeRequest('get', '/test-transaction/123');
+
+      await runner.completed();
+    });
+  });
+});

packages/core/src/integrations/express/patch-layer.ts

@@ -33,7 +33,7 @@ import { DEBUG_BUILD } from '../../debug-build';
 import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '../../semanticAttributes';
 import { SPAN_STATUS_ERROR, withActiveSpan } from '../../tracing';
 import { hasSpanStreamingEnabled } from '../../tracing/spans/hasSpanStreamingEnabled';
-import { ROUTER_SPAN_NAME_FALLBACK } from '../../tracing/spans/spanNames';
+import { REQUEST_HANDLER_SPAN_NAME_FALLBACK, ROUTER_SPAN_NAME_FALLBACK } from '../../tracing/spans/spanNames';
 import { startSpanManual } from '../../tracing/trace';
 import { debug } from '../../utils/debug-logger';
 import type { SpanAttributes } from '../../types/span';
@@ -168,10 +168,17 @@ export function patchLayer(
     }
 
     const client = getClient();
-    // With span streaming, span names have to be low cardinality, so router spans are named after their route.
-    const isStreamedRouterSpan = type === ExpressLayerType_ROUTER && !!client && hasSpanStreamingEnabled(client);
+    // With span streaming, span names have to be low cardinality, so router and request
+    // handler spans are named after their route.
+    const isStreamedSpan = !!client && hasSpanStreamingEnabled(client);
+    const isStreamedRouterSpan = isStreamedSpan && type === ExpressLayerType_ROUTER;
+    const isStreamedRequestHandlerSpan = isStreamedSpan && type === ExpressLayerType_REQUEST_HANDLER;
 
-    const spanName = isStreamedRouterSpan ? actualMatchedRoute || ROUTER_SPAN_NAME_FALLBACK : name;
+    const spanName = isStreamedRouterSpan
+      ? actualMatchedRoute || ROUTER_SPAN_NAME_FALLBACK
+      : isStreamedRequestHandlerSpan
+        ? actualMatchedRoute || REQUEST_HANDLER_SPAN_NAME_FALLBACK
+        : name;
 
     return startSpanManual({ name: spanName, attributes }, span => {
       let spanHasEnded = false;

packages/core/src/tracing/spans/spanNames.ts

@@ -76,6 +76,6 @@ 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
+ * @see https://getsentry.github.io/sentry-conventions/names/#web_server-request-handler
  */
-export const REQUEST_HANDLER_SPAN_NAME_FALLBACK = 'Request Handler';
+export const REQUEST_HANDLER_SPAN_NAME_FALLBACK = 'Request handler';

packages/core/test/lib/integrations/express/patch-layer.test.ts

@@ -542,6 +542,79 @@ describe('patchLayer', () => {
     ]);
   });
 
+  it('names request handler spans after their route when span streaming is enabled', () => {
+    spanStreamingEnabled = true;
+    const options: ExpressPatchLayerOptions = {};
+    const req = Object.assign(new EventEmitter(), {
+      originalUrl: '/a/b/c',
+    }) as unknown as ExpressRequest;
+
+    const layer = {
+      name: 'handle',
+      handle: vi.fn(),
+    } as unknown as ExpressLayer;
+
+    const res = Object.assign(new EventEmitter(), {}) as unknown as ExpressResponse;
+
+    storeLayer(req, '/a');
+    storeLayer(req, '/b');
+
+    patchLayer(() => options, layer, '/c');
+    layer.handle(req, res);
+
+    checkSpans([
+      {
+        status: { code: 0, message: 'OK' },
+        data: {
+          'express.name': '/a/b/c',
+          'express.type': 'request_handler',
+          'http.route': '/a/b/c',
+          'sentry.op': 'handler',
+          'sentry.origin': 'auto.http.express',
+        },
+        description: '/a/b/c',
+      },
+    ]);
+    res.emit('finish');
+    checkSpans([]);
+  });
+
+  it('falls back to a static request handler span name when the route is unknown', () => {
+    spanStreamingEnabled = true;
+    const options: ExpressPatchLayerOptions = {};
+    const req = Object.assign(new EventEmitter(), {
+      originalUrl: '/abcdef',
+    }) as unknown as ExpressRequest;
+
+    const layer = {
+      name: 'handle',
+      handle: vi.fn(),
+    } as unknown as ExpressLayer;
+
+    const res = Object.assign(new EventEmitter(), {}) as unknown as ExpressResponse;
+
+    storeLayer(req, '/a');
+    storeLayer(req, '/b');
+
+    patchLayer(() => options, layer, '/c');
+    layer.handle(req, res);
+
+    checkSpans([
+      {
+        status: { code: 0, message: 'OK' },
+        data: {
+          'express.name': '/a/b/c',
+          'express.type': 'request_handler',
+          'sentry.op': 'handler',
+          'sentry.origin': 'auto.http.express',
+        },
+        description: 'Request handler',
+      },
+    ]);
+    res.emit('finish');
+    checkSpans([]);
+  });
+
   it('handles case when route does not match url', () => {
     const onRouteResolved = vi.fn();
     const options: ExpressPatchLayerOptions = { onRouteResolved };

packages/elysia/src/withElysia.ts

@@ -1,13 +1,22 @@
-import { SENTRY_SEGMENT_NAME_SOURCE, HTTP_ROUTE, URL_FULL, URL_PATH } from '@sentry/conventions/attributes';
+import {
+  SENTRY_SEGMENT_NAME_SOURCE,
+  CODE_FUNCTION_NAME,
+  HTTP_ROUTE,
+  URL_FULL,
+  URL_PATH,
+} from '@sentry/conventions/attributes';
 import { MIDDLEWARE } from '@sentry/conventions/op';
 import type { Span } from '@sentry/core';
 import {
   captureException,
   continueTrace,
   getActiveSpan,
+  getClient,
   getIsolationScope,
   getRootSpan,
   getTraceData,
+  hasSpanStreamingEnabled,
+  REQUEST_HANDLER_SPAN_NAME_FALLBACK,
   SEMANTIC_ATTRIBUTE_SENTRY_OP,
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
   setHttpStatus,
@@ -115,8 +124,13 @@ function instrumentLifecyclePhase(phaseName: string, listener: TraceListener, ro
   }
 
   void listener(process => {
+    const client = getClient();
+    // With span streaming, span names have to be low cardinality. Elysia resolves the
+    // route only after the handler ran, so request handler spans use the static fallback.
+    const isStreamedRequestHandlerSpan = op === 'handler' && !!client && hasSpanStreamingEnabled(client);
+
     const phaseSpan = startInactiveSpan({
-      name: phaseName,
+      name: isStreamedRequestHandlerSpan ? REQUEST_HANDLER_SPAN_NAME_FALLBACK : phaseName,
       parentSpan: rootSpan,
       attributes: {
         [SEMANTIC_ATTRIBUTE_SENTRY_OP]: op,
@@ -130,11 +144,12 @@ function instrumentLifecyclePhase(phaseName: string, listener: TraceListener, ro
       void process.onEvent(child => {
         const handlerName = child.name || 'anonymous';
         const childSpan = startInactiveSpan({
-          name: handlerName,
+          name: isStreamedRequestHandlerSpan ? REQUEST_HANDLER_SPAN_NAME_FALLBACK : handlerName,
           parentSpan: phaseSpan,
           attributes: {
             [SEMANTIC_ATTRIBUTE_SENTRY_OP]: op,
             [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: ELYSIA_ORIGIN,
+            [CODE_FUNCTION_NAME]: handlerName,
           },
         });
 

packages/elysia/test/withElysia.test.ts

@@ -5,12 +5,16 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 // Capture handlers registered by withElysia
 let onAfterHandleHandler: (context: unknown) => void;
 let onErrorHandler: (context: unknown) => void;
+let traceHandler: (lifecycle: unknown) => void;
 
 function createMockApp() {
   const app: Record<string, unknown> = {};
   app.use = vi.fn().mockReturnValue(app);
   app.wrap = vi.fn().mockReturnValue(app);
-  app.trace = vi.fn().mockReturnValue(app);
+  app.trace = vi.fn((_opts: unknown, handler: (lifecycle: unknown) => void) => {
+    traceHandler = handler;
+    return app;
+  });
   app.onRequest = vi.fn(() => app);
   app.onAfterHandle = vi.fn((_opts: unknown, handler: (context: unknown) => void) => {
     onAfterHandleHandler = handler;
@@ -30,9 +34,16 @@ const mockGetIsolationScope = vi.fn(() => ({
   setSDKProcessingMetadata: vi.fn(),
   setTransactionName: vi.fn(),
 }));
+let traceLifecycle: 'static' | 'stream' = 'stream';
 const mockGetClient = vi.fn(() => ({
   on: vi.fn(),
+  getOptions: () => ({ traceLifecycle }),
 }));
+const startedSpans: { name: string; attributes?: Record<string, unknown> }[] = [];
+const mockStartInactiveSpan = vi.fn((options: { name: string; attributes?: Record<string, unknown> }) => {
+  startedSpans.push({ name: options.name, attributes: options.attributes });
+  return { end: vi.fn() };
+});
 const mockRootSpan = {
   setAttribute: vi.fn(),
   setAttributes: vi.fn(),
@@ -56,6 +67,8 @@ vi.mock('@sentry/core', async importActual => {
     getClient: () => mockGetClient(),
     getRootSpan: () => mockGetRootSpan(),
     getTraceData: () => mockGetTraceData(),
+    startInactiveSpan: (options: { name: string; attributes?: Record<string, unknown> }) =>
+      mockStartInactiveSpan(options),
   };
 });
 
@@ -65,6 +78,8 @@ const { withElysia } = await import('../src/withElysia');
 describe('withElysia', () => {
   beforeEach(() => {
     mockApp = createMockApp();
+    startedSpans.length = 0;
+    traceLifecycle = 'stream';
   });
 
   afterEach(() => {
@@ -185,6 +200,58 @@ describe('withElysia', () => {
     });
   });
 
+  describe('request handler span names', () => {
+    /** Drive the registered trace handler through a single `Handle` phase. */
+    function runHandlePhase(handlerNames: string[]): void {
+      traceHandler({
+        context: { request: new Request('http://localhost/test') },
+        onHandle: (callback: (process: unknown) => void) => {
+          callback({
+            total: handlerNames.length,
+            onEvent: (onChild: (child: unknown) => void) => {
+              for (const name of handlerNames) {
+                onChild({ name, onStop: () => {} });
+              }
+            },
+            onStop: () => {},
+          });
+        },
+      });
+    }
+
+    it('uses the low cardinality fallback when span streaming is enabled', () => {
+      // @ts-expect-error - mock app
+      withElysia(mockApp);
+      runHandlePhase(['getUser']);
+
+      expect(startedSpans.map(span => span.name)).toEqual(['Request handler', 'Request handler']);
+    });
+
+    it('keeps the phase and handler names in static mode', () => {
+      traceLifecycle = 'static';
+      // @ts-expect-error - mock app
+      withElysia(mockApp);
+      runHandlePhase(['getUser']);
+
+      expect(startedSpans.map(span => span.name)).toEqual(['Handle', 'getUser']);
+    });
+
+    it('records the handler name on the child span in both trace lifecycles', () => {
+      // @ts-expect-error - mock app
+      withElysia(mockApp);
+      runHandlePhase(['getUser']);
+
+      traceLifecycle = 'static';
+      // @ts-expect-error - mock app
+      withElysia(createMockApp());
+      runHandlePhase(['getUser']);
+
+      const childSpans = startedSpans.filter(span => span.attributes?.['code.function.name']);
+      expect(childSpans).toHaveLength(2);
+      expect(childSpans.every(span => span.attributes?.['code.function.name'] === 'getUser')).toBe(true);
+    });
+  });
+
   describe('custom shouldHandleError', () => {
     it('uses custom shouldHandleError when provided', () => {
       const customShouldHandle = vi.fn(() => false);

packages/nestjs/src/integrations/wrap-route.ts

@@ -1,7 +1,14 @@
 import { HTTP_METHOD, HTTP_ROUTE, SENTRY_OP, URL_FULL } from '@sentry/conventions/attributes';
 import { FUNCTION } from '@sentry/conventions/op';
 import type { SpanAttributes } from '@sentry/core';
-import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan, filterCollectedUrl } from '@sentry/core';
+import {
+  getClient,
+  hasSpanStreamingEnabled,
+  REQUEST_HANDLER_SPAN_NAME_FALLBACK,
+  SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+  startSpan,
+  filterCollectedUrl,
+} from '@sentry/core';
 import type { AnyFn } from './helpers';
 import { copyReflectMetadata, HTTP_ORIGIN, isWrapped, markWrapped } from './helpers';
 import { AttributeNames, NestType } from './enums';
@@ -62,7 +69,15 @@ export function wrapRouteHandler(callback: AnyFn, moduleVersion?: string): AnyFn
     [AttributeNames.VERSION]: moduleVersion || undefined,
   };
   const wrapped = function (this: unknown, ...args: unknown[]): unknown {
-    return startSpan({ name: spanName, attributes }, () => callback.apply(this, args));
+    const client = getClient();
+    // With span streaming, span names have to be low cardinality. NestJS resolves no
+    // route for the handler span, so it uses the static fallback. The callback name
+    // stays on the `nestjs.callback` attribute.
+    const isStreamedSpan = !!client && hasSpanStreamingEnabled(client);
+
+    return startSpan({ name: isStreamedSpan ? REQUEST_HANDLER_SPAN_NAME_FALLBACK : spanName, attributes }, () =>
+      callback.apply(this, args),
+    );
   };
   if (callback.name) {
     Object.defineProperty(wrapped, 'name', { value: callback.name });