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
• Hono
• Hydrogen
• Next.js
• Nuxt
• Remix
• SvelteKit

Prerequisites

You need:

• A Sentry account and project
• Your application up and running

Step 1: Install

Choose the features you want to configure, and this guide will show you how:

Install the Sentry SDK

Run the command for your preferred package manager to add the Sentry SDK to your application:

npm install @sentry/cloudflare --save

Step 2: Configure

The main Sentry configuration should happen as early as possible in your app's lifecycle.

Wrangler Configuration

Since the SDK needs access to the AsyncLocalStorage API, you need to set the nodejs_compat compatibility flag in your wrangler.(jsonc|toml) configuration file:

{
  "compatibility_flags": ["nodejs_compat"],
}

Release Configuration (Optional)

If you don't set the release option manually, the SDK automatically detects it from these sources (in order of priority):

1. The SENTRY_RELEASE environment variable
2. The CF_VERSION_METADATA.id binding (if configured)

To enable automatic release detection via Cloudflare's version metadata, add the CF_VERSION_METADATA binding in your wrangler configuration. This provides access to the Cloudflare version metadata:

Sentry.withSentry(
  (env) => ({
    dsn: "___PUBLIC_DSN___",
    release: env.CF_VERSION_METADATA?.id,
  }),
  // ...
);

{
  // ...
  "version_metadata": {
    "binding": "CF_VERSION_METADATA"
  }
}

Setup for Cloudflare Workers

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:

import * as Sentry from "@sentry/cloudflare";

export default Sentry.withSentry(
  (env: Env) => ({
    dsn: "___PUBLIC_DSN___",

    // 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/guides/cloudflare/configuration/options/#tracesSampleRate
    tracesSampleRate: 1.0,
    // ___PRODUCT_OPTION_END___ performance
  }),
  {
    async fetch(request, env, ctx) {
      // Your worker logic here
      return new Response("Hello World!");
    },
  },
);

Setup for Cloudflare Pages

To use the Sentry SDK, add the sentryPagesPlugin as middleware to your Cloudflare Pages application.

Create a _middleware.js file in your functions directory (Cloudflare Pages middleware). Create the directory in the root of your project if it doesn't already exist, then create the file and import and initialize the Sentry Cloudflare SDK:

import * as Sentry from "@sentry/cloudflare";

export const onRequest = [
  // Make sure Sentry is the first middleware
  Sentry.sentryPagesPlugin((context) => ({
    dsn: "___PUBLIC_DSN___",

    // 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/guides/cloudflare/configuration/options/#tracesSampleRate
    tracesSampleRate: 1.0,
    // ___PRODUCT_OPTION_END___ performance
  })),
  // Add more middlewares here
];

// hooks.server.js
import * as Sentry from "@sentry/cloudflare";

export const handle = ({ event, resolve }) => {
  const requestHandlerOptions = {
    options: {
      dsn: event.platform.env.SENTRY_DSN,
      tracesSampleRate: 1.0,
    },
    request: event.request,
    context: event.platform.ctx,
  };
  return Sentry.wrapRequestHandler(requestHandlerOptions, () =>
    resolve(event),
  );
};

Step 3: Add Readable Stack Traces With Source Maps (Optional)

The stack traces in your Sentry errors probably won't look like your actual code without unminifying them. To fix this, upload your source maps to Sentry.

First, set the upload_source_maps option to true in your wrangler.(jsonc|toml) config file to enable source map uploading:

{
  "upload_source_maps": true,
}

Next, run the Sentry Wizard to finish your setup:

npx @sentry/wizard@latest -i sourcemaps

Step 4: Verify Your Setup

Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.

Issues

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:

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:

export async function onRequest(context) {
  throw new Error("My first Sentry error!");
}

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("...");
  },
};

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!");
    },
  );
}

View Captured Data in Sentry

Now, head over to your project on Sentry.io to view the collected data (it takes a couple of moments for the data to appear).

Known Limitations

Span Durations

Server-side spans will display 0ms for their durations. In the Cloudflare Workers runtime, performance.now() and Date.now() only advance after I/O occurs. CPU-bound operations will show zero duration. This is a security measure Cloudflare implements to mitigate against timing attacks.

This is expected behavior in the Cloudflare Workers environment and affects all frameworks deployed to Cloudflare Workers, including Next.js, Astro, Remix, and others.

Next Steps

At this point, you should have integrated Sentry and should already be sending data to your Sentry project.

Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are:

• Explore practical guides on what to monitor, log, track, and investigate after setup
• Learn how to manually capture errors
• Continue to customize your configuration
• Make use of Cloudflare-specific features
• Get familiar with Sentry's product features like tracing, insights, and alerts