diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx index 3914a654fde2e..405addaed4d3e 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx @@ -15,6 +15,8 @@ After installing the Sentry Astro SDK, you can now install the Sentry Cloudflare ## Setup +The main Sentry configuration should happen as early as possible in your app's lifecycle. + Then create a `functions` directory and add a `_middleware.js` file to it with the following code: @@ -33,4 +35,4 @@ export const onRequest = [ })), // Add more middlewares here ]; -``` \ No newline at end of file +``` diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/hono.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/hono.mdx index 3c9557cdfa594..70f60d1e9079d 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/hono.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/hono.mdx @@ -11,12 +11,23 @@ This guide explains how to set up Sentry in your Hono application running on Clo ## Setup +The main Sentry configuration should happen as early as possible in your app's lifecycle. + - + - + ## Verify - + diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/nuxt.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/nuxt.mdx index ffa0e7412e3a5..ac32461b6884f 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/nuxt.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/nuxt.mdx @@ -24,6 +24,8 @@ If you installed the SDK before, make sure that `@sentry/nuxt` version `9.37.0` ## Setup +The main Sentry configuration should happen as early as possible in your app's lifecycle. + ### Adding the Nitro Plugin @@ -56,5 +58,3 @@ export default defineNitroPlugin(sentryCloudflareNitroPlugin((nitroApp: NitroApp } })) ``` - - diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx index d668577e6c7ae..b0440ff1a8b2a 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx @@ -23,6 +23,8 @@ Now you can install the Sentry Cloudflare SDK. First, install the SDK with your ## Setup +The main Sentry configuration should happen as early as possible in your app's lifecycle. + Then create a `_middleware.js` file in your `functions` directory and add the following code: @@ -39,4 +41,4 @@ export const onRequest = [ })), // Add more middlewares here ]; -``` \ No newline at end of file +``` diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/sveltekit.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/sveltekit.mdx index 1d3aeafe83ab4..d8e23ad4a2e03 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/sveltekit.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/sveltekit.mdx @@ -23,6 +23,8 @@ If you installed the SDK before, make sure that `@sentry/sveltekit` version `9.2 ## Setup +The main Sentry configuration should happen as early as possible in your app's lifecycle. + Next, update your `src/hooks.server.(ts|js)` file to use the `initCloudflareSentryHandle` method from the Sentry Cloudflare SDK and remove the `Sentry.init` call from `@sentry/sveltekit`. diff --git a/docs/platforms/javascript/guides/cloudflare/index.mdx b/docs/platforms/javascript/guides/cloudflare/index.mdx index 0bc95eadfbf76..6986b3e97c5ff 100644 --- a/docs/platforms/javascript/guides/cloudflare/index.mdx +++ b/docs/platforms/javascript/guides/cloudflare/index.mdx @@ -1,6 +1,6 @@ --- title: Cloudflare -description: "Official Sentry SDK for Cloudflare Workers and Cloudflare Pages." +description: "Learn how to manually set up Sentry for Cloudflare Workers and Cloudflare Pages and capture your first errors." sdk: sentry.javascript.cloudflare categories: - javascript @@ -9,7 +9,7 @@ categories: - serverless --- -You can use the Sentry Cloudflare SDK with popular frameworks running on Cloudflare: +Use this guide for general instructions on using the Sentry SDK with Cloudflare. If you're using any of the listed frameworks, follow their specific setup instructions: - **[Astro](frameworks/astro/)** - **[Hono](frameworks/hono/)** @@ -18,36 +18,41 @@ You can use the Sentry Cloudflare SDK with popular frameworks running on Cloudfl - **[Remix](frameworks/remix/)** - **[SvelteKit](frameworks/sveltekit/)** -Take a look at your framework of choice, as there are likely additional instructions for setting up Sentry with it. For more framework-specific guidance, see the [frameworks section](frameworks/). + -If you're not using one of these frameworks, or are just looking for general instructions for Cloudflare usage, you're in the right place. +## Step 1: Install -## Features - -In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). - -Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below. +Choose the features you want to configure, and this guide will show you how: -## Install + + +### Install the Sentry SDK + +Run the command for your preferred package manager to add the Sentry SDK to your application: -## Setup +## Step 2: Configure + +The main Sentry configuration should happen as early as possible in your app's lifecycle. + +### Wrangler Configuration -### Setup (Cloudflare Workers) +### Setup for Cloudflare Workers -If you do not have access to the `onRequest` middleware API, you can use the `wrapRequestHandler` API instead. For example: + +If you don't have access to the `onRequest` middleware API, you can use the `wrapRequestHandler` API instead. For example: ```javascript // hooks.server.js @@ -66,12 +71,12 @@ export const handle = ({ event, resolve }) => { }; ``` -### Setup (Cloudflare Pages) + -To use this SDK, add the `sentryPagesPlugin` as [middleware to your Cloudflare Pages application](https://developers.cloudflare.com/pages/functions/middleware/). +### Setup for Cloudflare Pages -We recommend adding a `functions/_middleware.js` for the middleware setup so that Sentry is initialized for your entire -app. +To use the Sentry SDK, add the `sentryPagesPlugin` as [middleware to your Cloudflare Pages application](https://developers.cloudflare.com/pages/functions/middleware/). +For this, we recommend you create a `functions/_middleware.js` file to set up the middleware for your entire app: ```javascript {filename:functions/_middleware.js} import * as Sentry from "@sentry/cloudflare"; @@ -94,11 +99,11 @@ export const onRequest = [ // Enable logs to be sent to Sentry enableLogs: true, // ___PRODUCT_OPTION_END___ logs - // ___PRODUCT_OPTION_START___ performance + // Set tracesSampleRate to 1.0 to capture 100% of spans for tracing. // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + // https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#tracesSampleRate tracesSampleRate: 1.0, // ___PRODUCT_OPTION_END___ performance }; @@ -107,58 +112,135 @@ export const onRequest = [ ]; ``` -### Cloudflare Durable Objects +## Step 3: Add Readable Stack Traces With Source Maps (Optional) -You can use the `instrumentDurableObjectWithSentry` method to instrument [Cloudflare Durable Objects](https://developers.cloudflare.com/durable-objects/). This will need to be done alongside the worker setup. +The stack traces in your Sentry errors probably won't look like your actual code. To fix this, upload your source maps to Sentry. -See the [Cloudflare Durable Objects](features/durableobject/) guide for more information. +First, set the `upload_source_maps` option to `true` in your `wrangler.(jsonc|toml)` config file to enable source map uploading: -### Cloudflare Workflows +```jsonc {tabTitle:JSON} {filename:wrangler.jsonc} +{ + "upload_source_maps": true, +} +``` -You can use the `instrumentWorkflowWithSentry` method to instrument [Cloudflare Workflows](https://developers.cloudflare.com/workflows/). This will need to be done alongside the worker setup. +```toml {tabTitle:Toml} {filename:wrangler.toml} +upload_source_maps = true +``` -See the [Cloudflare Workflows](features/workflows/) guide for more information. +Next, run the Sentry Wizard to finish your setup: -## Add Readable Stack Traces to Errors +```bash +npx @sentry/wizard@latest -i sourcemaps +``` -Depending on how you've set up your project, the stack traces in your Sentry errors probably don't look like your actual code. +## Step 4: Verify Your Setup -To fix this, upload your source maps to Sentry. +Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project. -To start, set the `upload_source_maps` option to `true` in your wrangler config file to enable source map uploading. +### Issues -```jsonc {tabTitle:JSON} {filename:wrangler.jsonc} -{ - "upload_source_maps": true, +First, let's make sure Sentry is correctly capturing errors and creating issues in your project. + +#### Cloudflare Workers + +Add the following code snippet to your main worker file to create a `/debug-sentry` route that triggers an error when called: + +```javascript {filename:index.js} +export default { + async fetch(request) { + const url = new URL(request.url); + + if (url.pathname === "/debug-sentry") { + throw new Error("My first Sentry error!"); + } + + // Your existing routes and logic here... + return new Response("..."); + }, +}; +``` + +#### Cloudflare Pages + +Create a new route that throws an error when called by adding the following code snippet to a file in your `functions` directory, such as `functions/debug-sentry.js`: + +```javascript {filename:debug-sentry.js} +export async function onRequest(context) { + throw new Error("My first Sentry error!"); } ``` -```toml {tabTitle:Toml} {filename:wrangler.toml} -upload_source_maps = true + +### Tracing +To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes to run your code. + +#### Cloudflare Workers + +```javascript {filename:index.js} +export default { + async fetch(request) { + const url = new URL(request.url); + + if (url.pathname === "/debug-sentry") { + await Sentry.startSpan( + { + op: "test", + name: "My First Test Transaction", + }, + async () => { + await new Promise((resolve) => setTimeout(resolve, 100)); // Wait for 100ms + throw new Error("My first Sentry error!"); + } + ); + } + + // Your existing routes and logic here... + return new Response("..."); + }, +}; +``` + +#### Cloudflare Pages + +```javascript {filename:debug-sentry.js} +export async function onRequest(context) { + await Sentry.startSpan( + { + op: "test", + name: "My First Test Transaction", + }, + async () => { + await new Promise((resolve) => setTimeout(resolve, 100)); // Wait for 100ms + throw new Error("My first Sentry error!"); + } + ); +} ``` -Then run the Sentry Wizard to finish your setup: + - +### View Captured Data in Sentry -For more information on source maps or for more options to upload them, head over to our Source Maps documentation. +Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). -## Verify + -This snippet includes an intentional error, so you can test that everything is working as soon as you set it up. +## Next Steps -Verify your setup by adding the following snippet anywhere in your code and running it: +At this point, you should have integrated Sentry and should already be sending data to your Sentry project. -```javascript -setTimeout(() => { - throw new Error(); -}); -``` +Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: - +- Learn how to [manually capture errors](/platforms/javascript/guides/cloudflare/usage/) +- Continue to [customize your configuration](/platforms/javascript/guides/cloudflare/configuration/) +- Make use of [Cloudflare-specific features](/platforms/javascript/guides/cloudflare/features) +- Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts -Learn more about manually capturing an error or message in our Usage documentation. + - +- Check out setup instructions for popular [frameworks on Cloudflare](/platforms/javascript/guides/cloudflare/frameworks/) +- Find various support topics in troubleshooting +- [Get support](https://sentry.zendesk.com/hc/en-us/) -To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and select your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. + diff --git a/platform-includes/getting-started-config/javascript.cloudflare.mdx b/platform-includes/getting-started-config/javascript.cloudflare.mdx index be26f55199d83..4face285b2492 100644 --- a/platform-includes/getting-started-config/javascript.cloudflare.mdx +++ b/platform-includes/getting-started-config/javascript.cloudflare.mdx @@ -1,6 +1,4 @@ -Configuration should happen as early as possible in your application's lifecycle. - -To use the SDK, you'll need to set either the `nodejs_compat` or `nodejs_als` compatibility flags in your `wrangler.jsonc` / `wrangler.toml` config. This is because the SDK needs access to the `AsyncLocalStorage` API to work correctly. +Since the SDK needs access to the `AsyncLocalStorage` API, you need to set either the `nodejs_compat` or `nodejs_als` compatibility flags in your `wrangler.(jsonc|toml)` configuration file: ```jsonc {tabTitle:JSON} {filename:wrangler.jsonc} { @@ -16,13 +14,13 @@ compatibility_flags = ["nodejs_als"] # compatibility_flags = ["nodejs_compat"] ``` -You will also want to add the `CF_VERSION_METADATA` binding: +Additionally, add the `CF_VERSION_METADATA` binding in the same file: ```jsonc {tabTitle:JSON} {filename:wrangler.jsonc} { // ... "version_metadata": { - "binding": "CF_VERSION_METADATA" + "binding": "CF_VERSION_METADATA", }, } ``` diff --git a/platform-includes/getting-started-config/javascript.cloudflare.workers.mdx b/platform-includes/getting-started-config/javascript.cloudflare.workers.mdx index 76e40c9f14fd5..c64d5c4571821 100644 --- a/platform-includes/getting-started-config/javascript.cloudflare.workers.mdx +++ b/platform-includes/getting-started-config/javascript.cloudflare.workers.mdx @@ -1,5 +1,4 @@ -Wrap your worker handler with the `withSentry` function. This will initialize the SDK and hook into the -environment. Note that you can turn off almost all side effects using the respective options. +Wrap your worker handler with the `withSentry` function, for example, in your `index.ts` file, to initialize the Sentry SDK and hook into the environment: ```typescript {filename:index.ts} import { Hono, HTTPException } from "hono"; @@ -17,17 +16,16 @@ export default Sentry.withSentry( // Adds request headers and IP for users, for more info visit: // https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#sendDefaultPii sendDefaultPii: true, - // ___PRODUCT_OPTION_START___ logs // Enable logs to be sent to Sentry enableLogs: true, // ___PRODUCT_OPTION_END___ logs - // ___PRODUCT_OPTION_START___ performance + // Set tracesSampleRate to 1.0 to capture 100% of spans for tracing. // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate + https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#tracesSampleRate tracesSampleRate: 1.0, // ___PRODUCT_OPTION_END___ performance }; diff --git a/platform-includes/getting-started-features-expandable/javascript.cloudflare.mdx b/platform-includes/getting-started-features-expandable/javascript.cloudflare.mdx new file mode 100644 index 0000000000000..24c6ca4523b0b --- /dev/null +++ b/platform-includes/getting-started-features-expandable/javascript.cloudflare.mdx @@ -0,0 +1,13 @@ + + +- [**Issues**](/product/issues) (always enabled): Sentry's core error monitoring product that automatically reports errors, + uncaught exceptions, and unhandled rejections. If you have something that + looks like an exception, Sentry can capture it. +- [**Tracing**](/product/tracing): Track software performance while seeing the + impact of errors across multiple systems. For example, distributed tracing + allows you to follow a request from the frontend to the backend and back. +- [**Logs**](/product/explore/logs): Centralize and analyze your application logs to + correlate them with errors and performance issues. Search, filter, and + visualize log data to understand what's happening in your applications. + + diff --git a/platform-includes/getting-started-verify-locate-data/javascript.cloudflare.mdx b/platform-includes/getting-started-verify-locate-data/javascript.cloudflare.mdx new file mode 100644 index 0000000000000..2aeda41f6656d --- /dev/null +++ b/platform-includes/getting-started-verify-locate-data/javascript.cloudflare.mdx @@ -0,0 +1,7 @@ + + +1. Open the [**Issues**](https://sentry.io/issues) page and select an error from the issues list to view the full details and context of this error. For more details, see this [interactive walkthrough](/product/sentry-basics/integrate-frontend/generate-first-error/#ui-walkthrough). +2. Open the [**Traces**](https://sentry.io/explore/traces) page and select a trace to reveal more information about each span, its duration, and any errors. For an interactive UI walkthrough, click [here](/product/sentry-basics/distributed-tracing/generate-first-error/#ui-walkthrough). +3. Open the [**Logs**](https://sentry.io/explore/logs) page and filter by service, environment, or search keywords to view log entries from your application. For an interactive UI walkthrough, click [here](/product/explore/logs/#overview). + +