feat: route parameterization

Author: logaretm

dev-packages/e2e-tests/test-applications/nitro-3/tests/isolation.test.ts

@@ -3,7 +3,7 @@ import { waitForError, waitForTransaction } from '@sentry-internal/test-utils';
 
 test('Isolation scope prevents tag leaking between requests', async ({ request }) => {
   const transactionEventPromise = waitForTransaction('nitro-3', event => {
-    return event?.transaction === 'GET /api/test-isolation/1';
+    return event?.transaction === 'GET /api/test-isolation/:id';
   });
 
   const errorPromise = waitForError('nitro-3', event => {

dev-packages/e2e-tests/test-applications/nitro-3/tests/transactions.test.ts

@@ -44,9 +44,9 @@ test('Sets correct HTTP status code on transaction', async ({ request }) => {
   expect(transactionEvent.contexts?.trace?.status).toBe('ok');
 });
 
-test('Sends a transaction event for a parameterized route', async ({ request }) => {
+test('Uses parameterized route for transaction name', async ({ request }) => {
   const transactionEventPromise = waitForTransaction('nitro-3', transactionEvent => {
-    return transactionEvent?.transaction === 'GET /api/test-param/123';
+    return transactionEvent?.transaction === 'GET /api/test-param/:id';
   });
 
   await request.get('/api/test-param/123');
@@ -55,9 +55,17 @@ test('Sends a transaction event for a parameterized route', async ({ request })
 
   expect(transactionEvent).toEqual(
     expect.objectContaining({
+      transaction: 'GET /api/test-param/:id',
+      transaction_info: expect.objectContaining({ source: 'route' }),
       type: 'transaction',
     }),
   );
+
+  expect(transactionEvent.contexts?.trace?.data).toEqual(
+    expect.objectContaining({
+      'http.route': '/api/test-param/:id',
+    }),
+  );
 });
 
 test('Sets Server-Timing response headers for trace propagation', async ({ request }) => {

packages/nitro/src/runtime/hooks/captureTracingEvents.ts

@@ -3,15 +3,18 @@ import {
   getActiveSpan,
   getClient,
   getHttpSpanDetailsFromUrlObject,
+  getRootSpan,
   GLOBAL_OBJ,
   httpHeadersToSpanAttributes,
   parseStringToURLObject,
   SEMANTIC_ATTRIBUTE_SENTRY_OP,
   SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+  SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
   setHttpStatus,
   type Span,
   SPAN_STATUS_ERROR,
   startSpanManual,
+  updateSpanName,
 } from '@sentry/core';
 import type { TracingRequestEvent as H3TracingRequestEvent } from 'h3/tracing';
 import { tracingChannel } from 'otel-tracing-channel';
@@ -69,12 +72,37 @@ function onTraceError(data: { span?: Span; error: unknown }): void {
   data.span?.end();
 }
 
+/**
+ * Extracts the parameterized route pattern from the h3 event context.
+ */
+function getParameterizedRoute(event: H3TracingRequestEvent['event']): string | undefined {
+  const matchedRoute = event.context?.matchedRoute;
+  if (!matchedRoute) {
+    return undefined;
+  }
+
+  const routePath = matchedRoute.route;
+
+  // Skip catch-all routes as they're not useful for transaction grouping
+  if (!routePath || routePath === '/**') {
+    return undefined;
+  }
+
+  return routePath;
+}
+
 function setupH3TracingChannels(): void {
   const h3Channel = tracingChannel<H3TracingRequestEvent>('h3.request', data => {
     const parsedUrl = parseStringToURLObject(data.event.url.href);
-    const [spanName, urlAttributes] = getHttpSpanDetailsFromUrlObject(parsedUrl, 'server', 'auto.http.nitro.h3', {
-      method: data.event.req.method,
-    });
+    const routePattern = getParameterizedRoute(data.event);
+
+    const [spanName, urlAttributes] = getHttpSpanDetailsFromUrlObject(
+      parsedUrl,
+      'server',
+      'auto.http.nitro.h3',
+      { method: data.event.req.method },
+      routePattern,
+    );
 
     return startSpanManual(
       {
@@ -93,7 +121,30 @@ function setupH3TracingChannels(): void {
     start: NOOP,
     asyncStart: NOOP,
     end: NOOP,
-    asyncEnd: onTraceEnd,
+    asyncEnd: (data: H3TracingRequestEvent & { span?: Span; result?: unknown }) => {
+      onTraceEnd(data);
+
+      if (!data.span) {
+        return;
+      }
+
+      // Update the root span (srvx transaction) with the parameterized route name.
+      // The srvx span is created before h3 resolves the route, so it initially has the raw URL.
+      // Note: data.type is always 'middleware' in asyncEnd regardless of handler type,
+      // so we rely on getParameterizedRoute() to filter out catch-all routes instead.
+      const rootSpan = getRootSpan(data.span);
+      if (rootSpan && rootSpan !== data.span) {
+        const routePattern = getParameterizedRoute(data.event);
+        if (routePattern) {
+          const method = data.event.req.method || 'GET';
+          updateSpanName(rootSpan, `${method} ${routePattern}`);
+          rootSpan.setAttributes({
+            [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'route',
+            'http.route': routePattern,
+          });
+        }
+      }
+    },
     error: onTraceError,
   });
 }