feat(browserprofiling): Add manual mode and deprecate old profiling (#18189)

Adds the `manual` mode for profiling and browser integration tests.

- adds deprecation note for old option
- adds some JSDoc comments to public-facing API to make the difference
between Node and UI profiling better visible.

Closes #17279

Author: s1gr1d

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

@@ -0,0 +1,76 @@
+import * as Sentry from '@sentry/browser';
+import { browserProfilingIntegration } from '@sentry/browser';
+
+window.Sentry = Sentry;
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  integrations: [browserProfilingIntegration()],
+  tracesSampleRate: 1,
+  profileSessionSampleRate: 1,
+  profileLifecycle: 'manual',
+});
+
+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);
+}
+
+function fibonacci1(n) {
+  if (n <= 1) {
+    return n;
+  }
+  return fibonacci1(n - 1) + fibonacci1(n - 2);
+}
+
+function fibonacci2(n) {
+  if (n <= 1) {
+    return n;
+  }
+  return fibonacci1(n - 1) + fibonacci1(n - 2);
+}
+
+function notProfiledFib(n) {
+  if (n <= 1) {
+    return n;
+  }
+  return fibonacci1(n - 1) + fibonacci1(n - 2);
+}
+
+// Adding setTimeout to ensure we cross the sampling interval to avoid flakes
+
+Sentry.uiProfiler.startProfiler();
+
+fibonacci(40);
+await new Promise(resolve => setTimeout(resolve, 25));
+
+largeSum();
+await new Promise(resolve => setTimeout(resolve, 25));
+
+Sentry.uiProfiler.stopProfiler();
+
+// ---
+
+notProfiledFib(40);
+await new Promise(resolve => setTimeout(resolve, 25));
+
+// ---
+
+Sentry.uiProfiler.startProfiler();
+
+fibonacci2(40);
+await new Promise(resolve => setTimeout(resolve, 25));
+
+Sentry.uiProfiler.stopProfiler();
+
+const client = Sentry.getClient();
+await client?.flush(8000);

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

@@ -0,0 +1,93 @@
+import { expect } from '@playwright/test';
+import type { ProfileChunkEnvelope } from '@sentry/core';
+import { sentryTest } from '../../../utils/fixtures';
+import {
+  countEnvelopes,
+  getMultipleSentryEnvelopeRequests,
+  properFullEnvelopeRequestParser,
+  shouldSkipTracingTest,
+} from '../../../utils/helpers';
+import { validateProfile, validateProfilePayloadMetadata } from '../test-utils';
+
+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 manual mode', 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' } });
+
+  // In manual mode we start and stop once -> expect exactly one chunk
+  const profileChunkEnvelopes = await getMultipleSentryEnvelopeRequests<ProfileChunkEnvelope>(
+    page,
+    2,
+    { url, envelopeType: 'profile_chunk', timeout: 8000 },
+    properFullEnvelopeRequestParser,
+  );
+
+  expect(profileChunkEnvelopes.length).toBe(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();
+
+  const profilerId1 = envelopeItemPayload1.profiler_id;
+
+  validateProfilePayloadMetadata(envelopeItemPayload1);
+
+  validateProfile(envelopeItemPayload1.profile, {
+    expectedFunctionNames: ['startJSSelfProfile', 'fibonacci', 'largeSum'],
+    minSampleDurationMs: 20,
+    isChunkFormat: true,
+  });
+
+  // only contains fibonacci
+  const functionNames1 = envelopeItemPayload1.profile.frames.map(frame => frame.function).filter(name => name !== '');
+  expect(functionNames1).toEqual(expect.not.arrayContaining(['fibonacci1', 'fibonacci2', 'fibonacci3']));
+
+  // === PROFILE CHUNK 2 ===
+
+  const profileChunkEnvelopeItem2 = profileChunkEnvelopes[1][1][0];
+  const envelopeItemHeader2 = profileChunkEnvelopeItem2[0];
+  const envelopeItemPayload2 = profileChunkEnvelopeItem2[1];
+
+  expect(envelopeItemHeader2).toHaveProperty('type', 'profile_chunk');
+  expect(envelopeItemPayload2.profile).toBeDefined();
+
+  expect(envelopeItemPayload2.profiler_id).toBe(profilerId1); // same profiler id for the whole session
+
+  validateProfilePayloadMetadata(envelopeItemPayload2);
+
+  validateProfile(envelopeItemPayload2.profile, {
+    expectedFunctionNames: [
+      'startJSSelfProfile',
+      'fibonacci1', // called by fibonacci2
+      'fibonacci2',
+    ],
+    isChunkFormat: true,
+  });
+
+  // does not contain notProfiledFib (called during unprofiled part)
+  const functionNames2 = envelopeItemPayload2.profile.frames.map(frame => frame.function).filter(name => name !== '');
+  expect(functionNames2).toEqual(expect.not.arrayContaining(['notProfiledFib']));
+});

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

@@ -90,7 +90,7 @@ export function validateProfile(
     }
   }
 
-  // Frames
+  // FRAMES
   expect(profile.frames.length).toBeGreaterThan(0);
   for (const frame of profile.frames) {
     expect(frame).toHaveProperty('function');

packages/browser/src/client.ts

@@ -130,7 +130,6 @@ export class BrowserClient extends Client<BrowserClientOptions> {
 
     // Flush logs and metrics when page becomes hidden (e.g., tab switch, navigation)
     // todo(v11): Remove the experimental flag
-    // eslint-disable-next-line deprecation/deprecation
     if (WINDOW.document && (sendClientReports || enableLogs || enableMetrics)) {
       WINDOW.document.addEventListener('visibilitychange', () => {
         if (WINDOW.document.visibilityState === 'hidden') {

packages/browser/src/exports.ts

@@ -78,6 +78,7 @@ export {
 export { WINDOW } from './helpers';
 export { BrowserClient } from './client';
 export { makeFetchTransport } from './transports/fetch';
+export { uiProfiler } from './profiling';
 export {
   defaultStackParser,
   defaultStackLineParsers,