Automatic Instrumentation

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

What Our 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 Instrumentation

To enable 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.)

After configuration, you will see both pageload and navigation transactions in the Sentry UI.

Copied
// If you're using one of our integration packages, like `@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 TracingIntegrations.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

Supported options:

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.

For example:

  • A frontend application is served from example.com.
  • A backend service is served from api.example.com.
  • The frontend application makes API calls to the backend.
  • Set the tracingOrigins option to ['api.example.com'].
  • Now outgoing XHR/fetch requests to api.example.com will get the sentry-trace header attached.
Copied
Sentry.init({
  // ...
  integrations: [
    new Integrations.BrowserTracing({
      tracingOrigins: ["api.example.com"],
    }),
  ],
});

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

beforeNavigate is called at the start of every pageload or navigation transaction, and is passed an object containing the data with the transaction will be started. Using beforeNavigate gives you the option to modify that data, or drop the transaction entirely by returning undefined.

One common use case is parameterizing transaction names. For both pageload and navigation transactions, the BrowserTracing integration uses the browser's window.location value to generate a transaction name. Using beforeNavigate you can 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.

Copied
Sentry.init({
  // ...
  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(/\/[a-f0-9]{32}/g, "/<hash>")
            .replace(/\/\d+/g, "/<digits>"),
        };
      },
    }),
  ],
});

shouldCreateSpanForRequest

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

Copied
Sentry.init({
  // ...
  integrations: [
    new Integrations.BrowserTracing({
      shouldCreateSpanForRequest: url => {
        // Do not create spans for outgoing requests to a `/health/` endpoint
        return !url.match(/\/health\/?$/);
      },
    }),
  ],
});

idleTimeout

The idle time, measured in ms, to wait until the transaction will be finished. The transaction will use the end timestamp of the last finished span as the endtime for the transaction.

The default is 1000.

startTransactionOnLocationChange

This flag enables or disables creation of navigation transaction on history changes.

The default is true.

startTransactionOnPageLoad

This flag enables or disables creation of pageload transaction on first pageload.

The default is true.

maxTransactionDuration

The maximum duration of a transaction, measured in seconds, before it will be marked as "deadline_exceeded". If you never want transactions marked that way, set maxTransactionDuration to 0.

The default is 600.

markBackgroundTransactions

This option flags transactions when tabs are moved to the background with "cancelled". Because browser background tab timing is not suited for precise measurements of operations and can affect your statistics in nondeterministic ways, we recommend that this option be enabled.

The default is true.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").