From b14cafe4181eb3778ac7aa7c6d0b2ee3cf70dfe2 Mon Sep 17 00:00:00 2001 From: Atila Fassina Date: Tue, 5 Dec 2023 18:09:48 +0100 Subject: [PATCH 1/3] add guide to use Sentry with SolidJS --- .../javascript.solid.mdx | 43 +++ .../javascript.solid.mdx | 34 +++ .../javascript/guides/solid/config.yml | 7 + .../javascript/guides/solid/manual-setup.mdx | 266 ++++++++++++++++++ 4 files changed, 350 insertions(+) create mode 100644 src/platform-includes/getting-started-config/javascript.solid.mdx create mode 100644 src/platform-includes/getting-started-verify/javascript.solid.mdx create mode 100644 src/platforms/javascript/guides/solid/config.yml create mode 100644 src/platforms/javascript/guides/solid/manual-setup.mdx diff --git a/src/platform-includes/getting-started-config/javascript.solid.mdx b/src/platform-includes/getting-started-config/javascript.solid.mdx new file mode 100644 index 0000000000000..0155378529f49 --- /dev/null +++ b/src/platform-includes/getting-started-config/javascript.solid.mdx @@ -0,0 +1,43 @@ +To use the SDK, initialize it in your Solid entry point before bootstrapping your app. In a typical Solid project that is the render-client.js, or render-client.tsx. + + + +```javascript {filename: render-client.jsx} +import { render } from "solid-js/web"; +import App from "./app"; +import * as Sentry from "@sentry/browser"; +import { DEV } from "solid-js"; + +// this will only initialize your Sentry client in production builds. +if (!DEV) { + Sentry.init({ + dsn: "", + integrations: [new Sentry.BrowserTracing(), new Sentry.Replay()], + + // Set tracesSampleRate to 1.0 to capture 100% + // of transactions for performance monitoring. + // We recommend adjusting this value in production + tracesSampleRate: 1.0, + + // Set `tracePropagationTargets` to control for which URLs distributed tracing should be enabled + tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], + + // Capture Replay for 10% of all sessions, + // plus for 100% of sessions with an error + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, + }); +} + +const app = document.getElementById("app"); + +if (!app) throw new Error("No #app element found in the DOM."); + +render(() => , app); +``` + +Once you've done this, the SDK will automatically capture unhandled errors and promise rejections, and monitor performance in the client. + +It is also possible to add Client-Side routing to your app with [Solid-Router](https://docs.solidjs.com/guides/how-to-guides/routing-in-solid/solid-router) without any additional setting. As long as you use the default HTML History API to handle routing. + +Once you've done this, the SDK will automatically capture unhandled errors and promise rejections, and monitor performance in the client. You can also [manually capture errors](/platforms/javascript/guides/solid/usage). diff --git a/src/platform-includes/getting-started-verify/javascript.solid.mdx b/src/platform-includes/getting-started-verify/javascript.solid.mdx new file mode 100644 index 0000000000000..42f3add9389c9 --- /dev/null +++ b/src/platform-includes/getting-started-verify/javascript.solid.mdx @@ -0,0 +1,34 @@ +```javascript + +``` + +This snippet adds a button that throws an error in any Solid component you choose. It is useful for testing. It is recommended to base wrap your app within an Error Boundary: + +```javascript {filename: app.jsx} +import { ErrorBoundary } from "solid-js"; +import Routes from "./routes.tsx"; +import ErrorFallbackComponent from "./components/error-fallback"; +import * as Sentry from "@sentry/browser"; + +export default function App() { + const Routes = useRoutes(ROUTES); + + return ( + { + Sentry.captureException(error); + return ; + }} + > + + + ); +} +``` diff --git a/src/platforms/javascript/guides/solid/config.yml b/src/platforms/javascript/guides/solid/config.yml new file mode 100644 index 0000000000000..e7ffc4fa64b93 --- /dev/null +++ b/src/platforms/javascript/guides/solid/config.yml @@ -0,0 +1,7 @@ +title: Solid +sdk: sentry.javascript.browser +fallbackPlatform: javascript +caseStyle: camelCase +supportLevel: production +categories: + - browser diff --git a/src/platforms/javascript/guides/solid/manual-setup.mdx b/src/platforms/javascript/guides/solid/manual-setup.mdx new file mode 100644 index 0000000000000..a463593eec19a --- /dev/null +++ b/src/platforms/javascript/guides/solid/manual-setup.mdx @@ -0,0 +1,266 @@ +--- +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 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 +- 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 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: [ + 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: [ + 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. From 17a7ce1749687d3423ed1f1cd002623b87b81bea Mon Sep 17 00:00:00 2001 From: Atila Fassina Date: Wed, 6 Dec 2023 11:46:25 +0100 Subject: [PATCH 2/3] remove unnecessary manual setup --- .../javascript/guides/solid/manual-setup.mdx | 266 ------------------ 1 file changed, 266 deletions(-) delete mode 100644 src/platforms/javascript/guides/solid/manual-setup.mdx diff --git a/src/platforms/javascript/guides/solid/manual-setup.mdx b/src/platforms/javascript/guides/solid/manual-setup.mdx deleted file mode 100644 index a463593eec19a..0000000000000 --- a/src/platforms/javascript/guides/solid/manual-setup.mdx +++ /dev/null @@ -1,266 +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 --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 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 -- 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 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: [ - 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: [ - 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. From 031a7b2b336af9f2c7392a1beedc8c9cf9bb7cf3 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Wed, 13 Dec 2023 12:52:39 -0500 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Liza Mock --- .../getting-started-config/javascript.solid.mdx | 6 +++--- .../getting-started-verify/javascript.solid.mdx | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/platform-includes/getting-started-config/javascript.solid.mdx b/src/platform-includes/getting-started-config/javascript.solid.mdx index 0155378529f49..4fb4b810b0ff9 100644 --- a/src/platform-includes/getting-started-config/javascript.solid.mdx +++ b/src/platform-includes/getting-started-config/javascript.solid.mdx @@ -1,4 +1,4 @@ -To use the SDK, initialize it in your Solid entry point before bootstrapping your app. In a typical Solid project that is the render-client.js, or render-client.tsx. +To use the SDK, initialize it in your Solid entry point before bootstrapping your app. (In a typical Solid project that's the render-client.js, or render-client.tsx.) @@ -23,7 +23,7 @@ if (!DEV) { tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], // Capture Replay for 10% of all sessions, - // plus for 100% of sessions with an error + // plus 100% of sessions with an error replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 1.0, }); @@ -38,6 +38,6 @@ render(() => , app); Once you've done this, the SDK will automatically capture unhandled errors and promise rejections, and monitor performance in the client. -It is also possible to add Client-Side routing to your app with [Solid-Router](https://docs.solidjs.com/guides/how-to-guides/routing-in-solid/solid-router) without any additional setting. As long as you use the default HTML History API to handle routing. +It's also possible to add Client-Side routing to your app with [Solid-Router](https://docs.solidjs.com/guides/how-to-guides/routing-in-solid/solid-router) without changing any additional settings. As long as you use the default HTML History API to handle routing. Once you've done this, the SDK will automatically capture unhandled errors and promise rejections, and monitor performance in the client. You can also [manually capture errors](/platforms/javascript/guides/solid/usage). diff --git a/src/platform-includes/getting-started-verify/javascript.solid.mdx b/src/platform-includes/getting-started-verify/javascript.solid.mdx index 42f3add9389c9..924a040e20c7f 100644 --- a/src/platform-includes/getting-started-verify/javascript.solid.mdx +++ b/src/platform-includes/getting-started-verify/javascript.solid.mdx @@ -9,7 +9,7 @@ ``` -This snippet adds a button that throws an error in any Solid component you choose. It is useful for testing. It is recommended to base wrap your app within an Error Boundary: +This snippet adds a button that throws an error in any Solid component you choose. It's useful for testing. It's recommended to base wrap your app within an Error Boundary: ```javascript {filename: app.jsx} import { ErrorBoundary } from "solid-js";