Automatic Instrumentation | Sentry for Next.js

Source URL: https://docs.sentry.io/platforms/javascript/guides/nextjs/tracing/instrumentation/automatic-instrumentation

Automatic Instrumentation | Sentry for Next.js

Capturing spans requires that you first set up tracing in your app if you haven’t already.

@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 tracing in your app. Further, the SDK will automatically enable error collection and tracing in your API routes and Next.js Data Fetchers.

What’s Captured Automatically

Once you enable tracing, the SDK automatically captures performance data without additional code:

What	Description	Metrics
Page loads	Full page load performance	LCP, CLS, TTFB
Navigations	Client-side route changes	Duration, Web Vitals
HTTP requests	All fetch/XHR calls	Duration, status, URL
User interactions	Clicks, inputs that trigger work	INP (responsiveness)
Long tasks	Main thread blocking > 50ms	Duration, attribution

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 tracing, simply set either a tracesSampleRate or a tracesSampler in your SDK configuration options, as detailed in Set Up Tracing.

Common Configuration

Most apps only need these options:

• Distributed Tracing Targets — Connect frontend and backend spans
• Customize Span Names — Normalize URLs or add context
• Filter Out Unwanted Requests — Exclude health checks, analytics

• Distributed Tracing Targets

• tracePropagationTargets

Type	Array<string | RegExp>
Default	['localhost', /^\/$/]

Controls which outgoing requests include tracing headers (sentry-trace and baggage). Required for connecting frontend spans to backend spans.

By default, tracing headers are only attached to requests containing localhost or starting with /. Add your API domains to trace requests across services:

For example:

• A frontend application is served from example.com.
• A backend service is served from api.example.com.
• During development, the backend service is served from localhost.
• The frontend application makes API calls to the backend.
• Set the tracePropagationTargets option to ["localhost", /^https:\/\/api\.example\.com/].
• Now outgoing XHR/fetch requests to your backend service will get the sentry-trace and baggage headers attached.

Sentry.init({
  // ...
  integrations: [Sentry.browserTracingIntegration()],

  // Set `tracePropagationTargets` to control for which URLs trace propagation should be enabled
  tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
});

Your server must allow these headers via CORS: Access-Control-Allow-Headers: sentry-trace, baggage

• Customize Span Names

• beforeStartSpan

Type	(options: StartSpanOptions) => StartSpanOptions

Modify span data before it’s captured. Useful for adding context or normalizing URLs with dynamic segments:

Sentry.init({
  // ...
  integrations: [
    Sentry.browserTracingIntegration({
      beforeStartSpan: (context) => {
        return {
          ...context,
          attributes: {
            ...context.attributes,
            resultFormat: "legacy",
          },
        };
      },
    }),
  ],
});

• Filter Out Unwanted Requests

• shouldCreateSpanForRequest

Type	(url: string) => boolean

Exclude requests from tracing, such as health checks or analytics pings:

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

Web Vitals & Interactions

• Interaction to Next Paint (INP)

• enableInp

Available since	7.104.0
Type	boolean
Default	true (See note)

Automatically captures INP events to measure responsiveness. Results appear in the Web Vitals module.

Default: true in SDK 8.x+, false in 7.x.

INP replaces FID

As of SDK version 10.0.0, First Input Delay (FID) is no longer reported. Google deprecated FID in favor of INP, which provides a more comprehensive measure of responsiveness. If you have alerts or dashboards based on FID, update them to use INP instead.

Sentry.init({
  // ...
  integrations: [
    Sentry.browserTracingIntegration({
      enableInp: true,
    }),
  ],
});

• interactionsSampleRate

Type	number
Default	1.0

Sample rate for INP spans, applied on top of tracesSampleRate. For example, interactionsSampleRate: 0.5 with tracesSampleRate: 0.1 results in 5% of interactions captured.

Advanced Options

Timing & Timeout Options

• idleTimeout

Type	number
Default	1000

Time in ms to wait before finishing a pageload/navigation span when no unfinished child spans remain.

• finalTimeout

Type	number
Default	30000

Maximum duration in ms for pageload/navigation spans. Spans exceeding this are automatically finished.

• childSpanTimeout

Type	number
Default	15000

Maximum time in ms a child span can run before the parent pageload/navigation span is finished.

Enable/Disable Specific Instrumentation

• instrumentPageLoad

Type	boolean
Default	true

Enable/disable automatic pageload span creation on initial page load.

• instrumentNavigation

Type	boolean
Default	true

Enable/disable automatic navigation span creation on history changes.

• enableLongTask

Type	boolean
Default	true

Enable/disable automatic spans for long tasks (main thread blocking > 50ms).

• enableLongAnimationFrame

Available since	8.18.0
Type	boolean
Default	true

Enable/disable spans for long animation frames. Falls back to long tasks if browser doesn’t support long animation frames.

• markBackgroundSpan

Type	boolean
Default	true

Mark pageload/navigation spans as “cancelled” when the tab moves to background. Recommended to keep enabled for accurate measurements.

• enableReportPageLoaded

Available since	10.13.0
Type	boolean
Default	false

Enable the Sentry.reportPageLoaded() function.

• traceFetch

Type	boolean
Default	true

Enable/disable automatic span creation for fetch requests.

• traceXHR

Type	boolean
Default	true

Enable/disable automatic span creation for XMLHttpRequest (XHR) requests.

• enableHTTPTimings

Type	boolean
Default	true

Enable/disable adding detailed HTTP timing data (DNS lookup, TLS handshake, etc.) to fetch/XHR spans via the Performance Resource Timing API.

• linkPreviousTrace

Type	'in-memory' | 'session-storage' | false
Default	'in-memory'

Controls how new pageload spans are linked to the previous trace. Set to 'in-memory' to link within the same page lifecycle, 'session-storage' to persist links across page reloads via session storage, or false to disable trace linking.

Filtering & Ignoring Spans

• ignoreResourceSpans

Available since	9.23.0
Type	Array<string>
Default	[]

Ignore specific resource span categories by their op (e.g., resource.script, resource.css):

Sentry.init({
  integrations: [
    Sentry.browserTracingIntegration({
      ignoreResourceSpans: ["resource.css", "resource.script"],
    }),
  ],
});

• ignorePerformanceApiSpans

Available since	9.23.0
Type	Array<string | RegExp>
Default	[]

Ignore spans created from performance.mark() and performance.measure():

Sentry.init({
  integrations: [
    Sentry.browserTracingIntegration({
      ignorePerformanceApiSpans: ["myMeasurement", /myMark/],
    }),
  ],
});

• onRequestSpanStart

Type	(span: Span, requestInformation: { headers?: WebFetchHeaders }): void

Callback invoked when a span starts for an outgoing fetch/XHR request. Use to annotate spans with additional attributes based on request headers.

Next.js Configuration

The browserTracingIntegration is automatically enabled in @sentry/nextjs. To customize options, include it explicitly in instrumentation-client.js:

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

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  integrations: [
    Sentry.browserTracingIntegration({
      // your options here
    }),
  ],
  tracesSampleRate: 1.0,
  tracePropagationTargets: [
    "localhost",
    /^\//,
    /^https:\/\/yourserver\.io\/api/,
  ],
});