feat(tanstackstart-react): Add distributed tracing

CHANGELOG.md

@@ -8,6 +8,10 @@
 
  Change the recommended setup for the SDK to do `Sentry.init()` in the client entry file to capture telemetry that is emitted ahead of page hydration.
 
+- **feat(tanstackstart-react): Add distributed tracing ([#21144](https://github.com/getsentry/sentry-javascript/pull/21144))**
+
+ Server and client traces are now automatically connected, allowing you to see the full request lifecycle from server-side rendering through client-side hydration in a single trace.
+
 ## 10.54.0
 
 ### Important Changes

dev-packages/e2e-tests/test-applications/tanstackstart-react-cloudflare/src/routes/__root.tsx

@@ -1,31 +1,21 @@
 import type { ReactNode } from 'react';
 import { Outlet, createRootRoute, HeadContent, Scripts } from '@tanstack/react-router';
-import { getTraceData } from '@sentry/tanstackstart-react';
 
 export const Route = createRootRoute({
- head: () => {
- const traceData = getTraceData();
- const sentryMeta = Object.entries(traceData).map(([key, value]) => ({
- name: key,
- content: value,
- }));
-
- return {
- meta: [
- {
- charSet: 'utf-8',
- },
- {
- name: 'viewport',
- content: 'width=device-width, initial-scale=1',
- },
- {
- title: 'TanStack Start Cloudflare E2E Test',
- },
- ...sentryMeta,
- ],
- };
- },
+ head: () => ({
+ meta: [
+ {
+ charSet: 'utf-8',
+ },
+ {
+ name: 'viewport',
+ content: 'width=device-width, initial-scale=1',
+ },
+ {
+ title: 'TanStack Start Cloudflare E2E Test',
+ },
+ ],
+ }),
  component: RootComponent,
 });
 

dev-packages/e2e-tests/test-applications/tanstackstart-react-cloudflare/tests/trace-propagation.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+
+test.describe('Trace propagation', () => {
+ test('should inject metatags in ssr pageload', async ({ page }) => {
+ await page.goto('/');
+
+ const sentryTraceContent = await page.getAttribute('meta[name="sentry-trace"]', 'content');
+ expect(sentryTraceContent).toBeDefined();
+ expect(sentryTraceContent).toMatch(/^[a-f0-9]{32}-[a-f0-9]{16}-[01]$/);
+
+ const baggageContent = await page.getAttribute('meta[name="baggage"]', 'content');
+ expect(baggageContent).toBeDefined();
+ expect(baggageContent).toContain('sentry-environment=qa');
+ expect(baggageContent).toContain('sentry-public_key=');
+ expect(baggageContent).toContain('sentry-trace_id=');
+ expect(baggageContent).toContain('sentry-sampled=');
+ });
+
+ test('should have trace connection between server and client', async ({ page }) => {
+ const serverTxPromise = waitForTransaction('tanstackstart-react-cloudflare', transactionEvent => {
+ return transactionEvent?.contexts?.trace?.op === 'http.server' && transactionEvent?.transaction === 'GET /';
+ });
+
+ const clientTxPromise = waitForTransaction('tanstackstart-react-cloudflare', transactionEvent => {
+ return transactionEvent?.contexts?.trace?.op === 'pageload' && transactionEvent?.transaction === '/';
+ });
+
+ await page.goto('/');
+
+ const serverTx = await serverTxPromise;
+ const clientTx = await clientTxPromise;
+
+ expect(clientTx.contexts?.trace?.trace_id).toBe(serverTx.contexts?.trace?.trace_id);
+ });
+});

dev-packages/e2e-tests/test-applications/tanstackstart-react-cloudflare/tests/transaction.test.ts

@@ -95,25 +95,3 @@ test('Sends server-side transaction for page request', async ({ baseURL }) => {
  status: 'ok',
  });
 });
-
-test('Propagates trace from server to client', async ({ page }) => {
- const serverTransactionPromise = waitForTransaction('tanstackstart-react-cloudflare', transactionEvent => {
- return transactionEvent?.contexts?.trace?.op === 'http.server' && transactionEvent?.transaction === 'GET /';
- });
-
- const clientTransactionPromise = waitForTransaction('tanstackstart-react-cloudflare', transactionEvent => {
- return transactionEvent?.contexts?.trace?.op === 'pageload' && transactionEvent?.transaction === '/';
- });
-
- await page.goto('/');
-
- const serverTransaction = await serverTransactionPromise;
- const clientTransaction = await clientTransactionPromise;
-
- const serverTraceId = serverTransaction.contexts?.trace?.trace_id;
- const clientTraceId = clientTransaction.contexts?.trace?.trace_id;
-
- expect(serverTraceId).toMatch(/[a-f0-9]{32}/);
- expect(clientTraceId).toMatch(/[a-f0-9]{32}/);
- expect(clientTraceId).toBe(serverTraceId);
-});

dev-packages/e2e-tests/test-applications/tanstackstart-react/tests/trace-propagation.test.ts

