From d2e350f8ab3893c5264ceec7c5923eb568808ff0 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Tue, 17 Oct 2023 16:14:33 +0200 Subject: [PATCH 1/7] feat(js): Add Documentation for Sentry Astro SDK --- src/components/orgAuthTokenNote.tsx | 4 +- .../javascript.astro.mdx | 22 ++ .../javascript.astro.mdx | 9 + .../javascript.astro.mdx | 14 + .../javascript.astro.mdx | 11 + .../javascript.astro.mdx | 13 + .../sourcemaps/overview/javascript.astro.mdx | 0 .../sourcemaps/primer/javascript.astro.mdx | 3 + src/platforms/common/index.mdx | 2 +- .../javascript/common/install/index.mdx | 1 + .../common/sourcemaps/uploading/index.mdx | 1 + .../javascript/guides/astro/config.yml | 8 + .../javascript/guides/astro/manual-setup.mdx | 254 ++++++++++++++++++ 13 files changed, 339 insertions(+), 3 deletions(-) create mode 100644 src/platform-includes/getting-started-config/javascript.astro.mdx create mode 100644 src/platform-includes/getting-started-install/javascript.astro.mdx create mode 100644 src/platform-includes/getting-started-primer/javascript.astro.mdx create mode 100644 src/platform-includes/getting-started-sourcemaps/javascript.astro.mdx create mode 100644 src/platform-includes/getting-started-verify/javascript.astro.mdx create mode 100644 src/platform-includes/sourcemaps/overview/javascript.astro.mdx create mode 100644 src/platform-includes/sourcemaps/primer/javascript.astro.mdx create mode 100644 src/platforms/javascript/guides/astro/config.yml create mode 100644 src/platforms/javascript/guides/astro/manual-setup.mdx 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/getting-started-config/javascript.astro.mdx b/src/platform-includes/getting-started-config/javascript.astro.mdx new file mode 100644 index 00000000000000..e68a91b8a90e1d --- /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 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..ed72870918943e --- /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 takes care of installing the SDK package and adding the Sentry integration to your `astro.config.mjs` file. + +To finish the Setup, you still need to 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..c901589aa6b768 --- /dev/null +++ b/src/platform-includes/getting-started-primer/javascript.astro.mdx @@ -0,0 +1,14 @@ +Sentry's SvelteKit SDK enables automatic reporting of errors and performance data. + + + +The SDK for Astro is currently in **Alpha state** and it might still experience **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`. +Furthermore, this SDK currently only works on Node runtimes. +None-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..a96c77f944ccee --- /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 (e.g. via 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/sourcemaps/overview/javascript.astro.mdx b/src/platform-includes/sourcemaps/overview/javascript.astro.mdx new file mode 100644 index 00000000000000..e69de29bb2d1d6 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..358e25d55b81dc --- /dev/null +++ b/src/platform-includes/sourcemaps/primer/javascript.astro.mdx @@ -0,0 +1,3 @@ +`@sentry/astro` will generate and upload source maps automatically, so that errors in Sentry will contain readable stack traces. + +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..6c456e436d9fd3 --- /dev/null +++ b/src/platforms/javascript/guides/astro/manual-setup.mdx @@ -0,0 +1,254 @@ +--- +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 Astro SDK, follow the instructions below to configure the Sentry SvelteKit SDK in your application. + +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 is designed to get you started quickly and it 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 replaysSessions + - 100% sample rate for sessions where an error occurred +- Automatic source maps upload for production builds, if you [set up a Sentry auth token and specified your project slug](../#add-readable-stack-traces-to-errors). + +### Astro Integration Options + +Besides the required `dsn` option, you can specify a subset of Sentry SDK options in the integration directly. + +- 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, + }, + }), + ], +}); +``` + +If you want to fully customize the browser and client SDKs, e.g. (add a `beforeSend` callback) you can also [manually initialize the SDK](#manual-initialization). + +## Manual SDK Initialization + +To fully customize the SDK initialization, you can manually initialize the SDK for the client or server side 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 + +These 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 + +If you want 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({ + // Rest of your Astro project config + integrations: [ + sentryAstro({ + clientInitPath: ".config/sentryClientInit.js", + serverInitPath: ".config/sentryServerInit.js", + }), + ], +}); +``` + +## Configure Source Maps Upload + +You can specify a few options to configure source maps upload for your production builds. Generally, this should work if you followed the [Astro CLI installation guide](../#add-readable-stack-traces-to-errors). + +Note that source maps upload only works if an auth token is specified. + +### Working with old authentication tokens + +If you're not using our new [organization-scoped auth tokens](/product/accounts/auth-tokens/#organization-auth-tokens) yet, you need to additionally specify your `org` slug in your `sourceMapsUploadOptions`: + +```javascript {filename:astro.config.mjs} +export default defineConfig({ + integrations: [ + sentryAstro({ + // rest of your 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 Vite config: + +```javascript {filename:astro.config.mjs} +export default defineConfig({ + integrations: [ + sentryAstro({ + // rest of your sentry options + sourceMapsUploadOptions: { + enabled: false, + }, + }), + ], +}); +``` + +### Disabeling Telemetry Data Collection + +By default, our Vite 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({ + // rest of your sentry options + sourceMapsUploadOptions: { + telemetry: false, + }, + }), + ], +}); +``` From f0a730879c96e430d21d128981e2cf807d05c180 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Tue, 17 Oct 2023 17:04:34 +0200 Subject: [PATCH 2/7] add replay and more platform includes --- .../capture-error/javascript.astro.mdx | 11 ++++ .../how-to-use/javascript.astro.mdx | 14 +++++ .../import/javascript.astro.mdx | 3 ++ .../javascript.astro.mdx | 2 + .../javascript.astro.mdx | 42 +++++++++++++++ .../javascript.astro.mdx | 1 + .../enable-tracing/javascript.astro.mdx | 1 + .../install/javascript.astro.mdx | 11 ++++ .../session-replay/setup/javascript.astro.mdx | 53 +++++++++++++++++++ 9 files changed, 138 insertions(+) create mode 100644 src/platform-includes/capture-error/javascript.astro.mdx create mode 100644 src/platform-includes/distributed-tracing/how-to-use/javascript.astro.mdx create mode 100644 src/platform-includes/enriching-events/import/javascript.astro.mdx create mode 100644 src/platform-includes/performance/automatic-instrumentation-intro/javascript.astro.mdx create mode 100644 src/platform-includes/performance/configure-sample-rate/javascript.astro.mdx create mode 100644 src/platform-includes/performance/enable-automatic-instrumentation/javascript.astro.mdx create mode 100644 src/platform-includes/performance/enable-tracing/javascript.astro.mdx create mode 100644 src/platform-includes/session-replay/install/javascript.astro.mdx create mode 100644 src/platform-includes/session-replay/setup/javascript.astro.mdx 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..58004bced55d51 --- /dev/null +++ b/src/platform-includes/capture-error/javascript.astro.mdx @@ -0,0 +1,11 @@ +You can pass an `Error` object to `captureException()` to get it captured as 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..f328d1246f5ce6 --- /dev/null +++ b/src/platform-includes/distributed-tracing/how-to-use/javascript.astro.mdx @@ -0,0 +1,14 @@ +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", + "https://.*.otherservice.org/.*", + ], +}); +``` 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/performance/automatic-instrumentation-intro/javascript.astro.mdx b/src/platform-includes/performance/automatic-instrumentation-intro/javascript.astro.mdx new file mode 100644 index 00000000000000..a04e706c135144 --- /dev/null +++ b/src/platform-includes/performance/automatic-instrumentation-intro/javascript.astro.mdx @@ -0,0 +1,2 @@ +The Sentry SvelteKit 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..4cba18184d9a90 --- /dev/null +++ b/src/platform-includes/session-replay/install/javascript.astro.mdx @@ -0,0 +1,11 @@ +The Replay integration is **already included** with the Astro SDK package. + +```bash {tabTitle:Npx} +npx astro add @sentry/astro +``` + + + +If the setup through the Astro CLI 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..5f7863c3cc8e55 --- /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`: + +```js +Sentry.init({ + // Note, Replay is NOT instantiated below: + integrations: [], +}); + +// Sometime later +const { Replay } = await import("@sentry/astro"); +Sentry.addIntegration(new Replay()); +``` From 9eafc0dbe70b1a7809b9fdb6a4303dafd59f26a1 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 23 Oct 2023 10:01:59 +0200 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Shana Matthews --- .../capture-error/javascript.astro.mdx | 2 +- .../javascript.astro.mdx | 2 +- .../javascript.astro.mdx | 4 +-- .../javascript.astro.mdx | 8 +++--- .../javascript.astro.mdx | 2 +- .../javascript.astro.mdx | 2 +- .../install/javascript.astro.mdx | 6 ++--- .../session-replay/setup/javascript.astro.mdx | 4 +-- .../javascript/guides/astro/manual-setup.mdx | 27 +++++++++---------- 9 files changed, 28 insertions(+), 29 deletions(-) diff --git a/src/platform-includes/capture-error/javascript.astro.mdx b/src/platform-includes/capture-error/javascript.astro.mdx index 58004bced55d51..4a649f987c6a64 100644 --- a/src/platform-includes/capture-error/javascript.astro.mdx +++ b/src/platform-includes/capture-error/javascript.astro.mdx @@ -1,4 +1,4 @@ -You can pass an `Error` object to `captureException()` to get it captured as 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. +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"; diff --git a/src/platform-includes/getting-started-config/javascript.astro.mdx b/src/platform-includes/getting-started-config/javascript.astro.mdx index e68a91b8a90e1d..3741e1e8065ab3 100644 --- a/src/platform-includes/getting-started-config/javascript.astro.mdx +++ b/src/platform-includes/getting-started-config/javascript.astro.mdx @@ -19,4 +19,4 @@ export default defineConfig({ }); ``` -Once you added your `dsn`, the SDK will automatically capture and send errors and performance events to Sentry. +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 index ed72870918943e..39d4a7f756d227 100644 --- a/src/platform-includes/getting-started-install/javascript.astro.mdx +++ b/src/platform-includes/getting-started-install/javascript.astro.mdx @@ -4,6 +4,6 @@ We recommend installing the SDK by using the `astro` CLI: npx astro add @sentry/astro ``` -The `astro` CLI takes care of installing the SDK package and adding the Sentry integration to your `astro.config.mjs` file. +The `astro` CLI installs the SDK package and adds the Sentry integration to your `astro.config.mjs` file. -To finish the Setup, you still need to configure the sentry integration. +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 index c901589aa6b768..a1454ce3134128 100644 --- a/src/platform-includes/getting-started-primer/javascript.astro.mdx +++ b/src/platform-includes/getting-started-primer/javascript.astro.mdx @@ -1,8 +1,8 @@ -Sentry's SvelteKit SDK enables automatic reporting of errors and performance data. +Sentry's Astro SDK enables automatic reporting of errors and performance data. -The SDK for Astro is currently in **Alpha state** and it might still experience **breaking changes**. +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). @@ -10,5 +10,5 @@ Please report any issues you encounter in our [Github Repository](https://github ## Compatibility The minimum supported Astro version is `3.0.0`. -Furthermore, this SDK currently only works on Node runtimes. -None-Node runtimes, like Vercel's Edge runtime or Cloudflare Pages, are currently not supported. +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 index a96c77f944ccee..e998ee5aa16b58 100644 --- a/src/platform-includes/getting-started-sourcemaps/javascript.astro.mdx +++ b/src/platform-includes/getting-started-sourcemaps/javascript.astro.mdx @@ -1,6 +1,6 @@ ## 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 (e.g. via a `.env` file or in your CI setup). +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. diff --git a/src/platform-includes/performance/automatic-instrumentation-intro/javascript.astro.mdx b/src/platform-includes/performance/automatic-instrumentation-intro/javascript.astro.mdx index a04e706c135144..751eb777ff6bc3 100644 --- a/src/platform-includes/performance/automatic-instrumentation-intro/javascript.astro.mdx +++ b/src/platform-includes/performance/automatic-instrumentation-intro/javascript.astro.mdx @@ -1,2 +1,2 @@ -The Sentry SvelteKit SDK provides a `BrowserTracing` integration to add automatic instrumentation for monitoring the performance of browser applications, which is enabled by default. +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/session-replay/install/javascript.astro.mdx b/src/platform-includes/session-replay/install/javascript.astro.mdx index 4cba18184d9a90..7bebb971e20476 100644 --- a/src/platform-includes/session-replay/install/javascript.astro.mdx +++ b/src/platform-includes/session-replay/install/javascript.astro.mdx @@ -1,11 +1,11 @@ -The Replay integration is **already included** with the Astro SDK package. +The Replay integration is already included with the Sentry Astro SDK. -```bash {tabTitle:Npx} +```bash {tabTitle:npx} npx astro add @sentry/astro ``` -If the setup through the Astro CLI doesn't work for you, you can also set up the SDK manually. +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 index 5f7863c3cc8e55..53bb46347e8b78 100644 --- a/src/platform-includes/session-replay/setup/javascript.astro.mdx +++ b/src/platform-includes/session-replay/setup/javascript.astro.mdx @@ -1,4 +1,4 @@ -Session replay is **enabled by default** if you use the SDK configuration in your `astro.config.mjs` file. +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: @@ -41,7 +41,7 @@ Session Replay can only be included on the client side. 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`: -```js +```javascript Sentry.init({ // Note, Replay is NOT instantiated below: integrations: [], diff --git a/src/platforms/javascript/guides/astro/manual-setup.mdx b/src/platforms/javascript/guides/astro/manual-setup.mdx index 6c456e436d9fd3..452b23a4c6579b 100644 --- a/src/platforms/javascript/guides/astro/manual-setup.mdx +++ b/src/platforms/javascript/guides/astro/manual-setup.mdx @@ -4,7 +4,7 @@ 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 Astro SDK, follow the instructions below to configure the Sentry SvelteKit SDK in your application. +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. @@ -47,18 +47,18 @@ export default defineConfig({ }); ``` -This integration is designed to get you started quickly and it enables the following features by default: +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 replaysSessions + - 10% sample rate for regular replay sessions - 100% sample rate for sessions where an error occurred -- Automatic source maps upload for production builds, if you [set up a Sentry auth token and specified your project slug](../#add-readable-stack-traces-to-errors). +- 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 a subset of Sentry SDK options in the integration directly. +Besides the required `dsn` option, you can specify the following options in the integration directly. These are a subset of the full PlatformLink to="/configuration/options">Sentry SDK options. - release - @@ -104,17 +104,16 @@ export default defineConfig({ }); ``` -If you want to fully customize the browser and client SDKs, e.g. (add a `beforeSend` callback) you can also [manually initialize the SDK](#manual-initialization). ## Manual SDK Initialization -To fully customize the SDK initialization, you can manually initialize the SDK for the client or server side or both. +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 -These file can also be a `.ts`, `.mjs`, `.mts`, etc. file. +This file can also be a `.ts`, `.mjs`, `.mts`, etc. file. In these files, you can specify the full range of Sentry SDK options. @@ -178,7 +177,7 @@ Sentry.init({ ### Changing config files location -If you want 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`: +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({ @@ -194,13 +193,13 @@ export default defineConfig({ ## Configure Source Maps Upload -You can specify a few options to configure source maps upload for your production builds. Generally, this should work if you followed the [Astro CLI installation guide](../#add-readable-stack-traces-to-errors). +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. Note that source maps upload only works if an auth token is specified. -### Working with old authentication tokens +### Working With Old Authentication Tokens -If you're not using our new [organization-scoped auth tokens](/product/accounts/auth-tokens/#organization-auth-tokens) yet, you need to additionally specify your `org` slug in your `sourceMapsUploadOptions`: +Source maps work best with [organization-scoped auth tokens](/product/accounts/auth-tokens/#organization-auth-tokens). If you are 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({ @@ -219,13 +218,13 @@ export default defineConfig({ ### Disable Source Maps Upload -You can disable automatic source maps upload in your Vite config: +You can disable automatic source maps upload in your Astro config: ```javascript {filename:astro.config.mjs} export default defineConfig({ integrations: [ sentryAstro({ - // rest of your sentry options + // Other Sentry options sourceMapsUploadOptions: { enabled: false, }, From ad46d13d9b67a26a324c7e9a59411c942c585a89 Mon Sep 17 00:00:00 2001 From: "getsantry[bot]" <66042841+getsantry[bot]@users.noreply.github.com> Date: Mon, 23 Oct 2023 08:03:43 +0000 Subject: [PATCH 4/7] [getsentry/action-github-commit] Auto commit --- src/platforms/javascript/guides/astro/manual-setup.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/platforms/javascript/guides/astro/manual-setup.mdx b/src/platforms/javascript/guides/astro/manual-setup.mdx index 452b23a4c6579b..84c8c7ef0ee223 100644 --- a/src/platforms/javascript/guides/astro/manual-setup.mdx +++ b/src/platforms/javascript/guides/astro/manual-setup.mdx @@ -58,7 +58,7 @@ This integration enables the following features by default: ### 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 PlatformLink to="/configuration/options">Sentry SDK options. +Besides the required `dsn` option, you can specify the following options in the integration directly. These are a subset of the full PlatformLink to="/configuration/options">Sentry SDK options. - release - @@ -104,7 +104,6 @@ export default defineConfig({ }); ``` - ## Manual SDK Initialization To fully customize the SDK initialization, you can manually initialize the SDK for the client, server, or both. From 6023063e0b42355ab055b702c5cb519cbc6acedc Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 23 Oct 2023 10:50:54 +0200 Subject: [PATCH 5/7] move source maps from manual setup to sourcemaps page --- .../javascript.astro.mdx | 2 +- .../sourcemaps/overview/javascript.astro.mdx | 85 +++++++++++++++++++ .../sourcemaps/primer/javascript.astro.mdx | 4 +- .../javascript/guides/astro/manual-setup.mdx | 63 +------------- 4 files changed, 92 insertions(+), 62 deletions(-) diff --git a/src/platform-includes/getting-started-sourcemaps/javascript.astro.mdx b/src/platform-includes/getting-started-sourcemaps/javascript.astro.mdx index e998ee5aa16b58..5b101663acbaf2 100644 --- a/src/platform-includes/getting-started-sourcemaps/javascript.astro.mdx +++ b/src/platform-includes/getting-started-sourcemaps/javascript.astro.mdx @@ -8,4 +8,4 @@ To get readable stack traces in your production builds, add the `SENTRY_AUTH_TOK 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. +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/sourcemaps/overview/javascript.astro.mdx b/src/platform-includes/sourcemaps/overview/javascript.astro.mdx index e69de29bb2d1d6..f0638b5df80da2 100644 --- a/src/platform-includes/sourcemaps/overview/javascript.astro.mdx +++ 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 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 index 358e25d55b81dc..2cf31ed12e3344 100644 --- a/src/platform-includes/sourcemaps/primer/javascript.astro.mdx +++ b/src/platform-includes/sourcemaps/primer/javascript.astro.mdx @@ -1,3 +1,5 @@ -`@sentry/astro` will generate and upload source maps automatically, so that errors in Sentry will contain readable stack traces. +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/javascript/guides/astro/manual-setup.mdx b/src/platforms/javascript/guides/astro/manual-setup.mdx index 84c8c7ef0ee223..7a21525e5a9122 100644 --- a/src/platforms/javascript/guides/astro/manual-setup.mdx +++ b/src/platforms/javascript/guides/astro/manual-setup.mdx @@ -58,7 +58,7 @@ This integration enables the following features by default: ### 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 PlatformLink to="/configuration/options">Sentry SDK 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 - @@ -180,7 +180,7 @@ To change the location of your `sentry.(client|server).config.js` files, specify ```javascript {filename:astro.config.mjs} export default defineConfig({ - // Rest of your Astro project config + // Other Astro project options integrations: [ sentryAstro({ clientInitPath: ".config/sentryClientInit.js", @@ -192,61 +192,4 @@ export default defineConfig({ ## 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. - -Note that source maps upload only works if an auth token is specified. - -### 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 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({ - // rest of your 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 - -By default, our Vite 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({ - // rest of your sentry options - sourceMapsUploadOptions: { - telemetry: false, - }, - }), - ], -}); -``` +To enable readable stack traces, set up source maps upload for your production builds. From b628a1f3afb2c285a0dbc333aaba1fe209e06503 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 23 Oct 2023 11:14:06 +0200 Subject: [PATCH 6/7] add note about self-hosted --- src/platform-includes/sourcemaps/overview/javascript.astro.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platform-includes/sourcemaps/overview/javascript.astro.mdx b/src/platform-includes/sourcemaps/overview/javascript.astro.mdx index f0638b5df80da2..c8472eb1254037 100644 --- a/src/platform-includes/sourcemaps/overview/javascript.astro.mdx +++ b/src/platform-includes/sourcemaps/overview/javascript.astro.mdx @@ -30,7 +30,7 @@ export default defineConfig({ ### 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 a different type of Sentry auth token, you'll need to additionally specify your `org` slug in your `sourceMapsUploadOptions`: +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({ From 7d18a09e6c43fb30adfb2a5aa21f03314e793443 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 23 Oct 2023 11:38:22 +0200 Subject: [PATCH 7/7] fix invalid tracePropagationTargets value --- .../distributed-tracing/how-to-use/javascript.astro.mdx | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) 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 index f328d1246f5ce6..82a0fa4152aa48 100644 --- a/src/platform-includes/distributed-tracing/how-to-use/javascript.astro.mdx +++ b/src/platform-includes/distributed-tracing/how-to-use/javascript.astro.mdx @@ -6,9 +6,6 @@ To get around possible [Browser CORS](https://developer.mozilla.org/en-US/docs/W Sentry.init({ dsn: "___PUBLIC_DSN___", integrations: [new BrowserTracing()], - tracePropagationTargets: [ - "https://myproject.org", - "https://.*.otherservice.org/.*", - ], + tracePropagationTargets: ["https://myproject.org", /^\/api\//], }); ```