Automatic Instrumentation

@sentry/nextjs provides a BrowserTracing integration to add automatic instrumentation for monitoring the performance of browser applications, which is enabled by default once you set up

tracingThe process of logging the events that took place during a request, often across multiple services.
in your app. Further, the SDK will automatically enable error collection and performance monitoring in your API routes and Next.js Data Fetchers.

What Our Instrumentation Provides

The BrowserTracing integration creates a new transaction for each pageload and navigation event, and creates a child span for every XMLHttpRequest or fetch request that occurs while those transactions are open. Additionally, the SDK creates transactions for all requests to API routes and Next.js data fetchers. Learn more about traces, transactions, and spans.

Enable Instrumentation

To enable

tracingThe process of logging the events that took place during a request, often across multiple services.
, simply set either a tracesSampleRate or a tracesSampler in your SDK configuration options, as detailed in Set Up Tracing.

Configuration Options

Though the BrowserTracing integration is automatically enabled in @sentry/nextjs, in order to customize its options you must include it in your Sentry.init in sentry.client.config.js:

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

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

  integrations: [
    new Sentry.BrowserTracing({
      // custom options
    }),
  ],

  tracesSampleRate: 1.0,
});

Supported options:

tracePropagationTargets

A list of strings and regular expressions. The JavaScript SDK will attach the sentry-trace and baggage headers 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'll need to add it there to propagate the sentry-trace and baggage headers to the backend services, which is required to link transactions together as part of a single trace.

The tracePropagationTargets option matches the entire request URL, not just the domain. Using stricter regex to match certain parts of the URL ensures that requests don't unnecessarily have additional headers attached.

The default value of tracePropagationTargets is ['localhost', /^\//]. This means that by default,

tracingThe process of logging the events that took place during a request, often across multiple services.
headers are only attached to requests that contain localhost in their URL or requests whose URL starts with a '/' (for example GET /api/v1/users).

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 tracePropagationTargets 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 Sentry.BrowserTracing({
      tracePropagationTargets: ["api.example.com"],
    }),
  ],
});

You will need to configure your web server CORS to allow the sentry-trace and baggage headers. The configuration might look like "Access-Control-Allow-Headers: sentry-trace" and "Access-Control-Allow-Headers: baggage", but it depends on your set up. If you do not allow the two headers, 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.

Copied
Sentry.init({
  // ...
  integrations: [
    new BrowserTracing({
      beforeNavigate: context => {
        return {
          ...context,
          tags: {
            ...context.tags,
            resultFormat: "legacy",
          },
        };
      },
    }),
  ],
});

shouldCreateSpanForRequest

This function can be used to filter out unwanted spans such as XHRs running health checks or something similar. If this function isn't specified, spans will be created for all requests.

Copied
Sentry.init({
  // ...
  integrations: [
    new 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, if there are no unfinished spans. The transaction will use the end timestamp of the last finished span as the endtime for the transaction.

The default is 1000.

finalTimeout

The maximum duration of the transaction, measured in ms. If the transaction duration hits the finalTimeout value, it will be finished.

The default is 30000.

heartbeatInterval

The time, measured in ms, one heartbeat takes. If no new spans were started or no open spans finished within three heartbeats, the transaction will be finished. The heartbeat count restarts whenever a new span is created or an open span is finished.

The default is 5000.

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.

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.

_experiments

This is an object containing experimental flags for features that haven't yet landed in a new major version and might include breaking changes.

The default is

Copied
{
  enableLongTasks: true
}

_experiments.enableLongTasks

This experimental option determines whether spans for long tasks automatically get created.

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").