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

s1gr1d · 2025-11-12T15:53:22Z

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.

github-actions · 2025-11-12T15:58:36Z

size-limit report 📦

Path	Size	% Change	Change
@sentry/browser	24.78 kB	-	-
@sentry/browser - with treeshaking flags	23.27 kB	-	-
@sentry/browser (incl. Tracing)	41.51 kB	-	-
@sentry/browser (incl. Tracing, Profiling)	46.1 kB	+0.59%	+269 B 🔺
@sentry/browser (incl. Tracing, Replay)	79.92 kB	-	-
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags	69.65 kB	-	-
@sentry/browser (incl. Tracing, Replay with Canvas)	84.6 kB	-	-
@sentry/browser (incl. Tracing, Replay, Feedback)	96.85 kB	-	-
@sentry/browser (incl. Feedback)	41.45 kB	-	-
@sentry/browser (incl. sendFeedback)	29.46 kB	-	-
@sentry/browser (incl. FeedbackAsync)	34.4 kB	-	-
@sentry/react	26.49 kB	-	-
@sentry/react (incl. Tracing)	43.51 kB	-	-
@sentry/vue	29.22 kB	-	-
@sentry/vue (incl. Tracing)	43.31 kB	-	-
@sentry/svelte	24.79 kB	-	-
CDN Bundle	27.14 kB	+0.2%	+52 B 🔺
CDN Bundle (incl. Tracing)	42.14 kB	+0.16%	+64 B 🔺
CDN Bundle (incl. Tracing, Replay)	78.67 kB	+0.11%	+79 B 🔺
CDN Bundle (incl. Tracing, Replay, Feedback)	84.13 kB	+0.07%	+53 B 🔺
CDN Bundle - uncompressed	79.71 kB	+0.32%	+249 B 🔺
CDN Bundle (incl. Tracing) - uncompressed	125.08 kB	+0.2%	+249 B 🔺
CDN Bundle (incl. Tracing, Replay) - uncompressed	241.11 kB	+0.11%	+249 B 🔺
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed	253.87 kB	+0.1%	+249 B 🔺
@sentry/nextjs (client)	45.93 kB	-	-
@sentry/sveltekit (client)	41.87 kB	-	-
@sentry/node-core	51.15 kB	-0.01%	-1 B 🔽
@sentry/node	159.46 kB	-0.01%	-1 B 🔽
@sentry/node - without tracing	93.02 kB	-0.01%	-1 B 🔽
@sentry/aws-serverless	106.78 kB	-0.01%	-1 B 🔽

View base workflow run

github-actions · 2025-11-14T15:12:27Z

node-overhead report 🧳

Note: This is a synthetic benchmark with a minimal express app and does not necessarily reflect the real-world performance impact in an application.

Scenario	Requests/s	% of Baseline	Prev. Requests/s	Change %
GET Baseline	8,859	-	8,762	+1%
GET With Sentry	1,799	20%	1,719	+5%
GET With Sentry (error only)	6,226	70%	6,107	+2%
POST Baseline	1,223	-	1,194	+2%
POST With Sentry	614	50%	593	+4%
POST With Sentry (error only)	1,082	88%	1,073	+1%
MYSQL Baseline	3,355	-	3,366	-0%
MYSQL With Sentry	522	16%	470	+11%
MYSQL With Sentry (error only)	2,732	81%	2,717	+1%

View base workflow run

s1gr1d · 2025-11-17T10:14:02Z

packages/browser/src/profiling/UIProfiler.ts

    this._sessionSampled = sessionSampled;
+    this._lifecycleMode = lifecycleMode;

