sentry-cloudflare-sdk

Full Sentry SDK setup for Cloudflare Workers and Pages. Use when asked to "add Sentry to Cloudflare Workers", "install @sentry/cloudflare", or configure error monitoring, tracing, logging, crons, or AI monitoring for Cloudflare Workers, Pages, Durable Objects, Queues, Workflows, or Hono on Cloudflare.

234stars29forksUpdated 7/7/2026

Developer Tools #sdk-setup #observability #sentry #cloudflare #error-monitoring

Security Assessment

Low Risk(85/100)

Detected risks:

Agent-reviewed override(False positive: 'exec(' is Cloudflare D1/Durable-Objects SQL execution (this.ctx.storage.sql.exec(), env.DB.exec()), not code exec; 'crontab' is Sentry's cron-monitoring feature; '.env' is SDK config. Legitimate Sentry Cloudflare Workers SDK skill.)

Security Score85/100

About sentry-cloudflare-sdk

Sentry Cloudflare SDK is an opinionated setup wizard for adding the @sentry/cloudflare SDK to Cloudflare Workers and Pages projects. Rather than dumping boilerplate, it scans the project first and then leads with a concrete recommendation, guiding the developer through error monitoring, tracing, logging, crons, and AI monitoring across the full range of Cloudflare primitives: Workers, Pages, Durable Objects, Queues, Workflows, D1, and the Hono framework.

The workflow runs in three phases. In Detect, it runs a set of shell commands to understand the project: whether it is Workers or Pages, whether @sentry/cloudflare is already installed, which bindings exist (Durable Objects, D1, Queues, Workflows, cron triggers), whether the required compatibility flag is set, and whether AI/LLM or logging libraries are present. In Recommend, it proposes a concrete feature set, treating Error Monitoring and Tracing as a non-negotiable baseline while recommending Logging, Crons, D1 instrumentation, Durable Objects, Workflows, and AI Monitoring conditionally based on what was detected. In Guide, it walks through setup: optionally running the source-maps wizard for readable production stack traces, then the manual SDK setup.

Use it when asked to add Sentry to a Cloudflare project or to configure any of these monitoring features. The guide is specific about Cloudflare's requirements and APIs: the SDK needs AsyncLocalStorage, so a nodejs_als or nodejs_compat compatibility flag must be set; Workers handlers are wrapped with withSentry, which auto-instruments fetch, scheduled, queue, email, and tail handlers; Pages use sentryPagesPlugin; Durable Objects use instrumentDurableObjectWithSentry; Workflows use instrumentWorkflowWithSentry; D1 bindings are auto-instrumented; and Hono has a dedicated standalone package. AI monitoring integrations cover the Vercel AI SDK, OpenAI, Anthropic, and LangChain. It notes the SDK version its APIs reflect and advises verifying against the current Sentry documentation before implementing.

FAQ

What package does it install?

The @sentry/cloudflare SDK, installed with npm install @sentry/cloudflare. For Hono projects it recommends the standalone @sentry/hono package for a cleaner integration.

What compatibility flag is required?

The SDK needs AsyncLocalStorage, so you must add either nodejs_als or nodejs_compat to your Wrangler config's compatibility_flags. nodejs_als is lighter and only enables AsyncLocalStorage.

How do you instrument a Workers handler?

Wrap your handler with Sentry.withSentry, which automatically instruments the fetch, scheduled, queue, email, and tail handlers. The first argument is a callback that receives env for reading secrets like the DSN.

Does it support Durable Objects, D1, and Workflows?

Yes. Durable Objects use instrumentDurableObjectWithSentry, Workflows use instrumentWorkflowWithSentry, and D1 bindings are auto-instrumented by withSentry, with query spans and breadcrumbs.

Which features does it recommend by default?

Error Monitoring and Tracing are always recommended as the baseline. Logging, Crons, D1 instrumentation, Durable Objects, Workflows, and AI Monitoring are recommended conditionally based on what the project scan detects.