diff --git a/docs/platforms/javascript/guides/astro/manual-setup.mdx b/docs/platforms/javascript/guides/astro/manual-setup.mdx deleted file mode 100644 index 2a86edae878514..00000000000000 --- a/docs/platforms/javascript/guides/astro/manual-setup.mdx +++ /dev/null @@ -1,254 +0,0 @@ ---- -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 @sentry/astro --save -``` - -```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 sentry from "@sentry/astro"; - -export default defineConfig({ - integrations: [ - sentry({ - 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 -- 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](/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 sentry from "@sentry/astro"; - -export default defineConfig({ - integrations: [ - sentry({ - 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: [ - 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; - }, -}); -``` - -### 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 - -Sentry automatically detects configuration files named `sentry.(client|server).config.js` in the root of your project. You can rename these files or move them to a custom folder within your project. -To change their location or names, specify the paths in the Sentry Astro integration options in your `astro.config.mjs`: - -```javascript {filename:astro.config.mjs} -export default defineConfig({ - // Other Astro project options - integrations: [ - sentry({ - clientInitPath: ".config/sentryClientInit.js", - serverInitPath: ".config/sentryServerInit.js", - }), - ], -}); -``` - -## Configure Server Instrumentation - - - -Auto instrumentation only works for Astro 3.5.2 or newer. If you're using an older version, you need to [manually add the Sentry middleware](#manually-add-server-instrumentation) instead. - - - -In SSR or hybrid mode configured Astro apps, the Sentry Astro integration will automatically add an [Astro middleware](https://docs.astro.build/en/guides/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 - -### Manually Add Server Instrumentation - -For Astro versions below 3.5.2, you need to manually add the Sentry middleware to your `src/middleware.js` file: - -```javascript {filename:src/middleware.(js|ts)} -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. - -### Customize Server Instrumentation - -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: - -```javascript {filename:src/middleware.(js|ts)} -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. - -### Disable Auto Server Instrumentation - -For Astro 3.5.2 or newer, you can disable the automatic server instrumentation by turning off the `requestHandler` auto instrumentation option: - -```javascript {filename:astro.config.mjs} -import { defineConfig } from "astro/config"; -import sentry from "@sentry/astro"; - -export default defineConfig({ - integrations: [ - sentry({ - autoInstrumentation: { - requestHandler: false, - }, - }), - ], - output: "server", -}); -``` - -## Configure Source Maps Upload - -To enable readable stack traces, set up source maps upload for your production builds. diff --git a/platform-includes/getting-started-config/javascript.astro.mdx b/platform-includes/getting-started-config/javascript.astro.mdx index ccec3814bd01d0..31d341da57706e 100644 --- a/platform-includes/getting-started-config/javascript.astro.mdx +++ b/platform-includes/getting-started-config/javascript.astro.mdx @@ -1,4 +1,6 @@ -Get started by adding your DSN to your Astro config file (`astro.config.mjs`): +To set up the Sentry SDK, register the Sentry integration and initialize the SDK for client and server in the root directory of your project: + +### Astro Integration Setup ```javascript {filename:astro.config.mjs} @@ -8,7 +10,6 @@ import sentry from "@sentry/astro"; export default defineConfig({ integrations: [ sentry({ - dsn: "___PUBLIC_DSN___", sourceMapsUploadOptions: { project: "___PROJECT_SLUG___", authToken: process.env.SENTRY_AUTH_TOKEN, @@ -18,4 +19,57 @@ export default defineConfig({ }); ``` -Once you've added your `dsn`, the SDK will automatically capture and send errors and performance events to Sentry. + + Passing runtime-specific configuration options (`dsn`, `release`, `environment`, `sampleRate`, `tracesSampleRate`, `replaysSessionSampleRate`, `replaysOnErrorSampleRate`) to the Sentry integration will be deprecated in future versions. + We recommend passing your configuration directly to the respective `Sentry.init()` calls in `sentry.client.config.js` and `sentry.server.config.js` instead. + + +### Client-Side Setup + +```javascript {filename:sentry.client.config.js} {"onboardingOptions": {"performance": "7,11-13", "session-replay": "8,14-21"}} +import * as Sentry from "@sentry/astro"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + + integrations: [ + Sentry.browserTracingIntegration(), + Sentry.replayIntegration(), + ], + + // Define how likely traces are sampled. Adjust this value in production, + // or use tracesSampler for greater control. + tracesSampleRate: 1.0, + + // This sets the sample rate to be 10%. You may want this to be 100% while + // in development and sample at a lower rate in production + replaysSessionSampleRate: 0.1, + + // If the entire session is not sampled, use the below sample rate to sample + // sessions when an error occurs. + replaysOnErrorSampleRate: 1.0, +}); +``` + +### Server-side Setup + +```javascript {filename:sentry.server.config.js} {"onboardingOptions": {"performance": "10-13", "profiling": "2,6-9,14-17"}} +import * as Sentry from "@sentry/astro"; +import { nodeProfilingIntegration } from '@sentry/profiling-node'; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + integrations: [ + // Add our Profiling integration + nodeProfilingIntegration(), + ], + + // Define how likely traces are sampled. Adjust this value in production, + // or use tracesSampler for greater control. + tracesSampleRate: 1.0, + + // Set sampling rate for profiling + // This is relative to tracesSampleRate + profilesSampleRate: 1.0 +}); +``` diff --git a/platform-includes/getting-started-install/javascript.astro.mdx b/platform-includes/getting-started-install/javascript.astro.mdx index 6278d70e88ec04..a6854f50495115 100644 --- a/platform-includes/getting-started-install/javascript.astro.mdx +++ b/platform-includes/getting-started-install/javascript.astro.mdx @@ -1,3 +1,7 @@ + + Install the SDK by using the `astro` CLI: ```bash {tabTitle:npm} @@ -14,4 +18,21 @@ pnpm 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. + + + +```bash {tabTitle:npm} +npm install @sentry/profiling-node +``` + +```bash {tabTitle:yarn} +yarn add @sentry/profiling-node +``` + +```bash {tabTitle:pnpm} +pnpm add @sentry/profiling-node +``` + + + +To finish the setup, configure the Sentry integration. \ No newline at end of file diff --git a/platform-includes/getting-started-next-steps/javascript.astro.mdx b/platform-includes/getting-started-next-steps/javascript.astro.mdx new file mode 100644 index 00000000000000..1346353734d0ea --- /dev/null +++ b/platform-includes/getting-started-next-steps/javascript.astro.mdx @@ -0,0 +1,89 @@ +## Advanced Configuration Options + +### Changing Config Files Location + +Sentry automatically detects configuration files named `sentry.(client|server).config.js` in the root of your project. You can rename these files or move them to a custom folder within your project. +To change their location or names, specify the paths in the Sentry Astro integration options in your `astro.config.mjs`: + +```javascript {filename:astro.config.mjs} +export default defineConfig({ + // Other Astro project options + integrations: [ + sentry({ + clientInitPath: ".config/sentryClientInit.js", + serverInitPath: ".config/sentryServerInit.js", + }), + ], +}); +``` + +### Server Instrumentation + + + +Auto instrumentation only works for Astro 3.5.2 or newer. If you're using an older version, you need to [manually add the Sentry middleware](#manually-add-server-instrumentation) instead. + + + +In SSR or hybrid mode configured Astro apps, the Sentry Astro integration will automatically add an [Astro middleware](https://docs.astro.build/en/guides/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 + +### Manually Add Server Instrumentation + +For Astro versions below 3.5.2, you need to manually add the Sentry middleware to your `src/middleware.js` file: + +```javascript {filename:src/middleware.(js|ts)} +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. + +### Customize Server Instrumentation + +Sentry's Astro middleware gives you 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: + +```javascript {filename:src/middleware.(js|ts)} +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. + +### Disable Auto Server Instrumentation + +For Astro 3.5.2 or newer, you can disable the automatic server instrumentation by turning off the `requestHandler` auto instrumentation option: + +```javascript {filename:astro.config.mjs} +import { defineConfig } from "astro/config"; +import sentry from "@sentry/astro"; + +export default defineConfig({ + integrations: [ + sentry({ + autoInstrumentation: { + requestHandler: false, + }, + }), + ], + output: "server", +}); +``` diff --git a/redirects.js b/redirects.js index e48788f633f2e4..bc4be065141703 100644 --- a/redirects.js +++ b/redirects.js @@ -868,6 +868,10 @@ const userDocsRedirects = [ destination: '/product/insights/ai/llm-monitoring/getting-started/the-dashboard/', }, // End of Insights reduirects. + { + source: '/platforms/javascript/guides/astro/manual-setup/', + destination: '/platforms/javascript/guides/astro/', + }, ]; /**