feat(browser): Add previous_trace span links

Lms24 · Lms24 · commit 66ec822600b6 · 2025-03-04T14:15:53.000+01:00
diff --git a/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/default/test.ts b/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/default/test.ts
@@ -0,0 +1,80 @@
+import { expect } from '@playwright/test';
+import { SEMANTIC_LINK_ATTRIBUTE_LINK_TYPE, type Event } from '@sentry/core';
+
+import { sentryTest } from '../../../../../utils/fixtures';
+import {
+  envelopeRequestParser,
+  getFirstSentryEnvelopeRequest,
+  shouldSkipTracingTest,
+  waitForTransactionRequest,
+} from '../../../../../utils/helpers';
+
+sentryTest("navigation spans link back to previous trace's root span", async ({ getLocalTestUrl, page }) => {
+  if (shouldSkipTracingTest()) {
+    sentryTest.skip();
+  }
+
+  const url = await getLocalTestUrl({ testDir: __dirname });
+
+  const pageloadRequest = await getFirstSentryEnvelopeRequest<Event>(page, url);
+  const navigationRequest = await getFirstSentryEnvelopeRequest<Event>(page, `${url}#foo`);
+  const navigation2Request = await getFirstSentryEnvelopeRequest<Event>(page, `${url}#bar`);
+
+  const pageloadTraceContext = pageloadRequest.contexts?.trace;
+  const navigationTraceContext = navigationRequest.contexts?.trace;
+  const navigation2TraceContext = navigation2Request.contexts?.trace;
+
+  const pageloadTraceId = pageloadTraceContext?.trace_id;
+  const navigationTraceId = navigationTraceContext?.trace_id;
+  const navigation2TraceId = navigation2TraceContext?.trace_id;
+
+  expect(pageloadTraceContext?.op).toBe('pageload');
+  expect(navigationTraceContext?.op).toBe('navigation');
+  expect(navigation2TraceContext?.op).toBe('navigation');
+
+  expect(pageloadTraceContext?.links).toBeUndefined();
+  expect(navigationTraceContext?.links).toEqual([
+    {
+      trace_id: pageloadTraceId,
+      span_id: pageloadTraceContext?.span_id,
+      sampled: true,
+      attributes: {
+        [SEMANTIC_LINK_ATTRIBUTE_LINK_TYPE]: 'previous_trace',
+      },
+    },
+  ]);
+
+  expect(navigation2TraceContext?.links).toEqual([
+    {
+      trace_id: navigationTraceId,
+      span_id: navigationTraceContext?.span_id,
+      sampled: true,
+      attributes: {
+        [SEMANTIC_LINK_ATTRIBUTE_LINK_TYPE]: 'previous_trace',
+      },
+    },
+  ]);
+
+  expect(pageloadTraceId).not.toEqual(navigationTraceId);
+  expect(navigationTraceId).not.toEqual(navigation2TraceId);
+  expect(pageloadTraceId).not.toEqual(navigation2TraceId);
+});
+
+sentryTest("doesn't link between hard page reloads by default", async ({ getLocalTestUrl, page }) => {
+  if (shouldSkipTracingTest()) {
+    sentryTest.skip();
+  }
+
+  const url = await getLocalTestUrl({ testDir: __dirname });
+
+  const pageload1Event = await getFirstSentryEnvelopeRequest<Event>(page, url);
+
+  const pageload2RequestPromise = waitForTransactionRequest(page, evt => evt.contexts?.trace?.op === 'pageload');
+  await page.reload();
+  const pageload2Event = envelopeRequestParser(await pageload2RequestPromise);
+
+  expect(pageload1Event.contexts?.trace).toBeDefined();
+  expect(pageload2Event.contexts?.trace).toBeDefined();
+  expect(pageload1Event.contexts?.trace?.links).toBeUndefined();
+  expect(pageload2Event.contexts?.trace?.links).toBeUndefined();
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/init.js b/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/init.js
@@ -0,0 +1,9 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  integrations: [Sentry.browserTracingIntegration()],
+  tracesSampleRate: 1,
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/meta/template.html b/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/meta/template.html
@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="sentry-trace" content="12345678901234567890123456789012-1234567890123456-1" />
+    <meta name="baggage"
+          content="sentry-trace_id=12345678901234567890123456789012,sentry-sample_rate=0.2,sentry-sampled=true,sentry-transaction=my-transaction,sentry-public_key=public,sentry-release=1.0.0,sentry-environment=prod,sentry-sample_rand=0.42"/>
+  </head>
+</html>
diff --git a/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/meta/test.ts b/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/meta/test.ts
@@ -0,0 +1,46 @@
+import { expect } from '@playwright/test';
+import { SEMANTIC_LINK_ATTRIBUTE_LINK_TYPE, type Event } from '@sentry/core';
+
+import { sentryTest } from '../../../../../utils/fixtures';
+import { getFirstSentryEnvelopeRequest, shouldSkipTracingTest } from '../../../../../utils/helpers';
+
+sentryTest(
+  "links back to previous trace's local root span if continued from meta tags",
+  async ({ getLocalTestUrl, page }) => {
+    if (shouldSkipTracingTest()) {
+      sentryTest.skip();
+    }
+
+    const url = await getLocalTestUrl({ testDir: __dirname });
+
+    const pageloadRequest = await getFirstSentryEnvelopeRequest<Event>(page, url);
+    const navigationRequest = await getFirstSentryEnvelopeRequest<Event>(page, `${url}#foo`);
+
+    const pageloadTraceContext = pageloadRequest.contexts?.trace;
+    const navigationTraceContext = navigationRequest.contexts?.trace;
+
+    const metaTagTraceId = '12345678901234567890123456789012';
+
+    const navigationTraceId = navigationTraceContext?.trace_id;
+
+    expect(pageloadTraceContext?.op).toBe('pageload');
+    expect(navigationTraceContext?.op).toBe('navigation');
+
+    // sanity check
+    expect(pageloadTraceContext?.trace_id).toBe(metaTagTraceId);
+    expect(pageloadTraceContext?.links).toBeUndefined();
+
+    expect(navigationTraceContext?.links).toEqual([
+      {
+        trace_id: metaTagTraceId,
+        span_id: pageloadTraceContext?.span_id,
+        sampled: true,
+        attributes: {
+          [SEMANTIC_LINK_ATTRIBUTE_LINK_TYPE]: 'previous_trace',
+        },
+      },
+    ]);
+
+    expect(navigationTraceId).not.toEqual(metaTagTraceId);
+  },
+);
diff --git a/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/negatively-sampled/init.js b/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/negatively-sampled/init.js
@@ -0,0 +1,14 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  integrations: [Sentry.browserTracingIntegration()],
+  tracesSampler: (ctx) => {
+    if (ctx.attributes['sentry.origin'] === 'auto.pageload.browser') {
+      return 0;
+    }
+    return 1;
+  }
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/negatively-sampled/test.ts b/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/negatively-sampled/test.ts
@@ -0,0 +1,36 @@
+import { expect } from '@playwright/test';
+import { SEMANTIC_LINK_ATTRIBUTE_LINK_TYPE, type Event } from '@sentry/core';
+
+import { sentryTest } from '../../../../../utils/fixtures';
+import { getFirstSentryEnvelopeRequest, shouldSkipTracingTest } from '../../../../../utils/helpers';
+
+sentryTest('includes a span link to a previously negatively sampled span', async ({ getLocalTestUrl, page }) => {
+  if (shouldSkipTracingTest()) {
+    sentryTest.skip();
+  }
+
+  const url = await getLocalTestUrl({ testDir: __dirname });
+
+  await page.goto(url);
+
+  const navigationRequest = await getFirstSentryEnvelopeRequest<Event>(page, `${url}#foo`);
+
+  const navigationTraceContext = navigationRequest.contexts?.trace;
+
+  const navigationTraceId = navigationTraceContext?.trace_id;
+
+  expect(navigationTraceContext?.op).toBe('navigation');
+
+  expect(navigationTraceContext?.links).toEqual([
+    {
+      trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+      span_id: expect.stringMatching(/[a-f0-9]{16}/),
+      sampled: false,
+      attributes: {
+        [SEMANTIC_LINK_ATTRIBUTE_LINK_TYPE]: 'previous_trace',
+      },
+    },
+  ]);
+
+  expect(navigationTraceId).not.toEqual(navigationTraceContext?.links![0].trace_id);
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/session-storage/init.js b/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/session-storage/init.js
@@ -0,0 +1,9 @@
+import * as Sentry from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  integrations: [Sentry.browserTracingIntegration({persistPreviousTrace: true})],
+  tracesSampleRate: 1,
+});
diff --git a/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/session-storage/test.ts b/dev-packages/browser-integration-tests/suites/tracing/browserTracingIntegration/previous-trace-links/session-storage/test.ts
@@ -0,0 +1,42 @@
+import { expect } from '@playwright/test';
+import { SEMANTIC_LINK_ATTRIBUTE_LINK_TYPE, type Event } from '@sentry/core';
+
+import { sentryTest } from '../../../../../utils/fixtures';
+import {
+  envelopeRequestParser,
+  getFirstSentryEnvelopeRequest,
+  shouldSkipTracingTest,
+  waitForTransactionRequest,
+} from '../../../../../utils/helpers';
+
+sentryTest(
+  'adds link between hard page reload traces when opting into sessionStorage',
+  async ({ getLocalTestUrl, page }) => {
+    if (shouldSkipTracingTest()) {
+      sentryTest.skip();
+    }
+
+    const url = await getLocalTestUrl({ testDir: __dirname });
+
+    const pageload1Event = await getFirstSentryEnvelopeRequest<Event>(page, url);
+
+    const pageload2RequestPromise = waitForTransactionRequest(page, evt => evt.contexts?.trace?.op === 'pageload');
+    await page.reload();
+    const pageload2Event = envelopeRequestParser(await pageload2RequestPromise);
+
+    const pageload1TraceContext = pageload1Event.contexts?.trace;
+    expect(pageload1TraceContext).toBeDefined();
+    expect(pageload1TraceContext?.links).toBeUndefined();
+
+    expect(pageload2Event.contexts?.trace?.links).toEqual([
+      {
+        trace_id: pageload1TraceContext?.trace_id,
+        span_id: pageload1TraceContext?.span_id,
+        sampled: true,
+        attributes: { [SEMANTIC_LINK_ATTRIBUTE_LINK_TYPE]: 'previous_trace' },
+      },
+    ]);
+
+    expect(pageload1TraceContext?.trace_id).not.toEqual(pageload2Event.contexts?.trace?.trace_id);
+  },
+);
diff --git a/packages/browser/src/tracing/browserTracingIntegration.ts b/packages/browser/src/tracing/browserTracingIntegration.ts
@@ -35,6 +35,12 @@ import { DEBUG_BUILD } from '../debug-build';
 import { WINDOW } from '../helpers';
 import { registerBackgroundTabDetection } from './backgroundtab';
 import { defaultRequestInstrumentationOptions, instrumentOutgoingRequests } from './request';
+import type { PreviousTraceInfo } from './previousTrace';
+import {
+  addPreviousTraceSpanLink,
+  getPreviousTraceFromSessionStorage,
+  storePreviousTraceInSessionStorage,
+} from './previousTrace';
 
 export const BROWSER_TRACING_INTEGRATION_ID = 'BrowserTracing';
 
@@ -142,6 +148,25 @@ export interface BrowserTracingOptions {
    */
   enableHTTPTimings: boolean;
 
+  /**
+   * If enabled, previously started traces (e.g. pageload or navigation spans) will be linked
+   * to the current trace. This lets you navigate across traces within a user journey in the
+   * Sentry UI.
+   *
+   * Set `persistPreviousTrace` to `true` to connect traces across hard page reloads.
+   *
+   * @default true, this is turned on by default.
+   */
+  enablePreviousTrace?: boolean;
+
+  /**
+   * If set to true, the previous trace will be stored in `sessionStorage`, so that
+   * traces can be linked across hard page refreshes.
+   *
+   * @default false, by default, previous trace data is only stored in-memory.
+   */
+  persistPreviousTrace?: boolean;
+
   /**
    * _experiments allows the user to send options to define how this integration works.
    *
@@ -175,6 +200,8 @@ const DEFAULT_BROWSER_TRACING_OPTIONS: BrowserTracingOptions = {
   enableLongTask: true,
   enableLongAnimationFrame: true,
   enableInp: true,
+  enablePreviousTrace: true,
+  persistPreviousTrace: false,
   _experiments: {},
   ...defaultRequestInstrumentationOptions,
 };
@@ -214,6 +241,8 @@ export const browserTracingIntegration = ((_options: Partial<BrowserTracingOptio
     enableHTTPTimings,
     instrumentPageLoad,
     instrumentNavigation,
+    enablePreviousTrace,
+    persistPreviousTrace,
   } = {
     ...DEFAULT_BROWSER_TRACING_OPTIONS,
     ..._options,
@@ -245,10 +274,19 @@ export const browserTracingIntegration = ((_options: Partial<BrowserTracingOptio
     source: undefined,
   };
 
+  let previousTraceInfo: PreviousTraceInfo | undefined;
+  if (enablePreviousTrace && persistPreviousTrace) {
+    previousTraceInfo = getPreviousTraceFromSessionStorage();
+  }
+
   /** Create routing idle transaction. */
   function _createRouteSpan(client: Client, startSpanOptions: StartSpanOptions): void {
     const isPageloadTransaction = startSpanOptions.op === 'pageload';
 
+    if (enablePreviousTrace && previousTraceInfo) {
+      previousTraceInfo = addPreviousTraceSpanLink(previousTraceInfo, startSpanOptions);
+    }
+
     const finalStartSpanOptions: StartSpanOptions = beforeStartSpan
       ? beforeStartSpan(startSpanOptions)
       : startSpanOptions;
@@ -292,6 +330,16 @@ export const browserTracingIntegration = ((_options: Partial<BrowserTracingOptio
     });
     setActiveIdleSpan(client, idleSpan);
 
+    if (enablePreviousTrace) {
+      previousTraceInfo = {
+        spanContext: idleSpan.spanContext(),
+        startTimestamp: spanToJSON(idleSpan).start_timestamp,
+      };
+      if (persistPreviousTrace) {
+        storePreviousTraceInSessionStorage(previousTraceInfo);
+      }
+    }
+
     function emitFinish(): void {
       if (optionalWindowDocument && ['interactive', 'complete'].includes(optionalWindowDocument.readyState)) {
         client.emit('idleSpanEnableAutoFinish', idleSpan);
diff --git a/packages/browser/src/tracing/previousTrace.ts b/packages/browser/src/tracing/previousTrace.ts
diff --git a/packages/browser/test/tracing/browserTracingIntegration.test.ts b/packages/browser/test/tracing/browserTracingIntegration.test.ts
diff --git a/packages/browser/test/tracing/previousTrace.test.ts b/packages/browser/test/tracing/previousTrace.test.ts
diff --git a/packages/core/src/semanticAttributes.ts b/packages/core/src/semanticAttributes.ts
