Astro

Sentry's Astro SDK enables automatic reporting of errors and performance data in your Astro application. Our Astro integration instruments both the client as well as the server side of your Astro application. This page walks you through adding Sentry to your Astro project, configuring it, adding readable stack traces, and verifying your setup.

Prerequisites

Before we get started, make sure you have the following:

• You need a Sentry account and project
• An Astro project that uses Astro 3.0.0 or newer.
• A Node runtime:
  • This SDK currently only works on Node runtimes (e.g. Node adapter, Vercel with Lambda functions). Non-Node runtimes, like Vercel's Edge runtime or Cloudflare Pages, are currently not supported.
• If you're using Astro's Netflify adapter (@astrojs/netlify), you need version 5.0.0 or newer.

Install

Sentry captures data by using an SDK within your application’s runtime.

Install the SDK by using the astro CLI:

npx astro add @sentry/astro

The astro CLI installs the SDK package and adds the Sentry integration to your astro.config.mjs file.

npm install @sentry/profiling-node

To finish the setup, configure the Sentry integration.

Configure

To set up the Sentry SDK, register the Sentry integration and initialize the SDK for client and server in the root directory of your project:

Astro Integration Setup

import { defineConfig } from "astro/config";
import sentry from "@sentry/astro";

export default defineConfig({
  integrations: [
    sentry({
      sourceMapsUploadOptions: {
        project: "example-project",
        authToken: process.env.SENTRY_AUTH_TOKEN,
      },
    }),
  ],
});

Client-Side Setup

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

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration(),
  ],

  // Define how likely traces are sampled. Adjust this value in production,
  // or use tracesSampler for greater control.
  tracesSampleRate: 1.0,
  
  // This sets the sample rate to be 10%. You may want this to be 100% while
  // in development and sample at a lower rate in production
  replaysSessionSampleRate: 0.1,

  // If the entire session is not sampled, use the below sample rate to sample
  // sessions when an error occurs.
  replaysOnErrorSampleRate: 1.0,
});

Server-side Setup

import * as Sentry from "@sentry/astro";
import { nodeProfilingIntegration } from '@sentry/profiling-node';

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  integrations: [
    // Add our Profiling integration
    nodeProfilingIntegration(),
  ],

  // Define how likely traces are sampled. Adjust this value in production,
  // or use tracesSampler for greater control.
  tracesSampleRate: 1.0,
  
  // Set sampling rate for profiling
  // This is relative to tracesSampleRate
  profilesSampleRate: 1.0
});

Add Readable Stack Traces to Errors

To get readable stack traces in your production builds, set the SENTRY_AUTH_TOKEN environment variable in your build environment. You can also add the environment variable to a .env.sentry-build-plugin file in the root of your project.

SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE

This, in combination with your sourceMapsUploadOptions configuration, will upload source maps to Sentry every time you make a production build.

Verify

This snippet includes an intentional error, so you can test that everything is working as soon as you set it up.

Trigger a test error somewhere in your Astro app, for example in one of your pages:

<button onclick="throw new Error('This is a test error')">
  Throw test error
</button>

To view and resolve the recorded error, log into sentry.io and select your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved.

Advanced Configuration Options

Changing Config Files Location

Sentry automatically detects configuration files named sentry.(client|server).config.js in the root of your project. You can rename these files or move them to a custom folder within your project. To change their location or names, specify the paths in the Sentry Astro integration options in your astro.config.mjs:

export default defineConfig({
  // Other Astro project options
  integrations: [
    sentry({
      clientInitPath: ".config/sentryClientInit.js",
      serverInitPath: ".config/sentryServerInit.js",
    }),
  ],
});

Server Instrumentation

In SSR or hybrid mode configured Astro apps, the Sentry Astro integration will automatically add an Astro middleware request handler to your server code. This middleware enhances the data collected by Sentry on the server side by:

• Collecting performance spans for incoming requests
• Enabeling distributed tracing between client and server
• Enhancing captured errors with additional information

Manually Add Server Instrumentation

For Astro versions below 3.5.2, you need to manually add the Sentry middleware to your src/middleware.js file:

import * as Sentry from "@sentry/astro";
import { sequence } from "astro:middleware";

export const onRequest = sequence(
  Sentry.handleRequest(),
  // other middleware handlers
);

If you have multiple request handlers, make sure to add the Sentry middleware as the first handler in the sequence.

Customize Server Instrumentation

Sentry's Astro middleware gives you control over what additional data should be added to the recorded request spans.

To customize the server instrumentation, add the Sentry middleware to your src/middleware.js file:

import * as Sentry from "@sentry/astro";
import { sequence } from "astro:middleware";

export const onRequest = sequence(
  Sentry.handleRequest({
    trackClientIp: true, // defaults to false
    trackHeaders: true, // defaults to false
  }),
  // other middleware handlers
);

If you're using Astro 3.5.2 or newer, make sure to also disable auto instrumentation as shown below.

Disable Auto Server Instrumentation

For Astro 3.5.2 or newer, you can disable the automatic server instrumentation by turning off the requestHandler auto instrumentation option:

import { defineConfig } from "astro/config";
import sentry from "@sentry/astro";

export default defineConfig({
  integrations: [
    sentry({
      autoInstrumentation: {
        requestHandler: false,
      },
    }),
  ],
  output: "server",
});