sentry-cloudflare-sdk

> [All Skills](../../SKILL_TREE.md) > [SDK Setup](../sentry-sdk-setup/SKILL.md) > Cloudflare SDK # Sentry Cloudflare SDK Opinionated wizard that scans your Cloudflare project and guides you through complete Sentry setup for Workers, Pages, Durable Objects, Queues, Workflows, and Hono. ## Invoke This Skill When - User asks to "add Sentry to Cloudflare Workers" or "set up Sentry" in a Cloudflare project - User wants to install or configure `@sentry/cloudflare` - User wants error monitoring, tracing, logging, crons, or AI monitoring for Cloudflare Workers or Pages - User asks about `withSentry`, `sentryPagesPlugin`, `instrumentDurableObjectWithSentry`, or `instrumentD1WithSentry` - User wants to monitor Durable Objects, Queues, Workflows, Scheduled handlers, or Email handlers on Cloudflare > **Note:** SDK versions and APIs below reflect current Sentry docs at time of writing (`@sentry/cloudflare` v10.61.0). > Always verify against [docs.sentry.io/platforms/javascript/guides/cloudflare/](https://docs.sentry.io/platforms/javascript/guides/cloudflare/) before implementing. --- ## Phase 1: Detect Run these commands to understand the project before making any recommendations: ```bash # Detect Cloudflare project ls wrangler.toml wrangler.jsonc wrangler.json 2>/dev/null # Detect existing Sentry cat package.json 2>/dev/null | grep -E '"@sentry/' # Detect project type (Workers vs Pages) ls functions/ functions/_middleware.js functions/_middleware.ts 2>/dev/null && echo "Pages detected" cat wrangler.toml 2>/dev/null | grep -E 'main|pages_build_output_dir' # Detect framework cat package.json 2>/dev/null | grep -E '"hono"|"remix"|"astro"|"svelte"' # Detect Durable Objects cat wrangler.toml 2>/dev/null | grep -i 'durable_objects' # Detect D1 databases cat wrangler.toml 2>/dev/null | grep -i 'd1_databases' # Detect Queues cat wrangler.toml 2>/dev/null | grep -i 'queues' # Detect Workflows cat wrangler.toml 2>/dev/null | grep -i 'workflows' # Detect Scheduled handlers (cron triggers) cat wrangler.toml 2>/dev/null | grep -i 'crons\|triggers' # Detect compatibility flags cat wrangler.toml 2>/dev/null | grep -i 'compatibility_flags' cat wrangler.jsonc 2>/dev/null | grep -i 'compatibility_flags' # Detect AI/LLM libraries cat package.json 2>/dev/null | grep -E '"openai"|"@anthropic-ai"|"ai"|"@google/generative-ai"|"@langchain"' # Detect logging libraries cat package.json 2>/dev/null | grep -E '"pino"|"winston"' # Check for companion frontend ls frontend/ web/ client/ 2>/dev/null cat package.json 2>/dev/null | grep -E '"react"|"vue"|"svelte"|"next"' ``` **What to determine:** | Question | Impact | |----------|--------| | Workers or Pages? | Determines wrapper: `withSentry` vs `sentryPagesPlugin` | | Hono framework? | Recommend standalone `@sentry/hono` package (v10.55.0+) for cleaner integration | | `@sentry/cloudflare` already installed? | Skip install, go to feature config | | Durable Objects configured? | Recommend `instrumentDurableObjectWithSentry` | | D1 databases bound? | `withSentry` auto-instruments D1 bindings (v10.57.0+); no manual wrapping needed | | Queues configured? | `withSentry` auto-instruments queue handlers | | Workflows configured? | Recommend `instrumentWorkflowWithSentry` | | Cron triggers configured? | `withSentry` auto-instruments scheduled handlers; recommend Crons monitoring | | `nodejs_als` or `nodejs_compat` flag set? | **Required** — SDK needs `AsyncLocalStorage` | | AI/LLM libraries? | Recommend AI Monitoring integrations | | Companion frontend? | Trigger Phase 4 cross-link | --- ## Phase 2: Recommend Present a concrete recommendation based on what you found. Don't ask open-ended questions — lead with a proposal: **Recommended (core coverage):** - ✅ **Error Monitoring** — always; captures unhandled exceptions in fetch, scheduled, queue, email, and Durable Object handlers - ✅ **Tracing** — automatic HTTP request spans, outbound fetch tracing, D1 query spans **Optional (enhanced observability):** - ⚡ **Logging** — structured logs via `Sentry.logger.*`; recommend when log search is needed - ⚡ **Crons** — detect missed/failed scheduled jobs; recommend when cron triggers are configured - ⚡ **D1 Instrumentation** — automatic query spans and breadcrumbs; recommend when D1 is bound - ⚡ **Durable Objects** — automatic error capture and spans for DO methods; recommend when DOs are configured - ⚡ **Workflows** — automatic span creation for workflow steps; recommend when Workflows are configured - ⚡ **AI Monitoring** — Vercel AI SDK, OpenAI, Anthropic, LangChain; recommend when AI libraries detected **Recommendation logic:** | Feature | Recommend when... | |---------|------------------| | Error Monitoring | **Always** — non-negotiable baseline | | Tracing | **Always** — HTTP request tracing and outbound fetch are high-value | | Logging | App needs structured log search or log-to-trace correlation | | Crons | Cron triggers configured in `wrangler.toml` | | D1 Instrumentation | D1 database bindings present | | Durable Objects | Durable Object bindings configured | | Workflows | Workflow bindings configured | | AI Monitoring | App uses Vercel AI SDK, OpenAI, Anthropic, or LangChain | | Metrics | App needs custom counters, gauges, or distributions | Propose: *"I recommend setting up Error Monitoring + Tracing. Want me to also add D1 instrumentation and Crons monitoring?"* --- ## Phase 3: Guide ### Option 1: Source Maps Wizard > **You need to run this yourself** — the wizard opens a browser for login and requires interactive input that the agent can't handle. Copy-paste into your terminal: > > ``` > npx @sentry/wizard@latest -i sourcemaps > ``` > > This sets up source map uploading so your production stack traces show readable code. It does **not** set up the SDK initialization — you still need to follow Option 2 below for the actual SDK setup. > > **Once it finishes, continue with Option 2 for SDK setup.** > **Note:** Unlike framework SDKs (Next.js, SvelteKit), there is no Cloudflare-specific wizard integration. The `sourcemaps` wizard only handles source map upload configuration. --- ### Option 2: Manual Setup #### Prerequisites: Compatibility Flags The SDK requires `AsyncLocalStorage`. Add **one** of these flags to your Wrangler config: **wrangler.toml:** ```toml compatibility_flags = ["nodejs_als"] # or: compatibility_flags = ["nodejs_compat"] ``` **wrangler.jsonc:** ```jsonc { "compatibility_flags": ["nodejs_als"] } ``` > `nodejs_als` is lighter — it only enables `AsyncLocalStorage`. Use `nodejs_compat` if your code also needs other Node.js APIs. #### Install ```bash npm install @sentry/cloudflare ``` #### Workers Setup Wrap your handler with `withSentry`. This automatically instruments `fetch`, `scheduled`, `queue`, `email`, and `tail` handlers: ```typescript import * as Sentry from "@sentry/cloudflare"; export default Sentry.withSentry( (env: Env) => ({ dsn: env.SENTRY_DSN, tracesSampleRate: 1.0, enableLogs: true, dataCollection: { // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit: // https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#dataCollection // userInfo: false, // httpBodies: [], }, }), { async fetch(request, env, ctx) { return new Response("Hello World!"); }, } satisfies ExportedHandler<Env>, ); ``` **Key points:** - The first argument is a callback that receives `env` — use this to read secrets like `SENTRY_DSN` - The SDK reads DSN, environment, release, debug, tunnel, and traces sample rate from `env` automatically (see [Environment Variables](#environment-variables)) - `withSentry` wraps all exported handlers — you do not need separate wrappers for `scheduled`, `queue`, etc. #### Pages Setup Use `sentryPagesPlugin` as middleware: ```typescript // functions/_middleware.ts import * as Sentry from "@sentry/cloudflare"; export const onRequest = Sentry.sentryPagesPlugin((context) => ({ dsn: context.env.SENTRY_DSN, tracesSampleRate: 1.0, enableLogs: true, dataCollection: { // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit: // https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#dataCollection // userInfo: false, // httpBodies: [], }, })); ``` **Chaining multiple middlewares:** ```typescript import * as Sentry from "@sentry/cloudflare"; export const onRequest = [ // Sentry must be first Sentry.sentryPagesPlugin((context) => ({ dsn: context.env.SENTRY_DSN, tracesSampleRate: 1.0, })), // Add more middlewares here ]; ``` **Using `wrapRequestHandler` directly** (for frameworks like SvelteKit on Cloudflare Pages): ```typescript import * as Sentry from "@sentry/cloudflare"; export const handle = ({ event, resolve }) => { return Sentry.wrapRequestHandler( { options: { dsn: event.platform.env.SENTRY_DSN, tracesSampleRate: 1.0, }, request: event.request, context: event.platform.ctx, }, () => resolve(event), ); }; ``` #### Hono on Cloudflare Workers **Recommended (v10.55.0+):** Use the standalone `@sentry/hono` package for Hono apps: ```bash npm install @sentry/hono @sentry/cloudflare ``` The `@sentry/cloudflare` package is a peer dependency and must stay in sync with `@sentry/hono`. ```typescript import { Hono } from "hono"; import { sentry } from "@sentry/hono/cloudflare"; type Bindings = { SENTRY_DSN: string }; const app = new Hono<{ Bindings: Bindings }>(); // Initialize Sentry middleware as early as possible app.use( sentry(app, (env) => ({ dsn: env.SENTRY_DSN, tracesSampleRate: 1.0, })), ); app.get("/", (ctx) => ctx.json({ message: "Hello" })); app.get("/error", () => { throw new Error("Test error"); }); export default app; ``` The `sentry()` middleware automatically captures errors and creates transaction spans with route patterns. **Legacy approach (deprecated):** Using `@sentry/cloudflare` with `withSentry` still works, but `honoIntegration` is deprecated: ```typescript import { Hono } from "hono"; import * as Sentry from "@sentry/cloudflare"; const app = new Hono(); app.get("/", (ctx) => ctx.json({ message: "Hello" })); export default Sentry.withSentry( (env: Env) => ({ dsn: env.SENTRY_DSN, tracesSampleRate: 1.0, }), app, ); ``` #### Set Up the SENTRY_DSN Secret Store your DSN as a Cloudflare secret — do not hardcode it: ```bash # Local development: add to .dev.vars echo 'SENTRY_DSN="https://examplePublicKey@o0.ingest.sentry.io/0"' >> .dev.vars # Production: set as a secret npx wrangler secret put SENTRY_DSN ``` Add the binding to your `Env` type: ```typescript interface Env { SENTRY_DSN: string; // ... other bindings } ``` #### Source Maps Setup Source maps make production stack traces readable. Most Cloudflare projects build with Vite via Wrangler — wire the Sentry Vite plugin so maps upload on build: ```bash npm install @sentry/vite-plugin --save-dev ``` ```typescript import { defineConfig } from "vite"; import { sentryVitePlugin } from "@sentry/vite-plugin"; export default defineConfig({ build: { sourcemap: true, }, plugins: [ sentryVitePlugin({ org: "___ORG_SLUG___", project: "___PROJECT_SLUG___", authToken: process.env.SENTRY_AUTH_TOKEN, }), ], }); ``` `SENTRY_AUTH_TOKEN` is a build-time secret. For creating the token and wiring it into CI, see [`sentry-source-maps`](../sentry-source-maps/SKILL.md). The `npx @sentry/wizard@latest -i sourcemaps` shortcut noted above automates this setup. --- ### Automatic Release Detection The SDK can automatically detect the release version via Cloudflare's version metadata binding: **wrangler.toml:** ```toml [version_metadata] binding = "CF_VERSION_METADATA" ``` Release priority (highest to lowest): 1. `release` option passed to `Sentry.init()` 2. `SENTRY_RELEASE` environment variable 3. `CF_VERSION_METADATA.id` binding --- ### For Each Agreed Feature Load the corresponding reference file and follow its steps: | Feature | Reference file | Load when... |