feat(browserProfiling): Add trace lifecycle mode for UI profiling (#17619)

Adds the `trace` lifecycle mode and sends `profile_chunk` envelopes.
Also adds test for either overlapping root spans (one chunk) or single
root spans (multiple chunks).



The "manual" mode comes in another PR to keep this from growing too
large.


 **Browser trace-lifecycle profiler (v2):**
  - Starts when the first sampled root span starts
  - Stops when the last sampled root span ends
- While running, periodically stops and restarts the JS self-profiling
API to collect chunks
 
**Profiles are emitted as standalone `profile_chunk` envelopes either
when:**
  - there are no more sampled root spans, or
  - the 60s chunk timer elapses while profiling is running.
  
  **Handling never-ending root spans**
In the trace lifecycle, profiling continues as long as a root span is
active. To prevent profiling endlessly, each root span has its own
profile timeout and is terminated if it is too long (5 minutes). If
another root span is still active, profiling will continue regardless.
 

part of #17279

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds UI profiling trace lifecycle mode that samples sessions, streams
profile_chunk envelopes, and attaches thread data, with accompanying
tests and type options.
> 
> - **Browser Profiling (UI Profiling v2)**:
> - Add `profileLifecycle: 'trace'` with session sampling via
`profileSessionSampleRate`; defaults lifecycle to `manual` when
unspecified.
> - Stream profiling as `profile_chunk` envelopes; periodic chunking
(60s) and 5‑min root-span timeout.
> - New `BrowserTraceLifecycleProfiler` manages start/stop across root
spans and chunk sending.
> - Attach profiled thread data to events/spans; warn if trace mode
without tracing.
> - **Profiling Utils**:
> - Convert JS self profile to continuous format; validate chunks;
main/worker thread constants; helper to attach thread info.
> - Split legacy logic: `hasLegacyProfiling`, `shouldProfileSpanLegacy`,
`shouldProfileSession`.
> - **Integration Changes**:
> - Browser integration branches between legacy and trace lifecycle;
adds `processEvent` to attach thread data.
>   - Minor fix in `startProfileForSpan` (processed profile handling).
> - **Tests**:
> - Add Playwright suites for trace lifecycle (multiple chunks,
overlapping spans) and adjust legacy tests.
> - Add unit tests for lifecycle behavior, warnings, profiler_id reuse,
and option defaults.
> - **Types/Config**:
> - Extend `BrowserClientProfilingOptions` with
`profileSessionSampleRate` and `profileLifecycle`; refine Node types
docs.
> - Size-limit: add entry for `@sentry/browser` incl. Tracing, Profiling
(48 KB).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
765f89d. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: s1gr1d

.size-limit.js

@@ -40,6 +40,13 @@ module.exports = [
     gzip: true,
     limit: '41 KB',
   },
+  {
+    name: '@sentry/browser (incl. Tracing, Profiling)',
+    path: 'packages/browser/build/npm/esm/index.js',
+    import: createImport('init', 'browserTracingIntegration', 'browserProfilingIntegration'),
+    gzip: true,
+    limit: '48 KB',
+  },
   {
     name: '@sentry/browser (incl. Tracing, Replay)',
     path: 'packages/browser/build/npm/esm/index.js',

dev-packages/browser-integration-tests/suites/profiling/legacyMode/subject.js

@@ -17,7 +17,7 @@ function fibonacci(n) {
   return fibonacci(n - 1) + fibonacci(n - 2);
 }
 
-await Sentry.startSpanManual({ name: 'root-fibonacci-2', parentSpan: null, forceTransaction: true }, async span => {
+await Sentry.startSpanManual({ name: 'root-fibonacci', parentSpan: null, forceTransaction: true }, async span => {
   fibonacci(30);
 
   // Timeout to prevent flaky tests. Integration samples every 20ms, if function is too fast it might not get sampled

dev-packages/browser-integration-tests/suites/profiling/legacyMode/test.ts

@@ -73,14 +73,16 @@ sentryTest('sends profile envelope in legacy mode', async ({ page, getLocalTestU
   expect(profile.frames.length).toBeGreaterThan(0);
   for (const frame of profile.frames) {
     expect(frame).toHaveProperty('function');
-    expect(frame).toHaveProperty('abs_path');
-    expect(frame).toHaveProperty('lineno');
-    expect(frame).toHaveProperty('colno');
-
     expect(typeof frame.function).toBe('string');
-    expect(typeof frame.abs_path).toBe('string');
-    expect(typeof frame.lineno).toBe('number');
-    expect(typeof frame.colno).toBe('number');
+
+    if (frame.function !== 'fetch' && frame.function !== 'setTimeout') {
+      expect(frame).toHaveProperty('abs_path');
+      expect(frame).toHaveProperty('lineno');
+      expect(frame).toHaveProperty('colno');
+      expect(typeof frame.abs_path).toBe('string');
+      expect(typeof frame.lineno).toBe('number');
+      expect(typeof frame.colno).toBe('number');
+    }
   }
 
   const functionNames = profile.frames.map(frame => frame.function).filter(name => name !== '');

dev-packages/browser-integration-tests/suites/profiling/traceLifecycleMode_multiple-chunks/subject.js

@@ -0,0 +1,48 @@
+import * as Sentry from '@sentry/browser';
+import { browserProfilingIntegration } from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://[email protected]/1337',
+  integrations: [browserProfilingIntegration()],
+  tracesSampleRate: 1,
+  profileSessionSampleRate: 1,
+  profileLifecycle: 'trace',
+});
+
+function largeSum(amount = 1000000) {
+  let sum = 0;
+  for (let i = 0; i < amount; i++) {
+    sum += Math.sqrt(i) * Math.sin(i);
+  }
+}
+
+function fibonacci(n) {
+  if (n <= 1) {
+    return n;
+  }
+  return fibonacci(n - 1) + fibonacci(n - 2);
+}
+
+// Create two NON-overlapping root spans so that the profiler stops and emits a chunk
+// after each span (since active root span count returns to 0 between them).
+await Sentry.startSpanManual({ name: 'root-fibonacci-1', parentSpan: null, forceTransaction: true }, async span => {
+  fibonacci(40);
+  // Ensure we cross the sampling interval to avoid flakes
+  await new Promise(resolve => setTimeout(resolve, 25));
+  span.end();
+});
+
+// Small delay to ensure the first chunk is collected and sent
+await new Promise(r => setTimeout(r, 25));
+
+await Sentry.startSpanManual({ name: 'root-largeSum-2', parentSpan: null, forceTransaction: true }, async span => {
+  largeSum();
+  // Ensure we cross the sampling interval to avoid flakes
+  await new Promise(resolve => setTimeout(resolve, 25));
+  span.end();
+});
+
+const client = Sentry.getClient();
+await client?.flush(5000);

dev-packages/browser-integration-tests/suites/profiling/traceLifecycleMode_multiple-chunks/test.ts

@@ -0,0 +1,206 @@
+import { expect } from '@playwright/test';
+import type { ProfileChunkEnvelope } from '@sentry/core';
+import { sentryTest } from '../../../utils/fixtures';
+import {
+  countEnvelopes,
+  getMultipleSentryEnvelopeRequests,
+  properFullEnvelopeRequestParser,
+  shouldSkipTracingTest,
+} from '../../../utils/helpers';
+
+sentryTest(
+  'does not send profile envelope when document-policy is not set',
+  async ({ page, getLocalTestUrl, browserName }) => {
+    if (shouldSkipTracingTest() || browserName !== 'chromium') {
+      // Profiling only works when tracing is enabled
+      sentryTest.skip();
+    }
+
+    const url = await getLocalTestUrl({ testDir: __dirname });
+
+    // Assert that no profile_chunk envelope is sent without policy header
+    const chunkCount = await countEnvelopes(page, { url, envelopeType: 'profile_chunk', timeout: 1500 });
+    expect(chunkCount).toBe(0);
+  },
+);
+
+sentryTest(
+  'sends profile_chunk envelopes in trace mode (multiple chunks)',
+  async ({ page, getLocalTestUrl, browserName }) => {
+    if (shouldSkipTracingTest() || browserName !== 'chromium') {
+      // Profiling only works when tracing is enabled
+      sentryTest.skip();
+    }
+
+    const url = await getLocalTestUrl({ testDir: __dirname, responseHeaders: { 'Document-Policy': 'js-profiling' } });
+
+    // Expect at least 2 chunks because subject creates two separate root spans,
+    // causing the profiler to stop and emit a chunk after each root span ends.
+    const profileChunkEnvelopes = await getMultipleSentryEnvelopeRequests<ProfileChunkEnvelope>(
+      page,
+      2,
+      { url, envelopeType: 'profile_chunk', timeout: 5000 },
+      properFullEnvelopeRequestParser,
+    );
+
+    expect(profileChunkEnvelopes.length).toBeGreaterThanOrEqual(2);
+
+    // Validate the first chunk thoroughly
+    const profileChunkEnvelopeItem = profileChunkEnvelopes[0][1][0];
+    const envelopeItemHeader = profileChunkEnvelopeItem[0];
+    const envelopeItemPayload1 = profileChunkEnvelopeItem[1];
+
+    expect(envelopeItemHeader).toHaveProperty('type', 'profile_chunk');
+
+    expect(envelopeItemPayload1.profile).toBeDefined();
+    expect(envelopeItemPayload1.version).toBe('2');
+    expect(envelopeItemPayload1.platform).toBe('javascript');
+
+    // Required profile metadata (Sample Format V2)
+    expect(typeof envelopeItemPayload1.profiler_id).toBe('string');
+    expect(envelopeItemPayload1.profiler_id).toMatch(/^[a-f0-9]{32}$/);
+    expect(typeof envelopeItemPayload1.chunk_id).toBe('string');
+    expect(envelopeItemPayload1.chunk_id).toMatch(/^[a-f0-9]{32}$/);
+    expect(envelopeItemPayload1.client_sdk).toBeDefined();
+    expect(typeof envelopeItemPayload1.client_sdk.name).toBe('string');
+    expect(typeof envelopeItemPayload1.client_sdk.version).toBe('string');
+    expect(typeof envelopeItemPayload1.release).toBe('string');
+    expect(envelopeItemPayload1.debug_meta).toBeDefined();
+    expect(Array.isArray(envelopeItemPayload1?.debug_meta?.images)).toBe(true);
+
+    const profile1 = envelopeItemPayload1.profile;
+
+    expect(profile1.samples).toBeDefined();
+    expect(profile1.stacks).toBeDefined();
+    expect(profile1.frames).toBeDefined();
+    expect(profile1.thread_metadata).toBeDefined();
+
+    // Samples
+    expect(profile1.samples.length).toBeGreaterThanOrEqual(2);
+    let previousTimestamp = Number.NEGATIVE_INFINITY;
+    for (const sample of profile1.samples) {
+      expect(typeof sample.stack_id).toBe('number');
+      expect(sample.stack_id).toBeGreaterThanOrEqual(0);
+      expect(sample.stack_id).toBeLessThan(profile1.stacks.length);
+
+      // In trace lifecycle mode, samples carry a numeric timestamp (ms since epoch or similar clock)
+      expect(typeof (sample as any).timestamp).toBe('number');
+      const ts = (sample as any).timestamp as number;
+      expect(Number.isFinite(ts)).toBe(true);
+      expect(ts).toBeGreaterThan(0);
+      // Monotonic non-decreasing timestamps
+      expect(ts).toBeGreaterThanOrEqual(previousTimestamp);
+      previousTimestamp = ts;
+
+      expect(sample.thread_id).toBe('0'); // Should be main thread
+    }
+
+    // Stacks
+    expect(profile1.stacks.length).toBeGreaterThan(0);
+    for (const stack of profile1.stacks) {
+      expect(Array.isArray(stack)).toBe(true);
+      for (const frameIndex of stack) {
+        expect(typeof frameIndex).toBe('number');
+        expect(frameIndex).toBeGreaterThanOrEqual(0);
+        expect(frameIndex).toBeLessThan(profile1.frames.length);
+      }
+    }
+
+    // Frames
+    expect(profile1.frames.length).toBeGreaterThan(0);
+    for (const frame of profile1.frames) {
+      expect(frame).toHaveProperty('function');
+      expect(typeof frame.function).toBe('string');
+
+      if (frame.function !== 'fetch' && frame.function !== 'setTimeout') {
+        expect(frame).toHaveProperty('abs_path');
+        expect(frame).toHaveProperty('lineno');
+        expect(frame).toHaveProperty('colno');
+        expect(typeof frame.abs_path).toBe('string');
+        expect(typeof frame.lineno).toBe('number');
+        expect(typeof frame.colno).toBe('number');
+      }
+    }
+
+    const functionNames = profile1.frames.map(frame => frame.function).filter(name => name !== '');
+
+    if ((process.env.PW_BUNDLE || '').endsWith('min')) {
+      // In bundled mode, function names are minified
+      expect(functionNames.length).toBeGreaterThan(0);
+      expect((functionNames as string[]).every(name => name?.length > 0)).toBe(true); // Just make sure they're not empty strings
+    } else {
+      expect(functionNames).toEqual(
+        expect.arrayContaining([
+          '_startRootSpan',
+          'withScope',
+          'createChildOrRootSpan',
+          'startSpanManual',
+          'startJSSelfProfile',
+
+          // first function is captured (other one is in other chunk)
+          'fibonacci',
+        ]),
+      );
+    }
+
+    expect(profile1.thread_metadata).toHaveProperty('0');
+    expect(profile1.thread_metadata['0']).toHaveProperty('name');
+    expect(profile1.thread_metadata['0'].name).toBe('main');
+
+    // Test that profile duration makes sense (should be > 20ms based on test setup)
+    const startTimeSec = (profile1.samples[0] as any).timestamp as number;
+    const endTimeSec = (profile1.samples[profile1.samples.length - 1] as any).timestamp as number;
+    const durationSec = endTimeSec - startTimeSec;
+
+    // Should be at least 20ms based on our setTimeout(21) in the test
+    expect(durationSec).toBeGreaterThan(0.2);
+
+    // === PROFILE CHUNK 2 ===
+
+    const profileChunkEnvelopeItem2 = profileChunkEnvelopes[1][1][0];
+    const envelopeItemHeader2 = profileChunkEnvelopeItem2[0];
+    const envelopeItemPayload2 = profileChunkEnvelopeItem2[1];
+
+    // Basic sanity on the second chunk: has correct envelope type and structure
+    expect(envelopeItemHeader2).toHaveProperty('type', 'profile_chunk');
+    expect(envelopeItemPayload2.profile).toBeDefined();
+    expect(envelopeItemPayload2.version).toBe('2');
+    expect(envelopeItemPayload2.platform).toBe('javascript');
+
+    // Required profile metadata (Sample Format V2)
+    // https://develop.sentry.dev/sdk/telemetry/profiles/sample-format-v2/
+    expect(typeof envelopeItemPayload2.profiler_id).toBe('string');
+    expect(envelopeItemPayload2.profiler_id).toMatch(/^[a-f0-9]{32}$/);
+    expect(typeof envelopeItemPayload2.chunk_id).toBe('string');
+    expect(envelopeItemPayload2.chunk_id).toMatch(/^[a-f0-9]{32}$/);
+    expect(envelopeItemPayload2.client_sdk).toBeDefined();
+    expect(typeof envelopeItemPayload2.client_sdk.name).toBe('string');
+    expect(typeof envelopeItemPayload2.client_sdk.version).toBe('string');
+    expect(typeof envelopeItemPayload2.release).toBe('string');
+    expect(envelopeItemPayload2.debug_meta).toBeDefined();
+    expect(Array.isArray(envelopeItemPayload2?.debug_meta?.images)).toBe(true);
+
+    const profile2 = envelopeItemPayload2.profile;
+
+    const functionNames2 = profile2.frames.map(frame => frame.function).filter(name => name !== '');
+
+    if ((process.env.PW_BUNDLE || '').endsWith('min')) {
+      // In bundled mode, function names are minified
+      expect(functionNames2.length).toBeGreaterThan(0);
+      expect((functionNames2 as string[]).every(name => name?.length > 0)).toBe(true); // Just make sure they're not empty strings
+    } else {
+      expect(functionNames2).toEqual(
+        expect.arrayContaining([
+          '_startRootSpan',
+          'withScope',
+          'createChildOrRootSpan',
+          'startSpanManual',
+          'startJSSelfProfile',
+
+          // second function is captured (other one is in other chunk)
+          'largeSum',
+        ]),
+      );
+    }
+  },
+);

dev-packages/browser-integration-tests/suites/profiling/traceLifecycleMode_overlapping-spans/subject.js

@@ -0,0 +1,52 @@
+import * as Sentry from '@sentry/browser';
+import { browserProfilingIntegration } from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://[email protected]/1337',
+  integrations: [browserProfilingIntegration()],
+  tracesSampleRate: 1,
+  profileSessionSampleRate: 1,
+  profileLifecycle: 'trace',
+});
+
+function largeSum(amount = 1000000) {
+  let sum = 0;
+  for (let i = 0; i < amount; i++) {
+    sum += Math.sqrt(i) * Math.sin(i);
+  }
+}
+
+function fibonacci(n) {
+  if (n <= 1) {
+    return n;
+  }
+  return fibonacci(n - 1) + fibonacci(n - 2);
+}
+
+let firstSpan;
+
+Sentry.startSpanManual({ name: 'root-largeSum-1', parentSpan: null, forceTransaction: true }, span => {
+  largeSum();
+  firstSpan = span;
+});
+
+await Sentry.startSpanManual({ name: 'root-fibonacci-2', parentSpan: null, forceTransaction: true }, async span => {
+  fibonacci(40);
+
+  Sentry.startSpan({ name: 'child-fibonacci', parentSpan: span }, childSpan => {
+    console.log('child span');
+  });
+
+  // Timeout to prevent flaky tests. Integration samples every 20ms, if function is too fast it might not get sampled
+  await new Promise(resolve => setTimeout(resolve, 21));
+  span.end();
+});
+
+await new Promise(r => setTimeout(r, 21));
+
+firstSpan.end();
+
+const client = Sentry.getClient();
+await client?.flush(5000);