@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:

• Enabling 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.43.0

Important Changes

• feat(nuxt): Add option autoInjectServerSentry (no default import()) (#14553)

  Using the dynamic import() as the default behavior for initializing the SDK on the server-side did not work for every project. The default behavior of the SDK has been changed, and you now need to use the --import flag to initialize Sentry on the server-side to leverage full functionality.

  Example with --import:

  node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs
  

  In case you are not able to use the --import flag, you can enable auto-injecting Sentry in the nuxt.config.ts (comes with limitations):

  sentry: {
    autoInjectServerSentry: 'top-level-import', // or 'experimental_dynamic-import'
  },
  

• feat(browser): Adds LaunchDarkly and OpenFeature integrations (#14207)

  Adds browser SDK integrations for tracking feature flag evaluations through the LaunchDarkly JS SDK and OpenFeature Web SDK:

  import * as Sentry from '@sentry/browser';
  
  Sentry.init({
    integrations: [
      // Track LaunchDarkly feature flags
      Sentry.launchDarklyIntegration(),
      // Track OpenFeature feature flags
      Sentry.openFeatureIntegration(),
    ],
  });
  

  • Read more about the Feature Flags feature in Sentry.
  • Read more about the LaunchDarkly SDK Integration.
  • Read more about the OpenFeature SDK Integration.

• feat(browser): Add featureFlagsIntegration for custom tracking of flag evaluations (#14582)

  Adds a browser integration to manually track feature flags with an API. Feature flags are attached to subsequent error events:

  import * as Sentry from '@sentry/browser';
  
  const featureFlagsIntegrationInstance = Sentry.featureFlagsIntegration();
  
  Sentry.init({
    // Initialize the SDK with the feature flag integration
    integrations: [featureFlagsIntegrationInstance],
  });
  
  // Manually track a feature flag
  featureFlagsIntegrationInstance.addFeatureFlag('my-feature', true);
  

• feat(astro): Add Astro 5 support (#14613)

  With this release, the Sentry Astro SDK officially supports Astro 5.

Deprecations

• feat(nextjs): Deprecate typedef for hideSourceMaps (#14594)

  The functionality of hideSourceMaps was removed in version 8 but was forgotten to be deprecated and removed. It will be completely removed in the next major version.

• feat(core): Deprecate APIs around RequestSessions (#14566)

  The APIs around RequestSessions are mostly used internally. Going forward the SDK will not expose concepts around RequestSessions. Instead, functionality around server-side Release Health will be managed in integrations.

Other Changes

• feat(browser): Add browserSessionIntegration (#14551)
• feat(core): Add raw_security envelope types (#14562)
• feat(deps): Bump @opentelemetry/instrumentation from 0.55.0 to 0.56.0 (#14625)
• feat(deps): Bump @sentry/cli from 2.38.2 to 2.39.1 (#14626)
• feat(deps): Bump @sentry/rollup-plugin from 2.22.6 to 2.22.7 (#14622)
• feat(deps): Bump @sentry/webpack-plugin from 2.22.6 to 2.22.7 (#14623)
• feat(nestjs): Add fastify support (#14549)
• feat(node): Add @vercel/ai instrumentation (#13892)
• feat(node): Add disableAnrDetectionForCallback function (#14359)
• feat(node): Add trackIncomingRequestsAsSessions option to http integration (#14567)
• feat(nuxt): Add option autoInjectServerSentry (no default import()) (#14553)
• feat(nuxt): Add warning when Netlify or Vercel build is discovered (#13868)
• feat(nuxt): Improve serverless event flushing and scope isolation (#14605)
• feat(opentelemetry): Stop looking at propagation context for span creation (#14481)
• feat(opentelemetry): Update OpenTelemetry dependencies to ^1.29.0 (#14590)
• feat(opentelemetry): Update OpenTelemetry dependencies to 1.28.0 (#14547)
• feat(replay): Upgrade rrweb packages to 2.30.0 (#14597)
• fix(core): Decode filename and module stack frame properties in Node stack parser (#14544)
• fix(core): Filter out unactionable CEFSharp promise rejection error by default (#14595)
• fix(nextjs): Don't show warning about devtool option (#14552)
• fix(nextjs): Only apply tracing metadata to data fetcher data when data is an object (#14575)
• fix(node): Guard against invalid maxSpanWaitDuration values (#14632)
• fix(react): Match routes with parseSearch option in TanStack Router instrumentation (#14328)
• fix(sveltekit): Fix git SHA not being picked up for release (#14540)
• fix(types): Fix generic exports with default (#14576)

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