Automatic Instrumentation

The @sentry/tracing package provides a BrowserTracing integration to add automatic instrumentation for monitoring the performance of browser applications.

What Automatic Instrumentation Provides

The BrowserTracing integration creates a new transaction for each page load and navigation event, and creates a child span for every XMLHttpRequest or fetch request that occurs while those transactions are open. Learn more about traces, transactions, and spans.

Enable Automatic Instrumentation

To enable this automatic tracing, include the BrowserTracing integration in your SDK configuration options. (Note that when using ESM modules, the main @sentry/* import must come before the @sentry/tracing import.)

// If you're using one of our integration packages, like `@sentry/react` or `@sentry/angular`,
// substitute its name for `@sentry/browser` here
import * as Sentry from "@sentry/browser";
import { Integrations as TracingIntegrations } from "@sentry/tracing"; // Must import second

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  integrations: [
    new Integrations.BrowserTracing({
      tracingOrigins: ["localhost", "my-site-url.com", /^\//],
      // ... other options
    }),
  ],

  // We recommend adjusting this value in production, or using tracesSampler
  // for finer control
  tracesSampleRate: 1.0,
});

Configuration Options

You can pass many different options to the BrowserTracing integration (as an object of the form {optionName: value}), but it comes with reasonable defaults out of the box. For all possible options, see TypeDocs.

tracingOrigins

The default value of tracingOrigins is ['localhost', /^\//]. The JavaScript SDK will attach the sentry-trace header to all outgoing XHR/fetch requests whose destination contains a string in the list or matches a regex in the list. If your frontend is making requests to a different domain, you will need to add it there to propagate the sentry-trace header to the backend services, which is required to link transactions together as part of a single trace. The tracingOrigins option matches against the whole request URL, not just the domain. Using stricter regex to match certain parts of the URL ensures that requests do not unnecessarily have the sentry-trace header attached.

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [
    new Integrations.BrowserTracing({
      tracingOrigins: ["localhost", "my-site-url.com"],
    }),
  ],

  // We recommend adjusting this value in production, or using tracesSampler
  // for finer control
  tracesSampleRate: 1.0,
});

You will need to configure your web server CORS to allow the sentry-trace header. The configuration might look like "Access-Control-Allow-Headers: sentry-trace", but the configuration depends on your set up. If you do not allow the sentry-trace header, the request might be blocked.

beforeNavigate

For pageload and navigation transactions, the BrowserTracing integration uses the browser's window.location API to generate a transaction name. To customize the name of the pageload and navigation transactions, you can supply a beforeNavigate option to the BrowserTracing integration. This option allows you to modify the transaction name to make it more generic, so that, for example, transactions named GET /users/12312012 and GET /users/11212012 can both be renamed GET /users/:userid, so that they'll group together.

import * as Sentry from "@sentry/browser";
import { Integrations } from "@sentry/tracing";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [
    new Integrations.BrowserTracing({
      beforeNavigate: context => {
        return {
          ...context,
          // You could use your UI's routing library to find the matching
          // route template here. We don't have one right now, so do some basic
          // parameter replacements.
          name: location.pathname
            .replace(/\d+/g, "<digits>")
            .replace(/[a-f0-9]{32}/g, "<hash>"),
        };
      },
    }),
  ],

  // We recommend adjusting this value in production, or using tracesSampler
  // for finer control
  tracesSampleRate: 1.0,
});

shouldCreateSpanForRequest

This function can be used to filter out unwanted spans such as XHR's running health checks or something similar. By default shouldCreateSpanForRequest already filters out everything but what was defined in tracingOrigins.

import * as Sentry from "@sentry/browser";
import { Integrations } from "@sentry/tracing";
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [
    new Integrations.BrowserTracing({
      shouldCreateSpanForRequest: url => {
        // Do not create spans for outgoing requests to a `/health/` endpoint
        return !url.match(/\/health\/?$/);
      },
    }),
  ],

  // We recommend adjusting this value in production, or using tracesSampler
  // for finer control
  tracesSampleRate: 1.0,
});