Manual Setup
If you can't (or prefer not to) use the Astro CLI to install the Sentry Astro SDK, follow the instructions below to configure the SDK in your application manually.
This guide also explains how to further customize your SDK setup.
npm install --save @sentry/astro
If you're updating your Sentry SDK to the latest version, check out our migration guide to learn more about breaking changes.
Import and install the Sentry Astro integration:
astro.config.mjs
import { defineConfig } from "astro/config";
import sentry from "@sentry/astro";
export default defineConfig({
integrations: [
sentry({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
sourceMapsUploadOptions: {
project: "example-project",
authToken: process.env.SENTRY_AUTH_TOKEN,
},
}),
],
});
This integration enables the following features by default:
- Error Monitoring with 100% sample rate
- Performance Monitoring with 100% sample rate
- Session Replay with
- 10% sample rate for regular replay sessions
- 100% sample rate for sessions where an error occurred
- Automatic source maps upload for production builds to Add Readable Stack Traces to Errors. This requires providing an auth token and project slug.
Besides the required dsn
option, you can specify the following options in the integration directly. These are a subset of the full Sentry SDK options.
- release
- environment
- sampleRate
- tracesSampleRate
- replaysSessionSampleRate
- replaysOnErrorSampleRate
- debug Here's an example with all available integration options:
astro.config.mjs
import { defineConfig } from "astro/config";
import sentry from "@sentry/astro";
export default defineConfig({
integrations: [
sentry({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
release: "1.0.0",
environment: "production",
sampleRate: 0.5,
tracesSampleRate: 1.0,
replaysSessionSampleRate: 0.2,
replaysOnErrorSampleRate: 0.8,
debug: false,
sourceMapsUploadOptions: {
project: "example-project",
authToken: process.env.SENTRY_AUTH_TOKEN,
},
}),
],
});
To fully customize the SDK initialization, you can manually initialize the SDK for the client, server, or both. At build time, the integration looks for the following two files in the root directory of your config:
sentry.client.config.js
containing aSentry.init
call for the client sidesentry.server.config.js
containing aSentry.init
call for the sever side
This file can also be a .ts
, .mjs
, .mts
, etc. file.
In these files, you can specify the full range of Sentry SDK options.
If you add a sentry.client.config.js
or sentry.server.config.js
file, the options specified in the Sentry Astro integration are ignored for the respective runtime. The only exception is sourceMapsUploadOptions
which always needs to be set in the integration options.
Here's an example of a custom client-side SDK setup:
sentry.client.config.js
import * as Sentry from "@sentry/astro";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
replaysSessionSampleRate: 0.1,
replaysOnErrorSampleRate: 1.0,
integrations: [
Sentry.replayIntegration({
maskAllText: true,
blockAllMedia: true,
}),
Sentry.browserTracingIntegration({
tracePropagationTargets: [/\//, "my-api-domain.com"],
}),
],
tracesSampler: (samplingContext) => {
if (samplingContext.transactionContext.name === "/home") {
return 0.5;
}
return 0.1;
},
});
Here's an example of a custom server-side SDK setup:
sentry.server.config.js
import * as Sentry from "@sentry/astro";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
tracesSampler: (samplingContext) => {
if (samplingContext.transactionContext.name === "/home") {
return 0.5;
}
return 0.1;
},
beforeSend: (event) => {
console.log("before send", event);
return event;
},
});
To change the location of your sentry.(client|server).config.js
files, specify the path to the files in the Sentry Astro integration options in your astro.config.mjs
:
astro.config.mjs
export default defineConfig({
// Other Astro project options
integrations: [
sentry({
clientInitPath: ".config/sentryClientInit.js",
serverInitPath: ".config/sentryServerInit.js",
}),
],
});
Auto instrumentation only works for Astro 3.5.2 or newer. If you're using an older version, you need to manually add the Sentry middleware instead.
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
For Astro versions below 3.5.2, you need to manually add the Sentry middleware to your src/middleware.js
file:
src/middleware.(js|ts)
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.
Sentry's Astro middleware allows 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:
src/middleware.(js|ts)
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.
For Astro 3.5.2 or newer, you can disable the automatic server instrumentation by turning off the requestHandler
auto instrumentation option:
astro.config.mjs
import { defineConfig } from "astro/config";
import sentry from "@sentry/astro";
export default defineConfig({
integrations: [
sentry({
autoInstrumentation: {
requestHandler: false,
},
}),
],
output: "server",
});
To enable readable stack traces, set up source maps upload for your production builds.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").