JavaScript Browser Profiling

Because our JavaScript browser profiling integration is built on top of the profiler exposed by the JS Self-Profiling API, it's in beta and will likely only move out once the official spec progresses and gains adoption. As with any beta package, there are risks involved in using it. See platform status.

Unlike Chrome DevTools profiler, which runs locally and is intended primarily as a debugging tool, Sentry's JavaScript Profiler runs in production. It captures profiling data from real users and reflects real-world performance.

Prerequisites

To get started with JavaScript browser profiling, you'll need to:

• Install the @sentry/browser SDK, minimum version 7.60.0
• Configure the document response header to include Document-Policy: js-profiling
• Configure the SDK to use the BrowserProfilingIntegration and set profilesSampleRate

Step 1: Install the JavaScript Browser SDK

Install our JavaScript browser SDK using either yarn or npm, the minimum version that supports profiling is 7.60.0.

yarn add @sentry/nextjs

Step 2: Add Document-Policy: js-profiling header

For the JavaScript browser profiler to start, the document response header needs to include a Document-Policy header key with the js-profiling value.

app.get("/", (request, response) => {
  response.set("Document-Policy", "js-profiling");
  response.sendFile("index.html");
});

Step 3: Configure the JavaScript SDK

Configuration should happen as early as possible in your application's lifecycle. Once this is done, Sentry's JavaScript SDK will capture all unhandled exceptions and transactions.

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

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [
    // Add browser profiling integration to the list of integrations
    new Sentry.BrowserProfilingIntegration(),
  ],

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

  // Set profilesSampleRate to 1.0 to profile every transaction.
  // Since profilesSampleRate is relative to tracesSampleRate,
  // the final profiling rate can be computed as tracesSampleRate * profilesSampleRate
  // For example, a tracesSampleRate of 0.5 and profilesSampleRate of 0.5 would
  // results in 25% of transactions being profiled (0.5*0.5=0.25)
  profilesSampleRate: 1.0,
});

The Difference Between DevTools & Sentry's JavaScript Browser Profiler

What does Sentry's JavaScript browser profile offer that Chrome DevTools does not?

• Sentry JavaScript profiler runs in production and captures real user data, showing real-world performance. DevTools runs locally on your machine and only shows profiles of what's running on your machine.
• Sentry runs at a lower sampling rate of 100Hz with a 10ms sample period versus a sampling rate of 1000Hz and a 1ms sample period for DevTools.
• Sentry supports deobfuscation, making it so that all the function names in your code are correct. Typically, when you run JavaScript code, it's minified, meaning that all the function names are replaced with machine-generated abbreviations.

Please note, that since the browser profiling API is currently only implemented in Chromium-based browsers, the profiles collected with Sentry's JavaScript browser profiling will inherently be biased toward that demographic. This is something that you'll need to consider if you're basing your decisions on the data collected.

We hope that as the Javascript browser profiling API gains adoption, other browsers will implement it as well. If you find the browser profiling feature helpful and would like to see it gain further adoption, please consider supporting the spec at the official WICG repository.