--- title: "Automatic Instrumentation" description: "Learn what spans are captured after tracing is enabled." url: https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation/ --- # Automatic Instrumentation | Sentry for Astro Capturing spans requires that you first [set up tracing in your app](https://docs.sentry.io/platforms/javascript/guides/astro/tracing.md) if you haven't already. The Sentry Astro SDK provides a `BrowserTracing` integration to add automatic instrumentation for monitoring the performance of browser applications, which is enabled by default. The SDK also automatically enables tracing in your server-side code. If you're using stream mode, automatic instrumentation works the same way as described in this guide but applies to service spans instead of transactions. See [Streamed Spans](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/streamed-spans.md) for more information. ## [What's Captured Automatically](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#whats-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 | | **Responsiveness** | Interaction to Next Paint | INP | | **Long tasks** | Main thread blocking > 50ms | Duration, attribution | 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](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing.md). ## [Enable Instrumentation](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#enable-instrumentation) To enable tracing, set either a `tracesSampleRate` or a `tracesSampler` in your SDK configuration options, as described in [Set Up Performance](https://docs.sentry.io/platforms/javascript/guides/astro/tracing.md). ## [Disable Automatic Instrumentation](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#disable-automatic-instrumentation) You can optionally disable the automatic server instrumentation by turning off the `requestHandler` auto instrumentation option: ```javascript import { defineConfig } from "astro/config"; import sentry from "@sentry/astro"; export default defineConfig({ integrations: [ sentry({ autoInstrumentation: { requestHandler: false, }, }), ], output: "server", }); ``` ## [Common Configuration](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#common-configuration) Most apps only need these options: * [Distributed Tracing Targets](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#distributed-tracing-targets) — Connect frontend and backend spans * [Customize Span Names](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#customize-span-names) — Normalize URLs or add context * [Filter Out Unwanted Requests](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#filter-out-unwanted-requests) — Exclude health checks, analytics ### [Distributed Tracing Targets](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#distributed-tracing-targets) ### [tracePropagationTargets](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#tracePropagationTargets) | Type | `Array` | | ------- | ------------------------- | | 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. ```javascript 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](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#customize-span-names) ### [beforeStartSpan](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#beforeStartSpan) | Type | `(options: StartSpanOptions) => StartSpanOptions` | | ---- | ------------------------------------------------- | Modify span data before it's captured. Useful for adding context or normalizing URLs with dynamic segments: One common use case is parameterizing transaction names. For both `pageload` and `navigation` transactions, the `browserTracingIntegration` uses the browser's `window.location` value to generate a transaction name. Using `beforeStartSpan` lets you 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 to `GET /users/:userid`. That way they'll be grouped together. ```javascript Sentry.init({ // ... integrations: [ Sentry.browserTracingIntegration({ beforeStartSpan: (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, "/") .replace(/\/\d+/g, "/"), }; }, }), ], }); ``` ### [Filter Out Unwanted Requests](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#filter-out-unwanted-requests) ### [shouldCreateSpanForRequest](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#shouldCreateSpanForRequest) | Type | `(url: string) => boolean` | | ---- | -------------------------- | Exclude requests from tracing, such as health checks or analytics pings: ```javascript 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](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#web-vitals--interactions) BrowserTracing automatically captures Web Vitals. To capture clicks and the work they trigger as spans, add the [Interactions integration](https://docs.sentry.io/platforms/javascript/guides/astro/configuration/integrations/interactions.md). ### [Configure Web Vitals](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#configure-web-vitals) ### [webVitals](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#webVitals) | Available since | `11.0.0` | | --------------- | ------------------ | | Type | `WebVitalsOptions` | Configure which Web Vitals BrowserTracing collects. For example, to disable INP collection: ```javascript Sentry.init({ // ... integrations: [ Sentry.browserTracingIntegration({ webVitals: { ignore: ["inp"], }, }), ], }); ``` If you explicitly add `webVitalsIntegration()`, configure these options on that integration instead. See [WebVitals](https://docs.sentry.io/platforms/javascript/guides/astro/configuration/integrations/webvitals.md) for details and browser support requirements. ### [Interaction to Next Paint (INP)](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#interaction-to-next-paint-inp) BrowserTracing automatically captures [INP](https://docs.sentry.io/product/dashboards/sentry-dashboards/frontend/web-vitals/web-vitals-concepts.md#interaction-to-next-paint-inp) to measure responsiveness. Results appear in the [Web Vitals](https://docs.sentry.io/product/dashboards/sentry-dashboards/frontend/web-vitals.md) module. ### [enableInp](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#enableInp) | Available since | `7.104.0` | | --------------- | ---------------------------- | | Type | `boolean` | | Default | `true` (since version 8.0.0) | Enable or disable INP collection. Defaults to `true` in SDK 8 and later, and `false` in SDK 7.x. Deprecated in SDK version 11. Use `webVitals: { ignore: ["inp"] }` to disable INP. Explicitly adding `webVitalsIntegration()` takes precedence over this option. ## [Advanced Options](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#advanced-options) Timing & Timeout Options These timeouts control pageload and navigation spans. Configure timeouts for click-triggered work on the [Interactions integration](https://docs.sentry.io/platforms/javascript/guides/astro/configuration/integrations/interactions.md) separately. ### [idleTimeout](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#idleTimeout) | Type | `number` | | ------- | -------- | | Default | `1000` | Time in ms to wait before finishing a pageload/navigation span when no unfinished child spans remain. ### [finalTimeout](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#finalTimeout) | Type | `number` | | ------- | -------- | | Default | `30000` | Maximum duration in ms for pageload/navigation spans. Spans exceeding this are automatically finished. ### [childSpanTimeout](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#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](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#instrumentPageLoad) | Type | `boolean` | | ------- | --------- | | Default | `true` | Enable/disable automatic `pageload` span creation on initial page load. ### [instrumentNavigation](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#instrumentNavigation) | Type | `boolean` | | ------- | --------- | | Default | `true` | Enable/disable automatic `navigation` span creation on history changes. ### [instrumentBfcacheRestore](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#instrumentBfcacheRestore) | Available since | `11.0.0` | | --------------- | --------- | | Type | `boolean` | | Default | `true` | Start a navigation span when the page is restored from the back/forward cache. This starts a new trace for activity after the restore. It is independent of `instrumentNavigation`. Web Vitals for restored pages are collected by default in stream mode. Set `webVitals: { bfcacheNavigations: false }` to disable this collection. See [WebVitals](https://docs.sentry.io/platforms/javascript/guides/astro/configuration/integrations/webvitals.md#bfcachenavigations) for requirements. ### [enableLongTask](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#enableLongTask) | Type | `boolean` | | ------- | --------- | | Default | `true` | Enable/disable automatic spans for long tasks (main thread blocking > 50ms). ### [enableLongAnimationFrame](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#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](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#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](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#enableReportPageLoaded) | Available since | `10.13.0` | | --------------- | --------- | | Type | `boolean` | | Default | `false` | Enable the [`Sentry.reportPageLoaded()` function](https://docs.sentry.io/platforms/javascript/guides/astro/apis.md#reportPageLoaded). ### [traceFetch](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#traceFetch) | Type | `boolean` | | ------- | --------- | | Default | `true` | Enable/disable automatic span creation for `fetch` requests. ### [traceXHR](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#traceXHR) | Type | `boolean` | | ------- | --------- | | Default | `true` | Enable/disable automatic span creation for `XMLHttpRequest` (XHR) requests. ### [enableHTTPTimings](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#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](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#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](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#ignoreResourceSpans) | Available since | `9.23.0` | | --------------- | --------------- | | Type | `Array` | | Default | `[]` | Ignore specific resource span categories by their `op` (e.g., `resource.script`, `resource.css`): ```javascript Sentry.init({ integrations: [ Sentry.browserTracingIntegration({ ignoreResourceSpans: ["resource.css", "resource.script"], }), ], }); ``` Use the [UserTiming integration](https://docs.sentry.io/platforms/javascript/guides/astro/configuration/integrations/usertiming.md) to capture `performance.mark()` and `performance.measure()` entries. To ignore entries by name: ```javascript Sentry.init({ integrations: [ Sentry.browserTracingIntegration(), Sentry.userTimingIntegration({ ignore: ["myMeasurement", /myMark/], }), ], }); ``` ### [onRequestSpanStart](https://docs.sentry.io/platforms/javascript/guides/astro/tracing/instrumentation/automatic-instrumentation.md#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.