feat: added server timing headers

Author: logaretm

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

@@ -59,3 +59,12 @@ test('Sends a transaction event for a parameterized route', async ({ request })
     }),
   );
 });
+
+test('Sets Server-Timing response headers for trace propagation', async ({ request }) => {
+  const response = await request.get('/test-transaction');
+  const headers = response.headers();
+
+  expect(headers['server-timing']).toBeDefined();
+  expect(headers['server-timing']).toContain('sentry-trace;desc="');
+  expect(headers['server-timing']).toContain('baggage;desc="');
+});

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

@@ -0,0 +1,183 @@
+import {
+  captureException,
+  getActiveSpan,
+  getClient,
+  getHttpSpanDetailsFromUrlObject,
+  GLOBAL_OBJ,
+  httpHeadersToSpanAttributes,
+  parseStringToURLObject,
+  SEMANTIC_ATTRIBUTE_SENTRY_OP,
+  setHttpStatus,
+  type Span,
+  SPAN_STATUS_ERROR,
+  startSpanManual,
+} from '@sentry/core';
+import type { TracingRequestEvent as H3TracingRequestEvent } from 'h3/tracing';
+import { tracingChannel } from 'otel-tracing-channel';
+import type { RequestEvent as SrvxRequestEvent } from 'srvx/tracing';
+
+/**
+ * Global object with the trace channels
+ */
+const globalWithTraceChannels = GLOBAL_OBJ as typeof GLOBAL_OBJ & {
+  __SENTRY_NITRO_HTTP_CHANNELS_INSTRUMENTED__: boolean;
+};
+
+/**
+ * Captures tracing events emitted by Nitro tracing channels.
+ */
+export function captureTracingEvents(): void {
+  if (globalWithTraceChannels.__SENTRY_NITRO_HTTP_CHANNELS_INSTRUMENTED__) {
+    return;
+  }
+
+  setupH3TracingChannels();
+  setupSrvxTracingChannels();
+  globalWithTraceChannels.__SENTRY_NITRO_HTTP_CHANNELS_INSTRUMENTED__ = true;
+}
+
+/**
+ * No-op function to satisfy the tracing channel subscribe callbacks
+ */
+const NOOP = (): void => {};
+
+/**
+ * Extracts the HTTP status code from a tracing channel result.
+ * The result is the return value of the traced handler, which is a Response for srvx
+ * and may or may not be a Response for h3.
+ */
+function getResponseStatusCode(result: unknown): number | undefined {
+  if (result && typeof result === 'object' && 'status' in result && typeof result.status === 'number') {
+    return result.status;
+  }
+  return undefined;
+}
+
+function onTraceEnd(data: { span?: Span; result?: unknown }): void {
+  const statusCode = getResponseStatusCode(data.result);
+  if (data.span && statusCode !== undefined) {
+    setHttpStatus(data.span, statusCode);
+    data.span.end();
+  }
+}
+
+function onTraceError(data: { span?: Span; error: unknown }): void {
+  captureException(data.error);
+  data.span?.setStatus({ code: SPAN_STATUS_ERROR, message: 'internal_error' });
+  data.span?.end();
+}
+
+function setupH3TracingChannels(): void {
+  const h3Channel = tracingChannel<H3TracingRequestEvent>('h3.fetch', data => {
+    const parsedUrl = parseStringToURLObject(data.event.url.href);
+    const [spanName, urlAttributes] = getHttpSpanDetailsFromUrlObject(parsedUrl, 'server', 'auto.http.nitro.h3', {
+      method: data.event.req.method,
+    });
+
+    return startSpanManual(
+      {
+        name: spanName,
+        attributes: {
+          ...urlAttributes,
+          [SEMANTIC_ATTRIBUTE_SENTRY_OP]: data?.type === 'middleware' ? 'middleware.nitro' : 'http.server',
+        },
+      },
+      s => s,
+    );
+  });
+
+  h3Channel.subscribe({
+    start: NOOP,
+    asyncStart: NOOP,
+    end: NOOP,
+    asyncEnd: onTraceEnd,
+    error: onTraceError,
+  });
+}
+
+function setupSrvxTracingChannels(): void {
+  // Store the parent span for all middleware and fetch to share
+  // This ensures they all appear as siblings in the trace
+  let requestParentSpan: Span | null = null;
+
+  const fetchChannel = tracingChannel<SrvxRequestEvent>('srvx.fetch', data => {
+    const parsedUrl = data.request._url ? parseStringToURLObject(data.request._url.href) : undefined;
+    const [spanName, urlAttributes] = getHttpSpanDetailsFromUrlObject(parsedUrl, 'server', 'auto.http.nitro.srvx', {
+      method: data.request.method,
+    });
+
+    const sendDefaultPii = getClient()?.getOptions().sendDefaultPii ?? false;
+    const headerAttributes = httpHeadersToSpanAttributes(
+      Object.fromEntries(data.request.headers.entries()),
+      sendDefaultPii,
+    );
+
+    return startSpanManual(
+      {
+        name: spanName,
+        attributes: {
+          ...urlAttributes,
+          ...headerAttributes,
+          [SEMANTIC_ATTRIBUTE_SENTRY_OP]: data.middleware ? 'middleware.nitro' : 'http.server',
+          'server.port': data.server.options.port,
+        },
+        // Use the same parent span as middleware to make them siblings
+        parentSpan: requestParentSpan || undefined,
+      },
+      span => span,
+    );
+  });
+
+  // Subscribe to events (span already created in bindStore)
+  fetchChannel.subscribe({
+    start: () => {},
+    asyncStart: () => {},
+    end: () => {},
+    asyncEnd: data => {
+      onTraceEnd(data);
+
+      // Reset parent span reference after the fetch handler completes
+      // This ensures each request gets a fresh parent span capture
+      requestParentSpan = null;
+    },
+    error: data => {
+      onTraceError(data);
+      // Reset parent span reference on error too
+      requestParentSpan = null;
+    },
+  });
+
+  const middlewareChannel = tracingChannel<SrvxRequestEvent>('srvx.middleware', data => {
+    // For the first middleware, capture the current parent span
+    if (data.middleware?.index === 0) {
+      requestParentSpan = getActiveSpan() || null;
+    }
+
+    const parsedUrl = data.request._url ? parseStringToURLObject(data.request._url.href) : undefined;
+    const [, urlAttributes] = getHttpSpanDetailsFromUrlObject(parsedUrl, 'server', 'auto.http.nitro.srvx.middleware', {
+      method: data.request.method,
+    });
+
+    // Create span as a child of the original parent, not the previous middleware
+    return startSpanManual(
+      {
+        name: `${data.middleware?.handler.name ?? 'unknown'} - ${data.request.method} ${data.request._url?.pathname}`,
+        attributes: {
+          ...urlAttributes,
+          [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'middleware.nitro',
+        },
+        parentSpan: requestParentSpan || undefined,
+      },
+      span => span,
+    );
+  });
+
+  // Subscribe to events (span already created in bindStore)
+  middlewareChannel.subscribe({
+    start: () => {},
+    asyncStart: () => {},
+    end: () => {},
+    asyncEnd: onTraceEnd,
+    error: onTraceError,
+  });
+}

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

@@ -0,0 +1,19 @@
+import { getTraceData } from '@sentry/core';
+
+/**
+ * Sets Server-Timing response headers for trace propagation to the client.
+ * The browser SDK reads these via the Performance API to connect pageload traces.
+ */
+export function setServerTimingHeaders(response: unknown, _event: unknown): void {
+  if (response && typeof response === 'object' && 'headers' in response) {
+    const responseObj = response as Response;
+    const traceData = getTraceData();
+
+    if (traceData['sentry-trace']) {
+      responseObj.headers.append('Server-Timing', `sentry-trace;desc="${traceData['sentry-trace']}"`);
+    }
+    if (traceData.baggage) {
+      responseObj.headers.append('Server-Timing', `baggage;desc="${traceData.baggage}"`);
+    }
+  }
+}