-    client.on('spanStart', span => {


The client.on calls (spanStart, spanEnd) are now added in the _setupTraceLifecycleListeners function.

This PR was factored out of another PR to make reviewing easier. The other PR: #18189 Moved the `spanStart` and `spanEnd` listeners into an extra function (`_setupTraceLifecycleListeners`) to be able to only call it depending on the lifecycle (used in another PR). Part of #17279

# Conflicts: # packages/browser/src/profiling/UIProfiler.ts

packages/browser/src/profiling/UIProfiler.ts

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

s1gr1d · 2025-11-17T13:32:41Z

packages/browser/src/profiling/index.ts

This file is similar to the Node profiling one: packages/core/src/profiling.ts (can be seen at the end of this diff page)

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

packages/browser/src/profiling/UIProfiler.ts

cursor · 2025-11-17T13:50:43Z

packages/browser/src/profiling/UIProfiler.ts

+    // Trace: Profile context is kept as long as there is an active root span
+    if (this._lifecycleMode === 'manual') {
+      getGlobalScope().setContext('profile', {});
+    }


Bug: Profiling state leaks after trace completion.

In trace mode, when _endProfiling is called after the last root span ends, the profile context is not cleared. The condition if (this._lifecycleMode === 'manual') prevents clearing the context in trace mode, but when there are no active root spans (which is when _endProfiling is called from spanEnd), the context should be cleared to prevent subsequent transactions from being incorrectly marked as profiled. The profile context persists even though profiling has stopped, causing spans created after profiling ends to incorrectly appear as profiled.

The profiler context will stay the same for the whole profiling session as the profiler cannot be just stopped like in manual profiling, where there might be spans that are not profiled anymore.

Lms24

Nice work! Had one thought about the public API <> integration interaction but otherwise LGTM!

Lms24 · 2025-11-17T16:53:55Z

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

+  // In manual mode we start and stop once -> expect exactly one chunk
+  const profileChunkEnvelopes = await getMultipleSentryEnvelopeRequests<ProfileChunkEnvelope>(


l: the code suggests we get two envelopes/chunks. Should we update/remove the comment?

Lms24 · 2025-11-17T17:07:54Z

packages/browser/src/profiling/integration.ts

 const _browserProfilingIntegration = (() => {
  return {
    name: INTEGRATION_NAME,
+    _profiler: new UIProfiler(),


l/m: In case the CDN bundle tests fail, this is likely the reason why: _profiler is mangled by our terser config (makeTerserPlugin()) because it is not excluded from the ignore list of private properties.

We can either opt out of mangling this field, make it "public" (i.e. remove the leading underscore), or add client hooks instead of exposing any additional field. I'd personally prefer using client hooks because it makes the binding very loose and also removes the need for the isProfilingIntegrationWithProfiler type predicate. Happy to leave this up to you though!

cursor · 2025-11-21T17:51:27Z

packages/browser/src/profiling/integration.ts

            const laterRootSpan = laterActiveSpan && getRootSpan(laterActiveSpan);
            if (laterRootSpan) {
-              traceLifecycleProfiler.notifyRootSpanActive(laterRootSpan);
+              profiler.notifyRootSpanActive(laterRootSpan);


Bug: Profiler hooks registered without initialization for invalid lifecycle

The profiler hooks startUIProfiler and stopUIProfiler are registered before checking if the lifecycle mode is valid. If profileLifecycle is set to an invalid value (not 'manual' or 'trace'), the hooks get registered but profiler.initialize() is never called. This causes the profiler to be in an uninitialized state when users call uiProfiler.startProfiler() or uiProfiler.stopProfiler(), leading to undefined behavior since _lifecycleMode, _sessionSampled, and other fields remain undefined.

s1gr1d added 4 commits November 12, 2025 16:51

Add test for manual profiling

f6c55e2

add common UIProfiler

4e0c670

align with previous code

47b89b1

prepare profiling for manual mode

ea38195

s1gr1d added 4 commits November 13, 2025 16:43

add comment about node profiling namespace

32080bf

improve integration tests

98b6de2

add util in test

ff7fc66

add test, refactor

389a6a5

s1gr1d commented Nov 17, 2025

View reviewed changes

s1gr1d added 4 commits November 17, 2025 11:17

revert comment changes

53bdb13

add tests for logs

09bfd6c

remove profile_id between cycles

68847c3

remove lifecycle folder

d03bba3

s1gr1d mentioned this pull request Nov 17, 2025

ref(browser): Move trace lifecycle listeners to class function #18231

Merged

add deprecation warning

9373335

Merge branch 'develop' into sig/profiling-manual-mode

373a1ed

# Conflicts: # packages/browser/src/profiling/UIProfiler.ts

s1gr1d marked this pull request as ready for review November 17, 2025 13:29

cursor bot reviewed Nov 17, 2025

View reviewed changes

packages/browser/src/profiling/UIProfiler.ts Outdated Show resolved Hide resolved

packages/browser/src/profiling/UIProfiler.ts Show resolved Hide resolved

dev-packages/browser-integration-tests/suites/profiling/manualMode/test.ts Outdated Show resolved Hide resolved

remove ts comments

038edda

s1gr1d commented Nov 17, 2025

View reviewed changes

cursor bot reviewed Nov 17, 2025

View reviewed changes

dev-packages/browser-integration-tests/suites/profiling/manualMode/test.ts Outdated Show resolved Hide resolved

s1gr1d requested review from JPeer264, Lms24 and andreiborza November 17, 2025 13:34

fix small issues

9fe4c7d

cursor bot reviewed Nov 17, 2025

View reviewed changes

packages/browser/src/profiling/UIProfiler.ts Show resolved Hide resolved

packages/browser/src/profiling/UIProfiler.ts Show resolved Hide resolved

fix prettier

79dae58

cursor bot reviewed Nov 17, 2025

View reviewed changes

s1gr1d added 2 commits November 17, 2025 17:19

fix AI review comments

ea98579

fix deprecation issues

ffc15f2

Lms24 reviewed Nov 17, 2025

View reviewed changes

use client hooks

e9db290

cursor bot reviewed Nov 21, 2025

View reviewed changes

		// In manual mode we start and stop once -> expect exactly one chunk
		const profileChunkEnvelopes = await getMultipleSentryEnvelopeRequests<ProfileChunkEnvelope>(

Uh oh!

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

Are you sure you want to change the base?

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

Conversation

s1gr1d commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

github-actions bot commented Nov 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

node-overhead report 🧳

Uh oh!

s1gr1d Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

s1gr1d Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot Nov 17, 2025

Choose a reason for hiding this comment

Bug: Profiling state leaks after trace completion.

Uh oh!

s1gr1d Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

Lms24 left a comment

Choose a reason for hiding this comment

Uh oh!

Lms24 Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

Lms24 Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

cursor bot Nov 21, 2025

Choose a reason for hiding this comment

Bug: Profiler hooks registered without initialization for invalid lifecycle

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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

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

s1gr1d commented Nov 12, 2025 •

edited

Loading

github-actions bot commented Nov 12, 2025 •

edited

Loading

github-actions bot commented Nov 14, 2025 •

edited

Loading