Manual Setup

Learn how to manually customize the SDK 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.

Copied
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
Copied
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
  • Tracing 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.

astro.config.mjs
Copied
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 a Sentry.init call for the client side
  • sentry.server.config.js containing a Sentry.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.

Here's an example of a custom client-side SDK setup:

sentry.client.config.js
Copied
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
Copied
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
Copied
export default defineConfig({
  // Other Astro project options
  integrations: [
    sentry({
      clientInitPath: ".config/sentryClientInit.js",
      serverInitPath: ".config/sentryServerInit.js",
    }),
  ],
});

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

Help improve this content
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").