@sentry/astro

Official Sentry SDK for Astro

Links

• Official SDK Docs

SDK Status

This SDK is in Beta and not yet fully stable. If you have feedback or encounter any bugs, feel free to open an issue.

General

This package is a wrapper around @sentry/node for the server and @sentry/browser for the client side.

Installation and Setup

Install the Sentry Astro SDK with the astro CLI:

npx astro add @sentry/astro

Add your DSN and source maps upload configuration:

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

export default defineConfig({
  integrations: [
    sentry({
      dsn: '__DSN__',
      sourceMapsUploadOptions: {
        project: 'your-sentry-project-slug',
        authToken: process.env.SENTRY_AUTH_TOKEN,
      },
    }),
  ],
});

Follow this guide to create an auth token and add it to your environment variables:

SENTRY_AUTH_TOKEN="your-token"

Server Instrumentation

For Astro apps configured for (hybrid) Server Side Rendering (SSR), the Sentry integration will automatically add middleware to your server to instrument incoming requests if you're using Astro 3.5.2 or newer.

If you're using Astro <3.5.2, complete the setup by adding the Sentry middleware to your src/middleware.js file:

// src/middleware.js
import { sequence } from 'astro:middleware';
import * as Sentry from '@sentry/astro';

export const onRequest = sequence(
  Sentry.handleRequest(),
  // Add your other handlers after Sentry.handleRequest()
);

The Sentry middleware enhances the data collected by Sentry on the server side by:

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

Disable Automatic Server Instrumentation

You can opt out of using the automatic sentry server instrumentation in your astro.config.mjs file:

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

export default defineConfig({
  integrations: [
    sentry({
      dsn: '__DSN__',
      autoInstrumentation: {
        requestHandler: false,
      },
    }),
  ],
});

Configuration

Check out our docs for configuring your SDK setup:

• Getting Started
• Manual Setup and Configuration
• Source Maps Upload

Changelog

8.3.0

Important Changes

• Better Node Framework Span Data

This release improves data quality of spans emitted by Express, Fastify, Connect, Koa, Nest.js and Hapi.

• feat(node): Ensure connect spans have better data (#12130)

• feat(node): Ensure express spans have better data (#12107)

• feat(node): Ensure fastify spans have better data (#12106)

• feat(node): Ensure hapi spans have better data (#12140)

• feat(node): Ensure koa spans have better data (#12108)

• feat(node): Ensure Nest.js spans have better data (#12139)

• feat(deps): Bump @opentelemetry/instrumentation-express from 0.38.0 to 0.39.0 (#12079)

• feat(node): No-code init via --import=@sentry/node/init (#11999)

When using Sentry in ESM mode, you can now use Sentry without manually calling init like this:

 SENTRY_DSN=https://[e-mail]/0 node --import=@sentry/node/init app.mjs

When using CommonJS, you can do:

 SENTRY_DSN=https://[e-mail]/0 node --require=@sentry/node/init app.js

Other Changes

• chore: Align and update MIT license dates (#12143)
• chore: Resolve or postpone a random assortment of TODOs (#11977)
• doc(migration): Add entry for runWithAsyncContext (#12153)
• docs: Add migration docs to point out that default import does not work (#12100)
• docs(sveltekit): process.env.SENTRY_AUTH_TOKEN (#12118)
• feat(browser): Ensure browserProfilingIntegration is published to CDN (#12158)
• feat(google-cloud): Expose ESM build (#12149)
• feat(nextjs): Ignore Prisma critical dependency warnings (#12144)
• feat(node): Add app.free_memory info to events (#12150)
• feat(node): Do not create GraphQL resolver spans by default (#12097)
• feat(node): Use node: prefix for node built-ins (#11895)
• feat(replay): Use unwrapped setTimeout to avoid e.g. angular change detection (#11924)
• fix(core): Add dsn to span envelope header (#12096)
• fix(feedback): Improve feedback border color in dark-mode, and prevent auto-dark mode when a theme is picked (#12126)
• fix(feedback): Set optionOverrides to be optional in TS definition (#12125)
• fix(nextjs): Don't put undefined values in props (#12131)
• fix(nextjs): Fix legacy configuration method detection for emitting warning (#12136)
• fix(node): Ensure fetch/http breadcrumbs are created correctly (#12137)
• fix(node): Update @prisma/instrumentation from 5.13.0 to 5.14.0 (#12081)
• ref(node): Add log for running in ESM/CommonJS mode (#12134)
• ref(node): Handle failing hook registration gracefully (#12135)
• ref(node): Only show instrumentation warning when tracing is enabled (#12141)

Work in this release contributed by @pboling. Thank you for your contribution!