Source URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/profiling/browser

Browser Profiling | Sentry for Next.js

Browser Profiling is currently in beta. Beta features are still in progress and may have bugs. We recognize the irony.

Profiling captures function-level data from your production code to enable you to fine-tune your app’s performance. It tracks what’s being called, how often, and where. In the browser, this helps you pinpoint causes of UI jank, understand why metrics like Interaction to Next Paint (INP) are slow, or identify long tasks blocking repaints and causing frame drops.

Chromium Only

Browser Profiling uses the JS Self-Profiling API, currently only available in Chromium-based browsers (Chrome, Edge). Profiles will only include data from these browsers.

Quick Setup

Requirements: @sentry/nextjs SDK version 10.27.0+ (or 7.60.0+ for deprecated transaction-based profiling)

1. Install the SDK

npm install @sentry/nextjs --save

2. Add the Document-Policy Header

Your server must return Document-Policy: js-profiling in response headers.

In Next.js you can configure document response headers via the headers option in next.config.js:

next.config.mjs

export default withSentryConfig({
  async headers() {
    return [
      {
        source: "/:path*",
        headers: [
          {
            key: "Document-Policy",
            value: "js-profiling",
          },
        ],
      },
    ];
  },

  // ... other Next.js config options
});

3. Configure the SDK

instrumentation-client.js|ts

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    // Add browser profiling integration to the list of integrations
    Sentry.browserProfilingIntegration(),
  ],

  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  tracesSampleRate: 1.0,
  // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
  tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],

  // Set profileSessionSampleRate to 1.0 to profile during every session.
  // The decision, whether to profile or not, is made once per session (when the SDK is initialized).
  profileSessionSampleRate: 1.0,
});

Profiling Modes

Mode	Description	Use When
Manual (default)	You control when profiling runs	Profiling specific user flows or interactions
Trace	Profiler runs automatically with active spans	You want profiles attached to all traced operations

Manual Mode

Start and stop the profiler around code you want to profile:

Sentry.uiProfiler.startProfiler();
// Code here will be profiled
Sentry.uiProfiler.stopProfiler();

Trace Mode

Profiles automatically attach to spans. Enable by setting profileLifecycle: "trace":

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.browserProfilingIntegration(),
  ],
  tracesSampleRate: 1.0,
  profileSessionSampleRate: 1.0,
  profileLifecycle: "trace",
});

Sentry vs Chrome DevTools

	Sentry Profiling	Chrome DevTools
Environment	Production (real users)	Local development
Sampling rate	100Hz (10ms period)	1000Hz (1ms period)
Source maps	Deobfuscated function names	Minified names
Data scope	Aggregated across users	Single session

Troubleshooting

Chrome DevTools shows “Profiling Overhead”

When browserProfilingIntegration is enabled, Chrome DevTools incorrectly attributes rendering work as profiling overhead. Disable the integration when using DevTools locally.

Profiles only from Chrome users

This is expected. The JS Self-Profiling API is currently only implemented in Chromium browsers. Consider this bias when analyzing data.