From cf628067dd442f45d1bb8acdbff5a8284b3a0a22 Mon Sep 17 00:00:00 2001 From: Abhijeet Prasad Date: Mon, 23 Sep 2024 09:17:48 -0400 Subject: [PATCH] feat(cloudflare): Add framework specific guides (#11396) --- .../guides/cloudflare/frameworks/astro.mdx | 36 +++++++++++ .../guides/cloudflare/frameworks/index.mdx | 8 +++ .../guides/cloudflare/frameworks/remix.mdx | 44 +++++++++++++ .../cloudflare/frameworks/sveltekit.mdx | 64 +++++++++++++++++++ 4 files changed, 152 insertions(+) create mode 100644 docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx create mode 100644 docs/platforms/javascript/guides/cloudflare/frameworks/index.mdx create mode 100644 docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx create mode 100644 docs/platforms/javascript/guides/cloudflare/frameworks/sveltekit.mdx diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx new file mode 100644 index 0000000000000..40adf850a3da5 --- /dev/null +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx @@ -0,0 +1,36 @@ +--- +title: Cloudflare Astro Framework Guide +description: "Learn how to add Cloudflare instrumentation to your Astro app." +--- + +If you're running your Astro app on Cloudflare Pages, you can use the Sentry Astro SDK in combination with the Sentry Cloudflare SDK to add Sentry instrumentation. + +First, install the Sentry Astro SDK in your application. We recommend [setting up the Astro SDK manually](/platforms/javascript/guides/astro/manual-setup/) and manually initializing the SDK. Make sure you have a `sentry.client.config.js` file created, but do not add a `sentry.server.config.js` file. + +After installing the Sentry Astro SDK, you can now install the Sentry Cloudflare SDK. First, install the SDK with your package manager: + + + +To use the SDK, you'll need to set either the `nodejs_compat` or `nodejs_als` compatibility flags in your `wrangler.toml`. This is because the SDK +needs access to the `AsyncLocalStorage` API to work correctly. + +```toml {filename:wrangler.toml} +compatibility_flags = ["nodejs_compat"] +# compatibility_flags = ["nodejs_als"] +``` + +Then create a `functions` directory and add a `_middleware.js` file to it with the following code: + +```javascript {filename:functions/_middleware.js} +import * as Sentry from "@sentry/cloudflare"; + +export const onRequest = [ + // Make sure Sentry is the first middleware + Sentry.sentryPagesPlugin((context) => ({ + dsn: "___PUBLIC_DSN___", + // Set tracesSampleRate to 1.0 to capture 100% of spans for tracing. + tracesSampleRate: 1.0, + })), + // Add more middlewares here +]; +``` diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/index.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/index.mdx new file mode 100644 index 0000000000000..a895bac706b40 --- /dev/null +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/index.mdx @@ -0,0 +1,8 @@ +--- +title: Cloudflare SDK Framework Guide +description: "Learn how to set up the Cloudflare SDK with popular Frameworks like SvelteKit or Remix." +--- + +You can use the Sentry Cloudlare SDK in combination with Sentry meta-framework SDKs like SvelteKit or Remix to instrument your Cloudflare Pages applications that use these frameworks. + + diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx new file mode 100644 index 0000000000000..6db013ef60dcc --- /dev/null +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx @@ -0,0 +1,44 @@ +--- +title: Cloudflare Remix Framework Guide +description: "Learn how to add Cloudflare instrumentation to your Remix app." +--- + +If you're running your Remix app on Cloudflare Pages, you can use the Sentry Remix SDK in combination with the Sentry Cloudflare SDK to add Sentry instrumentation. + +First, install the Sentry Remix SDK in your application. We recommend using the Sentry wizard to automatically install the SDK: + +```bash +npx @sentry/wizard@latest -i remix +``` + +If the setup through the wizard doesn't work for you, you can also [set up the Remix SDK manually](/platforms/javascript/guides/remix/manual-setup/). + +After installing the Sentry Remix SDK, delete the newly generated `instrumentation.server.mjs` file. This instrumentation is not needed when using the Cloudflare SDK. + +Now you can install the Sentry Cloudflare SDK. First, install the SDK with your package manager: + + + +To use the SDK, you'll need to set either the `nodejs_compat` or `nodejs_als` compatibility flags in your `wrangler.toml`. This is because the SDK +needs access to the `AsyncLocalStorage` API to work correctly. + +```toml {filename:wrangler.toml} +compatibility_flags = ["nodejs_compat"] +# compatibility_flags = ["nodejs_als"] +``` + +Then create a `_middleware.js` file in your `functions` directory and add the following code: + +```javascript {filename:functions/_middleware.js} +import * as Sentry from "@sentry/cloudflare"; + +export const onRequest = [ + // Make sure Sentry is the first middleware + Sentry.sentryPagesPlugin((context) => ({ + dsn: "___PUBLIC_DSN___", + // Set tracesSampleRate to 1.0 to capture 100% of spans for tracing. + tracesSampleRate: 1.0, + })), + // Add more middlewares here +]; +``` diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/sveltekit.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/sveltekit.mdx new file mode 100644 index 0000000000000..18c2841caaf7b --- /dev/null +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/sveltekit.mdx @@ -0,0 +1,64 @@ +--- +title: Cloudflare Sveltekit Framework Guide +description: "Learn how to add Cloudflare instrumentation to your SvelteKit app." +--- + +If you're running your SvelteKit app on Cloudflare Pages, you can use the Sentry SvelteKit SDK in combination with the Sentry Cloudflare SDK to add Sentry instrumentation. + +First, install the Sentry SvelteKit SDK in your application. We recommend using the Sentry wizard to automatically install the SDK: + +```bash +npx @sentry/wizard@latest -i sveltekit +``` + +If the setup through the wizard doesn't work for you, you can also [set up the SvelteKit SDK manually](/platforms/javascript/guides/sveltekit/manual-setup/). + +After installing the Sentry SvelteKit SDK, you can move on to setting up the Cloudflare SDK. First, install the SDK with your package manager: + + + +To use the SDK, you'll need to set either the `nodejs_compat` or `nodejs_als` compatibility flags in your `wrangler.toml`. This is because the SDK +needs access to the `AsyncLocalStorage` API to work correctly. + +```toml {filename:wrangler.toml} +compatibility_flags = ["nodejs_compat"] +# compatibility_flags = ["nodejs_als"] +``` + +To use this SDK, update your `src/hooks.server.ts` file to use the `Sentry.wrapRequestHandler` method from the Sentry Cloudflare SDK and remove the `Sentry.init` call from `@sentry/sveltekit`. + +```diff + import { sequence } from "@sveltejs/kit/hooks"; + import { handleErrorWithSentry, sentryHandle } from "@sentry/sveltekit"; +-import * as Sentry from '@sentry/sveltekit'; ++import * as Sentry from "@sentry/cloudflare"; + +-Sentry.init({ +- dsn: '___PUBLIC_DSN___', +- tracesSampleRate: 1.0, +- +- // uncomment the line below to enable Spotlight (https://spotlightjs.com) +- // spotlight: import.meta.env.DEV, +-}); +- ++const handleInitSentry = ({ event, resolve }) => { ++ return event.platform ++ ? Sentry.wrapRequestHandler( ++ { ++ options: { ++ dsn: '___PUBLIC_DSN___', ++ tracesSampleRate: 1.0, ++ }, ++ request: event.request, ++ context: event.platform.ctx, ++ }, ++ () => resolve(event) ++ ) ++ : resolve(event); ++}; +-// If you have custom handlers, make sure to place them after `sentryHandle()` in the `sequence` function. +-export const handle = sequence(sentryHandle()); ++export const handle = sequence(handleInitSentry, sentryHandle()); +``` + +If you need to use environmental variables, you can access them using `event.platform.env`.