@@ -0,0 +1,41 @@
+import { expect, test } from '@playwright/test';
+import { waitForTransaction } from '@sentry-internal/test-utils';
+
+const usesManagedTunnelRoute =
+ (process.env.E2E_TEST_TUNNEL_ROUTE_MODE ?? 'off') !== 'off' || process.env.E2E_TEST_CUSTOM_TUNNEL_ROUTE === '1';
+
+test.skip(usesManagedTunnelRoute, 'Default e2e suites run only in the proxy variant');
+
+test.describe('Trace propagation', () => {
+ test('should inject metatags in ssr pageload', async ({ page }) => {
+ await page.goto('/');
+
+ const sentryTraceContent = await page.getAttribute('meta[name="sentry-trace"]', 'content');
+ expect(sentryTraceContent).toBeDefined();
+ expect(sentryTraceContent).toMatch(/^[a-f0-9]{32}-[a-f0-9]{16}-[01]$/);
+
+ const baggageContent = await page.getAttribute('meta[name="baggage"]', 'content');
+ expect(baggageContent).toBeDefined();
+ expect(baggageContent).toContain('sentry-environment=qa');
+ expect(baggageContent).toContain('sentry-public_key=');
+ expect(baggageContent).toContain('sentry-trace_id=');
+ expect(baggageContent).toContain('sentry-sampled=');
+ });
+
+ test('should have trace connection between server and client', async ({ page }) => {
+ const serverTxPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+ return transactionEvent?.contexts?.trace?.op === 'http.server' && transactionEvent?.transaction === 'GET /';
+ });
+
+ const clientTxPromise = waitForTransaction('tanstackstart-react', transactionEvent => {
+ return transactionEvent?.contexts?.trace?.op === 'pageload' && transactionEvent?.transaction === '/';
+ });
+
+ await page.goto('/');
+
+ const serverTx = await serverTxPromise;
+ const clientTx = await clientTxPromise;
+
+ expect(clientTx.contexts?.trace?.trace_id).toBe(serverTx.contexts?.trace?.trace_id);
+ });
+});

packages/tanstackstart-react/src/server/wrapFetchWithSentry.ts

@@ -1,11 +1,110 @@
-import { flushIfServerless } from '@sentry/core';
-import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/node';
+import { flushIfServerless, getTraceMetaTags } from '@sentry/core';
+import {
+ captureException,
+ SEMANTIC_ATTRIBUTE_SENTRY_OP,
+ SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+ startSpan,
+} from '@sentry/node';
 import { extractServerFunctionSha256 } from './utils';
 
 export type ServerEntry = {
  fetch: (request: Request, opts?: unknown) => Promise<Response> | Response;
 };
 
+/**
+ * This function optimistically assumes that the HTML coming in chunks will not be split
+ * within the <head> tag. If this still happens, we simply won't replace anything.
+ */
+function addMetaTagToHead(htmlChunk: string, metaTagsStr: string): string {
+ if (typeof htmlChunk !== 'string' || !metaTagsStr) {
+ return htmlChunk;
+ }
+
+ if (htmlChunk.includes('"sentry-trace"')) {
+ return htmlChunk;
+ }
+
+ // Skip quoted attribute values so we don't match <head> inside e.g. data-code="...<head>..."
+ let replaced = false;
+ return htmlChunk.replace(/"[^"]*"|'[^']*'|(<head>)/g, (match, headTag) => {
+ if (headTag && !replaced) {
+ replaced = true;
+ return `<head>${metaTagsStr}`;
+ }
+ return match;
+ });
+}
+
+function injectMetaTagsInResponse(originalResponse: Response): Response {
+ try {
+ const contentType = originalResponse.headers.get('content-type');
+
+ const isPageloadRequest = contentType?.startsWith('text/html');
+ if (!isPageloadRequest) {
+ return originalResponse;
+ }
+
+ // Type case necessary b/c the body's ReadableStream type doesn't include
+ // the async iterator that is actually available in Node
+ // We later on use the async iterator to read the body chunks
+ // see https://github.com/microsoft/TypeScript/issues/39051
+ const originalBody = originalResponse.body as NodeJS.ReadableStream | null;
+ if (!originalBody) {
+ return originalResponse;
+ }
+
+ const metaTagsStr = getTraceMetaTags();
+ const decoder = new TextDecoder();
+
+ const newResponseStream = new ReadableStream({
+ start: async controller => {
+ // Assign to a new variable to avoid TS losing the narrower type checked above.
+ const body = originalBody;
+
+ async function* bodyReporter(): AsyncGenerator<string | Buffer> {
+ try {
+ for await (const chunk of body) {
+ yield chunk;
+ }
+ } catch (e) {
+ captureException(e, {
+ mechanism: { type: 'auto.http.tanstackstart', handled: false },
+ });
+ throw e;
+ }
+ }
+
+ let errored = false;
+ try {
+ for await (const chunk of bodyReporter()) {
+ const html = typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+ const modifiedHtml = addMetaTagToHead(html, metaTagsStr);
+ controller.enqueue(new TextEncoder().encode(modifiedHtml));
+ }
+ } catch (e) {
+ errored = true;
+ controller.error(e);
+ } finally {
+ if (!errored) {
+ controller.close();
+ }
+ }
+ },
+ });
+
+ return new Response(newResponseStream, {
+ status: originalResponse.status,
+ statusText: originalResponse.statusText,
+ headers: new Headers(originalResponse.headers),
+ });
+ } catch (e) {
+ captureException(e, {
+ mechanism: { type: 'auto.http.tanstackstart', handled: false },
+ });
+ throw e;
+ }
+}
+
 /**
  * This function can be used to wrap the server entry request handler to add tracing to server-side functionality.
  * You must explicitly define a server entry point in your application for this to work. This is done by passing the request handler to the `createServerEntry` function.
@@ -62,7 +161,7 @@ export function wrapFetchWithSentry(serverEntry: ServerEntry): ServerEntry {
  );
  }
 
- return await target.apply(thisArg, args);
+ return injectMetaTagsInResponse(await target.apply(thisArg, args));
  } finally {
  await flushIfServerless();
  }