diff --git a/src/components/orgAuthTokenNote.tsx b/src/components/orgAuthTokenNote.tsx index a25b9541884649..f01257bcaa9790 100644 --- a/src/components/orgAuthTokenNote.tsx +++ b/src/components/orgAuthTokenNote.tsx @@ -38,7 +38,7 @@ export function OrgAuthTokenNote() { sign in {' '} - to create a token directly from the docs. + to create a token directly from this page. @@ -48,7 +48,7 @@ export function OrgAuthTokenNote() { manually create an Auth Token {' '} - or create a token directly from the docs. A created token will only be visible + or create a token directly from this page. A created token will only be visible once right after creation - make sure to copy it! diff --git a/src/platform-includes/capture-error/javascript.astro.mdx b/src/platform-includes/capture-error/javascript.astro.mdx new file mode 100644 index 00000000000000..4a649f987c6a64 --- /dev/null +++ b/src/platform-includes/capture-error/javascript.astro.mdx @@ -0,0 +1,11 @@ +You can pass an `Error` object to `captureException()` to have it captured as an event. It's also possible to pass non-`Error` objects and strings, but be aware that the resulting events in Sentry may be missing a stack trace. + +```javascript +import * as Sentry from "@sentry/astro"; + +try { + aFunctionThatMightFail(); +} catch (err) { + Sentry.captureException(err); +} +``` diff --git a/src/platform-includes/distributed-tracing/how-to-use/javascript.astro.mdx b/src/platform-includes/distributed-tracing/how-to-use/javascript.astro.mdx new file mode 100644 index 00000000000000..82a0fa4152aa48 --- /dev/null +++ b/src/platform-includes/distributed-tracing/how-to-use/javascript.astro.mdx @@ -0,0 +1,11 @@ +If you're using our Astro SDK, distributed tracing will work out of the box for the client and server runtimes. +To get around possible [Browser CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) issues, you should define `tracePropagationTargets` on the client-side. + +```js +// sentry.client.config.js +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [new BrowserTracing()], + tracePropagationTargets: ["https://myproject.org", /^\/api\//], +}); +``` diff --git a/src/platform-includes/enriching-events/import/javascript.astro.mdx b/src/platform-includes/enriching-events/import/javascript.astro.mdx new file mode 100644 index 00000000000000..682147b48149e6 --- /dev/null +++ b/src/platform-includes/enriching-events/import/javascript.astro.mdx @@ -0,0 +1,3 @@ +```javascript +import * as Sentry from "@sentry/astro"; +``` diff --git a/src/platform-includes/getting-started-config/javascript.astro.mdx b/src/platform-includes/getting-started-config/javascript.astro.mdx new file mode 100644 index 00000000000000..3741e1e8065ab3 --- /dev/null +++ b/src/platform-includes/getting-started-config/javascript.astro.mdx @@ -0,0 +1,22 @@ +Get started by adding your DSN to your Astro config file: + + + +```javascript {filename:astro.config.mjs} +import { defineConfig } from "astro/config"; +import sentry from "@sentry/astro"; + +export default defineConfig({ + integrations: [ + sentry({ + dsn: "___PUBLIC_DSN___", + sourceMapsUploadOptions: { + project: "___PROJECT_SLUG___", + authToken: process.env.SENTRY_AUTH_TOKEN, + }, + }), + ], +}); +``` + +Once you've added your `dsn`, the SDK will automatically capture and send errors and performance events to Sentry. diff --git a/src/platform-includes/getting-started-install/javascript.astro.mdx b/src/platform-includes/getting-started-install/javascript.astro.mdx new file mode 100644 index 00000000000000..39d4a7f756d227 --- /dev/null +++ b/src/platform-includes/getting-started-install/javascript.astro.mdx @@ -0,0 +1,9 @@ +We recommend installing the SDK by using the `astro` CLI: + +```bash +npx astro add @sentry/astro +``` + +The `astro` CLI installs the SDK package and adds the Sentry integration to your `astro.config.mjs` file. + +To finish the setup, configure the Sentry integration. diff --git a/src/platform-includes/getting-started-primer/javascript.astro.mdx b/src/platform-includes/getting-started-primer/javascript.astro.mdx new file mode 100644 index 00000000000000..a1454ce3134128 --- /dev/null +++ b/src/platform-includes/getting-started-primer/javascript.astro.mdx @@ -0,0 +1,14 @@ +Sentry's Astro SDK enables automatic reporting of errors and performance data. + + + +The Astro SDK is in **Alpha** and may undergo **breaking changes**. +Please report any issues you encounter in our [Github Repository](https://github.com/getsentry/sentry-javascript/issues/new/choose). + + + +## Compatibility + +The minimum supported Astro version is `3.0.0`. +This SDK currently only works on Node runtimes. +Non-Node runtimes, like Vercel's Edge runtime or Cloudflare Pages, are currently not supported. diff --git a/src/platform-includes/getting-started-sourcemaps/javascript.astro.mdx b/src/platform-includes/getting-started-sourcemaps/javascript.astro.mdx new file mode 100644 index 00000000000000..5b101663acbaf2 --- /dev/null +++ b/src/platform-includes/getting-started-sourcemaps/javascript.astro.mdx @@ -0,0 +1,11 @@ +## Add Readable Stack Traces to Errors + +To get readable stack traces in your production builds, add the `SENTRY_AUTH_TOKEN` environment variable to your environment, like in a `.env` file or in your CI setup. + + + +```bash {filename:.env} +SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ +``` + +This, in combination with your `sourceMapsUploadOptions` configuration, will upload source maps to Sentry every time you make a production build. diff --git a/src/platform-includes/getting-started-verify/javascript.astro.mdx b/src/platform-includes/getting-started-verify/javascript.astro.mdx new file mode 100644 index 00000000000000..16fa0d31c3f5a0 --- /dev/null +++ b/src/platform-includes/getting-started-verify/javascript.astro.mdx @@ -0,0 +1,13 @@ +Trigger a test error somewhere in your Astro app, for example in one of your pages: + +```html {filename: home.astro} + +``` + + + +Errors triggered from within Browser DevTools are sandboxed and won't trigger an error handler. Place the snippet directly in your code instead. + + diff --git a/src/platform-includes/performance/automatic-instrumentation-intro/javascript.astro.mdx b/src/platform-includes/performance/automatic-instrumentation-intro/javascript.astro.mdx new file mode 100644 index 00000000000000..751eb777ff6bc3 --- /dev/null +++ b/src/platform-includes/performance/automatic-instrumentation-intro/javascript.astro.mdx @@ -0,0 +1,2 @@ +The Sentry Astro SDK provides a `BrowserTracing` integration to add automatic instrumentation for monitoring the performance of browser applications, which is enabled by default. +The SDK also automatically enables performance monitoring in your server-side code. diff --git a/src/platform-includes/performance/configure-sample-rate/javascript.astro.mdx b/src/platform-includes/performance/configure-sample-rate/javascript.astro.mdx new file mode 100644 index 00000000000000..198d2e8d750eae --- /dev/null +++ b/src/platform-includes/performance/configure-sample-rate/javascript.astro.mdx @@ -0,0 +1,42 @@ +Either set `tracesSampleRate` in your `astro.config.mjs` file or in `sentry.(client|server).init.js`: + + + +```javascript {tabTitle:Integration Config}{filename:astro.config.mjs} +import { defineConfig } from "astro/config"; +import sentryAstro from "@sentry/astro"; + +export default defineConfig({ + integrations: [ + sentryAstro({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, + }), + ], +}); +``` + +```javascript {tabTitle:Custom Config (client)} {filename:sentry.client.config.js} +import * as Sentry from "@sentry/astro"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, +}); +``` + +```javascript {tabTitle:Custom Config (server)} {filename:sentry.server.config.js} +import * as Sentry from "@sentry/astro"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampleRate: 1.0, +}); +``` + + + +The `tracesSampler` callback can only be specified in custom SDK init files. +It is **not supported** in the `astro.config.mjs` file. + + diff --git a/src/platform-includes/performance/enable-automatic-instrumentation/javascript.astro.mdx b/src/platform-includes/performance/enable-automatic-instrumentation/javascript.astro.mdx new file mode 100644 index 00000000000000..095ca9d96cbdf8 --- /dev/null +++ b/src/platform-includes/performance/enable-automatic-instrumentation/javascript.astro.mdx @@ -0,0 +1 @@ +To enable tracing, set either a `tracesSampleRate` or a `tracesSampler` in your SDK configuration options, as described in Set Up Performance. diff --git a/src/platform-includes/performance/enable-tracing/javascript.astro.mdx b/src/platform-includes/performance/enable-tracing/javascript.astro.mdx new file mode 100644 index 00000000000000..0511bfc650bc4f --- /dev/null +++ b/src/platform-includes/performance/enable-tracing/javascript.astro.mdx @@ -0,0 +1 @@ +The Sentry Astro SDK comes with performance monitoring included. To enable it, configure the sample rate as described below. diff --git a/src/platform-includes/session-replay/install/javascript.astro.mdx b/src/platform-includes/session-replay/install/javascript.astro.mdx new file mode 100644 index 00000000000000..7bebb971e20476 --- /dev/null +++ b/src/platform-includes/session-replay/install/javascript.astro.mdx @@ -0,0 +1,11 @@ +The Replay integration is already included with the Sentry Astro SDK. + +```bash {tabTitle:npx} +npx astro add @sentry/astro +``` + + + +If the Astro CLI setup doesn't work for you, you can also set up the SDK manually. + + diff --git a/src/platform-includes/session-replay/setup/javascript.astro.mdx b/src/platform-includes/session-replay/setup/javascript.astro.mdx new file mode 100644 index 00000000000000..53bb46347e8b78 --- /dev/null +++ b/src/platform-includes/session-replay/setup/javascript.astro.mdx @@ -0,0 +1,53 @@ +Session replay is enabled by default if you use the SDK configuration in your `astro.config.mjs` file. + +You can customize Replay sample rates like so: + +```javascript {filename:astro.config.mjs} +import { defineConfig } from "astro/config"; +import sentry from "@sentry/astro"; + +export default defineConfig({ + integrations: [ + sentry({ + dsn: "___PUBLIC_DSN___", + replaysSessionSampleRate: 0.2, // defaults to 0.1 + replaysOnErrorSampleRate: 1.0, // defaults to 1.0 + }), + ], +}); +``` + +If you have a custom SDK configuration file for the client side (`sentry.client.config.js`), add the Sentry `Replay` integration: + +```javascript {filename:sentry.client.config.js} +import * as sentry from "@sentry/astro"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, + integrations: [new Sentry.Replay()], +}); +``` + + + +Do not add the `Replay` integration to your server-side Sentry config file (`sentry.server.config.js`). +Session Replay can only be included on the client side. + + + +### Lazy-loading Replay + +Once you've added the integration, Replay will start automatically. If you don't want to start it immediately (lazy-load it), you can use `addIntegration`: + +```javascript +Sentry.init({ + // Note, Replay is NOT instantiated below: + integrations: [], +}); + +// Sometime later +const { Replay } = await import("@sentry/astro"); +Sentry.addIntegration(new Replay()); +``` diff --git a/src/platform-includes/sourcemaps/overview/javascript.astro.mdx b/src/platform-includes/sourcemaps/overview/javascript.astro.mdx new file mode 100644 index 00000000000000..c8472eb1254037 --- /dev/null +++ b/src/platform-includes/sourcemaps/overview/javascript.astro.mdx @@ -0,0 +1,85 @@ +## Configure Source Maps Upload + +Source maps upload should work if you followed the [Astro CLI installation guide](/platforms/javascript/guides/astro/#add-readable-stack-traces-to-errors). However, there are some options to configure source maps upload for your production builds for other configurations. + +### Enable Source Maps Upload + +To automatically upload source maps during production builds, add the `SENTRY_AUTH_TOKEN` environment variable to your environment, for example in a `.env` file or in your CI setup. + + + +```bash {filename:.env} +SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ +``` + +Next, add your project slug to the `sourceMapsUploadOptions` in your Astro config: + +```javascript {filename:astro.config.mjs} +export default defineConfig({ + integrations: [ + sentryAstro({ + // Other Sentry options + sourceMapsUploadOptions: { + project: "___PROJECT_SLUG___", + authToken: process.env.SENTRY_AUTH_TOKEN, + }, + }), + ], +}); +``` + +### Working With Old Authentication Tokens + +Source maps work best with [organization-scoped auth tokens](/product/accounts/auth-tokens/#organization-auth-tokens). If you are using an old self-hosted Sentry version that doesn't yet support org-based tokens or you're using a different type of Sentry auth token, you'll need to additionally specify your `org` slug in your `sourceMapsUploadOptions`: + +```javascript {filename:astro.config.mjs} +export default defineConfig({ + integrations: [ + sentryAstro({ + // Other Sentry options + sourceMapsUploadOptions: { + project: "___PROJECT_SLUG___", + org: "___ORG_SLUG___", + authToken: process.env.SENTRY_AUTH_TOKEN, + }, + }), + ], +}); +``` + +### Disable Source Maps Upload + +You can disable automatic source maps upload in your Astro config: + +```javascript {filename:astro.config.mjs} +export default defineConfig({ + integrations: [ + sentryAstro({ + // Other Sentry options + sourceMapsUploadOptions: { + enabled: false, + }, + }), + ], +}); +``` + +### Disabeling Telemetry Data Collection + +The Astro SDK uses the Sentry Vite plugin to upload source maps. +This plugin collects telemetry data to help us improve the source map uploading experience. +Read more about this in our [Vite plugin documentation](https://www.npmjs.com/package/@sentry/vite-plugin#telemetry). +You can disable telemetry collection by setting `telemetry` to `false`: + +```javascript {filename:astro.config.mjs} +export default defineConfig({ + integrations: [ + sentryAstro({ + // Other Sentry options + sourceMapsUploadOptions: { + telemetry: false, + }, + }), + ], +}); +``` diff --git a/src/platform-includes/sourcemaps/primer/javascript.astro.mdx b/src/platform-includes/sourcemaps/primer/javascript.astro.mdx new file mode 100644 index 00000000000000..2cf31ed12e3344 --- /dev/null +++ b/src/platform-includes/sourcemaps/primer/javascript.astro.mdx @@ -0,0 +1,5 @@ +The Sentry Astro SDK will generate and upload source maps automatically during a production build, so that errors in Sentry contain readable stack traces. + +![Readable Stack Traces](/readable-stacktraces.png) + +The Astro SDK uses the [Sentry Vite Plugin](https://www.npmjs.com/package/@sentry/vite-plugin/) to upload source maps. See the Manual Configuration page and the Sentry [Vite plugin documentation](https://www.npmjs.com/package/@sentry/vite-plugin/#configuration) for more details. diff --git a/src/platforms/common/index.mdx b/src/platforms/common/index.mdx index c5742fcdfa6e09..e7affa84bc7e9c 100644 --- a/src/platforms/common/index.mdx +++ b/src/platforms/common/index.mdx @@ -22,7 +22,7 @@ Sentry captures data by using an SDK within your application’s runtime. ## Configure - + Configuration should happen as early as possible in your application's lifecycle. diff --git a/src/platforms/javascript/common/install/index.mdx b/src/platforms/javascript/common/install/index.mdx index d78433334f660f..53961317be5918 100644 --- a/src/platforms/javascript/common/install/index.mdx +++ b/src/platforms/javascript/common/install/index.mdx @@ -4,6 +4,7 @@ sidebar_order: 1 description: "Review our alternate installation methods." notSupported: - javascript.angular + - javascript.astro - javascript.bun - javascript.capacitor - javascript.cordova diff --git a/src/platforms/javascript/common/sourcemaps/uploading/index.mdx b/src/platforms/javascript/common/sourcemaps/uploading/index.mdx index 0febcb7f34f56a..f30963cf31e370 100644 --- a/src/platforms/javascript/common/sourcemaps/uploading/index.mdx +++ b/src/platforms/javascript/common/sourcemaps/uploading/index.mdx @@ -6,6 +6,7 @@ notSupported: - javascript.nextjs - javascript.remix - javascript.sveltekit + - javascript.astro --- diff --git a/src/platforms/javascript/guides/astro/config.yml b/src/platforms/javascript/guides/astro/config.yml new file mode 100644 index 00000000000000..cd21351b10bdda --- /dev/null +++ b/src/platforms/javascript/guides/astro/config.yml @@ -0,0 +1,8 @@ +title: Astro +sdk: sentry.javascript.astro +fallbackPlatform: javascript +caseStyle: camelCase +supportLevel: production +categories: + - browser + - server diff --git a/src/platforms/javascript/guides/astro/manual-setup.mdx b/src/platforms/javascript/guides/astro/manual-setup.mdx new file mode 100644 index 00000000000000..7a21525e5a9122 --- /dev/null +++ b/src/platforms/javascript/guides/astro/manual-setup.mdx @@ -0,0 +1,195 @@ +--- +title: Manual Setup +sidebar_order: 1 +description: "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. + +## Manual Installation + +```bash {tabTitle:npm} +npm install --save @sentry/astro +``` + +```bash {tabTitle:Yarn} +yarn add @sentry/astro +``` + +```bash {tabTitle:pnpm} +pnpm add @sentry/astro +``` + +If you're updating your Sentry SDK to the latest version, check out our [migration guide](https://github.com/getsentry/sentry-javascript/blob/master/MIGRATION.md) to learn more about breaking changes. + +## Configure the Astro Integration + +Import and install the Sentry Astro integration: + + + +```javascript {filename:astro.config.mjs} +import { defineConfig } from "astro/config"; +import sentryAstro from "@sentry/astro"; + +export default defineConfig({ + integrations: [ + sentryAstro({ + dsn: "___PUBLIC_DSN___", + sourceMapsUploadOptions: { + project: "___PROJECT_SLUG___", + 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](/platforms/javascript/guides/astro/#add-readable-stack-traces-to-errors). This requires providing an auth token and project slug. + +### Astro Integration Options + +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: + +```javascript {filename:astro.config.mjs} +import { defineConfig } from "astro/config"; +import sentryAstro from "@sentry/astro"; + +export default defineConfig({ + integrations: [ + sentryAstro({ + dsn: "___PUBLIC_DSN___", + release: "1.0.0", + environment: "production", + sampleRate: 0.5, + tracesSampleRate: 1.0, + replaysSessionSampleRate: 0.2, + replaysOnErrorSampleRate: 0.8, + debug: false, + sourceMapsUploadOptions: { + project: "___PROJECT_SLUG___", + authToken: process.env.SENTRY_AUTH_TOKEN, + }, + }), + ], +}); +``` + +## Manual SDK Initialization + +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. + + + +If you add a `sentry.client.config.js` or `sentry.server.config.js` file, the options specified in the [Sentry Astro integration](#astro-integration-options) are ignored for the respective runtime. +The only exception is `sourceMapsUploadOptions` which **always** needs to be set in the integration options. + + + +### Client Side + +Here's an example of a custom client-side SDK setup: + +```javascript {filename:sentry.client.config.js} +import * as sentry from "@sentry/astro"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, + integrations: [ + new Sentry.Replay({ + maskAllText: true, + blockAllMedia: true, + }), + new BrowserTracing({ + tracePropagationTargets: [/\//, "my-api-domain.com"], + }), + ], + tracesSampler: (samplingContext) => { + if (samplingContext.transactionContext.name === "/home") { + return 0.5; + } + return 0.1; + }, +}); +``` + +### Server Side + +Here's an example of a custom server-side SDK setup: + +```javascript {filename:sentry.server.config.js} +import * as sentry from "@sentry/astro"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + tracesSampler: (samplingContext) => { + if (samplingContext.transactionContext.name === "/home") { + return 0.5; + } + return 0.1; + }, + beforeSend: (event) => { + console.log("before send", event); + return event; + }, +}); +``` + +### Changing config files location + +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`: + +```javascript {filename:astro.config.mjs} +export default defineConfig({ + // Other Astro project options + integrations: [ + sentryAstro({ + clientInitPath: ".config/sentryClientInit.js", + serverInitPath: ".config/sentryServerInit.js", + }), + ], +}); +``` + +## Configure Source Maps Upload + +To enable readable stack traces, set up source maps upload for your production builds.