diff --git a/docs/platforms/javascript/common/agent-tracing/index.mdx b/docs/platforms/javascript/common/agent-tracing/index.mdx index 79825ac2ce7f12..a0a36316d50306 100644 --- a/docs/platforms/javascript/common/agent-tracing/index.mdx +++ b/docs/platforms/javascript/common/agent-tracing/index.mdx @@ -207,7 +207,7 @@ export default Sentry.withSentry( ); ``` -On the default CF entrypoint, control Vercel AI I/O with `experimental_telemetry` per call (or integration-level `record*` via `nodejs_compat`). See each integration page. +On Cloudflare, control Vercel AI I/O with integration-level `record*` options or with `experimental_telemetry` per call. See each integration page. diff --git a/docs/platforms/javascript/common/agent-tracing/vercelai.mdx b/docs/platforms/javascript/common/agent-tracing/vercelai.mdx index 83cf7254934179..664e3d0e9becaf 100644 --- a/docs/platforms/javascript/common/agent-tracing/vercelai.mdx +++ b/docs/platforms/javascript/common/agent-tracing/vercelai.mdx @@ -63,16 +63,9 @@ Everything else depends on which runtime you're in: -Cloudflare Workers can't load OpenTelemetry instrumentation. On both entrypoints, Sentry reads the spans the AI SDK emits on its own instead of patching your call sites, so you must pass `experimental_telemetry` on every call. The `@sentry/cloudflare/nodejs_compat` entrypoint adds the Node.js APIs the AI SDK v7 telemetry channel needs. +Cloudflare Workers can't load OpenTelemetry instrumentation. Sentry reads the spans the AI SDK emits on its own instead of patching your call sites, so you must pass `experimental_telemetry` on every call. -Your entrypoint decides the rest: - -| | `@sentry/cloudflare` | `@sentry/cloudflare/nodejs_compat` | -| ---------------------------- | -------------------- | ---------------------------------- | -| Record inputs and outputs | Per call only | Integration or per call | -| AI SDK v7 | Not supported | Supported | -| Minimum Sentry SDK | `10.6.0` | `10.64.0` | -| Minimum `compatibility_date` | `2024-09-23` | `2026-02-19` | +The AI SDK v7 telemetry channel needs Node.js APIs, which the Worker gets from the `nodejs_compat` compatibility flag. Set a `compatibility_date` of `2026-02-19` or later to record AI SDK v7 spans. @@ -146,10 +139,10 @@ Deno can't load OpenTelemetry instrumentation, so Sentry can't patch your call s ### AI SDK v7 -Use the `@sentry/cloudflare/nodejs_compat` entrypoint and enable the Wrangler `nodejs_compat` flag: +Enable the Wrangler `nodejs_compat` flag and set a `compatibility_date` of `2026-02-19` or later: ```javascript -import * as Sentry from "@sentry/cloudflare/nodejs_compat"; +import * as Sentry from "@sentry/cloudflare"; export default Sentry.withSentry( (env) => ({ @@ -199,7 +192,7 @@ export default Sentry.withSentry( ); ``` -On both entrypoints, adding the integration is not enough on its own. Cloudflare can't patch your call sites, so you must also pass `experimental_telemetry` on every call — including on `nodejs_compat`. See [Turn on telemetry](#turn-on-telemetry). +Adding the integration is not enough on its own. Cloudflare can't patch your call sites, so you must also pass `experimental_telemetry` on every call. See [Turn on telemetry](#turn-on-telemetry). @@ -286,12 +279,12 @@ const result = await generateText({ -### `@sentry/cloudflare/nodejs_compat` +### On the integration Set the options on the integration to cover every call: ```javascript -import * as Sentry from "@sentry/cloudflare/nodejs_compat"; +import * as Sentry from "@sentry/cloudflare"; export default Sentry.withSentry( (env) => ({ @@ -312,13 +305,9 @@ export default Sentry.withSentry( ); ``` -### `@sentry/cloudflare` - - - -The default entrypoint ignores `recordInputs` and `recordOutputs` on the integration. It accepts no error and logs no warning — your prompts are simply missing. Set both per call. +### Per call - +Or set them on a single call, which overrides the integration for that call: ```javascript const result = await generateText({ @@ -470,7 +459,7 @@ Pass these to `Sentry.vercelAIIntegration()`. The Edge runtime accepts `enableTr -Pass these to `Sentry.vercelAIIntegration()`. The default `@sentry/cloudflare` entrypoint accepts `enableTruncation` only; `nodejs_compat` also accepts `recordInputs` and `recordOutputs`. Neither has module detection to override, so `force` does not apply. +Pass these to `Sentry.vercelAIIntegration()`. Cloudflare accepts `enableTruncation`, `recordInputs` and `recordOutputs`. It has no module detection to override, so `force` does not apply. @@ -603,8 +592,8 @@ Plus `generate()` and `stream()` on [`ToolLoopAgent`](#toolloopagent). -- Sentry SDK: `10.6.0`+ with `@sentry/cloudflare` -- Sentry SDK: `10.64.0`+ with `@sentry/cloudflare/nodejs_compat`, required for `ai` v7 +- Sentry SDK: `10.6.0`+ +- `compatibility_date`: `2026-02-19`+, required for `ai` v7 diff --git a/docs/platforms/javascript/common/mcp-monitoring/index.mdx b/docs/platforms/javascript/common/mcp-monitoring/index.mdx index 626f8ead3a059e..b969ab2cd9e7f4 100644 --- a/docs/platforms/javascript/common/mcp-monitoring/index.mdx +++ b/docs/platforms/javascript/common/mcp-monitoring/index.mdx @@ -57,30 +57,11 @@ These options override the corresponding `dataCollection.genAI.inputs` and `data ## Preserve MCP Spans After the Response -Cloudflare MCP work can finish after the Worker returns an HTTP response, including work kept alive with `waitUntil()`. With the static trace lifecycle, Sentry snapshots the request transaction when the response is returned, so MCP spans that finish later may be missing. +Cloudflare MCP work can finish after the Worker returns an HTTP response, including work kept alive with `waitUntil()`. The SDK streams spans by default, sending each sampled span as it finishes, so this work is captured without extra configuration. You still need to wrap the MCP server as shown above. -Set `traceLifecycle: "stream"` so the SDK can send each sampled span when it finishes. This changes how spans are delivered; you still need to wrap the MCP server as shown above. Span streaming on Cloudflare requires `@sentry/cloudflare` version `10.49.0` or newer. +If you set `traceLifecycle: "static"`, the SDK snapshots the request transaction when the response is returned and MCP spans that finish later are dropped. Remove the option to get them back. -```javascript {filename:index.js} -import * as Sentry from "@sentry/cloudflare"; - -const worker = { - async fetch(request, env, ctx) { - return handleMcpRequest(request, env, ctx); - }, -}; - -export default Sentry.withSentry( - (env) => ({ - dsn: env.SENTRY_DSN, - tracesSampleRate: 1.0, - traceLifecycle: "stream", - }), - worker -); -``` - -Stream mode sends span records instead of assembling one transaction event with embedded spans. `beforeSendTransaction` and `ignoreTransactions` don't apply to streamed spans. See Streamed Spans for the `beforeSendSpan` and `ignoreSpans` configuration. +Streaming sends span records instead of assembling one transaction event with embedded spans. `beforeSendTransaction` and `ignoreTransactions` don't apply to streamed spans. See Streamed Spans for the `beforeSendSpan` and `ignoreSpans` configuration. If you use `McpAgent`, wrap the `McpServer` returned by its `server` getter, and wrap the Agent class separately with `instrumentAgentWithSentry` to preserve request and RPC context. Agent instrumentation, MCP server wrapping, and span streaming solve different parts of the setup; none replaces the others. See Agents SDK. @@ -90,7 +71,7 @@ If you use `McpAgent`, wrap the `McpServer` returned by its `server` getter, and ## Hono on Cloudflare Workers -If your Hono app runs on Cloudflare Workers, MCP work can finish after the Worker returns its response. Set `traceLifecycle: "stream"` in the Hono Sentry middleware so each sampled span is sent when it finishes: +If your Hono app runs on Cloudflare Workers, MCP work can finish after the Worker returns its response. The middleware streams spans by default, sending each sampled span as it finishes, so that work is captured on its own: ```javascript {filename:index.js} import { sentry } from "@sentry/hono/cloudflare"; @@ -99,12 +80,11 @@ app.use( sentry(app, { dsn: "___PUBLIC_DSN___", tracesSampleRate: 1.0, - traceLifecycle: "stream", }) ); ``` -This changes how spans are delivered; it doesn't replace `wrapMcpServerWithSentry`. Stream mode requires `@sentry/hono` and `@sentry/cloudflare` version `10.49.0` or newer. See Streamed Spans for configuration and filtering differences. +Setting `traceLifecycle: "static"` drops the spans that finish after the response. Streaming changes how spans are delivered; it doesn't replace `wrapMcpServerWithSentry`. See Streamed Spans for configuration and filtering differences. diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index 813c80090facc4..bac982c83e6aee 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -695,9 +695,23 @@ shamefully-hoist=true Cloudflare's [`waitUntil()`](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil) lets work continue after the Worker returns a response. Whether those spans arrive depends on your trace lifecycle. - On the static lifecycle, which is the default, the SDK snapshots the request transaction when the response is returned, so anything finishing later is dropped. Streaming sends each sampled span as it finishes instead, which captures deferred work. + On the static lifecycle, the SDK snapshots the request transaction when the response is returned, so anything finishing later is dropped. Streaming sends each sampled span as it finishes instead, which captures deferred work. - Set `traceLifecycle: "stream"`, which needs `@sentry/cloudflare` version `10.49.0` or newer: + From version `11.0.0`, the SDK streams by default, so this is only a problem if something set the static lifecycle explicitly. Remove it: + + ```javascript {filename:index.js} + export default Sentry.withSentry( + (env) => ({ + dsn: env.SENTRY_DSN, + tracesSampleRate: 1.0, + // Remove this to stream spans as they finish + // traceLifecycle: "static", + }), + worker + ); + ``` + + On version `10.x` the static lifecycle is the default, so missing deferred spans are expected until you opt in. Set `traceLifecycle: "stream"`, which needs `@sentry/cloudflare` version `10.49.0` or newer: ```javascript {filename:index.js} export default Sentry.withSentry( @@ -710,7 +724,7 @@ shamefully-hoist=true ); ``` - If you need to keep the static lifecycle, wrap the background work in its own span with `forceTransaction: true`, which records it as a separate transaction. `forceTransaction` isn't available in stream mode. + If you need the static lifecycle for another reason, wrap the background work in its own span with `forceTransaction: true`, which records it as a separate transaction. `forceTransaction` has no effect while streaming. ```javascript {filename:index.js} ctx.waitUntil( diff --git a/docs/platforms/javascript/guides/cloudflare/agent-tracing/agents-sdk.mdx b/docs/platforms/javascript/guides/cloudflare/agent-tracing/agents-sdk.mdx index d74c495d476091..50a6f450955173 100644 --- a/docs/platforms/javascript/guides/cloudflare/agent-tracing/agents-sdk.mdx +++ b/docs/platforms/javascript/guides/cloudflare/agent-tracing/agents-sdk.mdx @@ -36,7 +36,7 @@ export const MyAgent = Sentry.instrumentAgentWithSentry( The Worker that calls the agent names its binding in `rpcTracePropagationBindings`. See RPC Trace Propagation. -`instrumentAgentWithSentry` works with `Agent` from `agents`, `AIChatAgent` from `@cloudflare/ai-chat`, and `McpAgent` from `agents/mcp`. When you build with the Sentry Cloudflare Vite plugin's `autoInstrumentation`, the plugin detects and wraps Agent classes automatically. +`instrumentAgentWithSentry` works with `Agent` from `agents`, `AIChatAgent` from `@cloudflare/ai-chat`, and `McpAgent` from `agents/mcp`. When you build with the Sentry Cloudflare Vite plugin, it detects and wraps Agent classes for you, so you only need this wrapper on a plain Wrangler build. ## Conversation IDs diff --git a/docs/platforms/javascript/guides/cloudflare/configuration/integrations/hono.mdx b/docs/platforms/javascript/guides/cloudflare/configuration/integrations/hono.mdx deleted file mode 100644 index adba0ecd9b05b7..00000000000000 --- a/docs/platforms/javascript/guides/cloudflare/configuration/integrations/hono.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Hono -description: "Reports Hono errors to Sentry. (default)" ---- - -_Import name: `Sentry.honoIntegration`_ - - - -**Deprecated**: `honoIntegration` is deprecated. Use the [dedicated `@sentry/hono` SDK](/platforms/javascript/guides/hono/) instead, which supports Hono across Cloudflare Workers, Node.js, and Bun with improved performance and a simpler setup. - - - -This integration is enabled by default. If you'd like to modify your default integrations, read [this](./../#modifying-default-integrations). - -The `honoIntegration` automatically captures errors from Hono's `onError` function and sends them to Sentry. By default, the integration doesn't capture errors that have a 3xx or 4xx HTTP status code. - -## Options - -You can configure the `honoIntegration` by passing an options object to the function. - -### `shouldHandleError` - -This option allows you to provide a function that determines whether an error should be captured, giving you full control over which errors are sent to Sentry. - -The function receives the error as an argument and should return `true` if the error should be reported, and `false` otherwise. - -For example, to report all errors except for 404s, add this to the integrations array when initializing Sentry: - -```javascript -integrations: [ - honoIntegration({ - shouldHandleError(error) { - // return true // Would report all errors - - if (error instanceof HTTPException && error.status === 404) { - // Don't report 404s - return false; - } - // Report all other errors - return true; - }, - }), -] -``` diff --git a/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx b/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx index febbd812a4af15..c6f8ae2472a07d 100644 --- a/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx +++ b/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx @@ -1,22 +1,16 @@ --- title: Prisma -description: "Adds instrumentation for Prisma ORM queries on Cloudflare Workers running with Node.js compatibility." +description: "Adds instrumentation for Prisma ORM queries on Cloudflare Workers." --- - - -On Cloudflare, the `prismaIntegration` is only available through the `@sentry/cloudflare/nodejs_compat` entrypoint, which requires SDK version `10.64.0` or higher. - - - _Import name: `Sentry.prismaIntegration`_ Sentry supports tracing [Prisma ORM](https://www.prisma.io/) queries with the Prisma integration. The integration creates a span for each query and reports relevant details to Sentry. -To enable it on Cloudflare, import Sentry from the `@sentry/cloudflare/nodejs_compat` entrypoint and add the `prismaIntegration` to your `Sentry.init` call: +The integration relies on Node.js APIs, so your Worker must run with the `nodejs_compat` compatibility flag. Add the `prismaIntegration` to your `Sentry.init` call: ```javascript {3,5} -import * as Sentry from "@sentry/cloudflare/nodejs_compat"; +import * as Sentry from "@sentry/cloudflare"; Sentry.init({ tracesSampleRate: 1.0, diff --git a/docs/platforms/javascript/guides/cloudflare/features/nodejs-compat.mdx b/docs/platforms/javascript/guides/cloudflare/features/nodejs-compat.mdx deleted file mode 100644 index 79193891a005ab..00000000000000 --- a/docs/platforms/javascript/guides/cloudflare/features/nodejs-compat.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Node.js Compatibility Entrypoint -description: "Learn how the nodejs_compat entrypoint unlocks additional Node.js SDK features on Cloudflare Workers, such as Prisma instrumentation." ---- - -Cloudflare Workers can run with Node.js APIs enabled through the [`nodejs_compat` compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs/). To take advantage of this, the Cloudflare SDK ships a dedicated `@sentry/cloudflare/nodejs_compat` entrypoint that unlocks Node.js SDK features which aren't available in the default Workers runtime. - - - -The `@sentry/cloudflare/nodejs_compat` entrypoint requires SDK version `10.64.0` or higher. It will become the default entrypoint in the next major version (v11). - - - -## What It Unlocks - -The `/nodejs_compat` entrypoint enables Node.js-only integrations and features on Cloudflare, including: - -- The `prismaIntegration` for tracing Prisma ORM queries. -- Vercel AI SDK v7 support for the `vercelAIIntegration`. - -## Usage - -The entrypoint is a drop-in replacement for `@sentry/cloudflare`, so switching over only requires changing your imports: - -```javascript {tabTitle:After} -import * as Sentry from "@sentry/cloudflare/nodejs_compat"; -``` - -```javascript {tabTitle:Before} -import * as Sentry from "@sentry/cloudflare"; -``` - -To use the entrypoint, your Worker must set the `nodejs_compat` compatibility flag in your Wrangler configuration: - - -```jsonc {tabTitle:JSON} {filename:wrangler.jsonc} -{ - "compatibility_flags": ["nodejs_compat"], -} -``` - -```toml {tabTitle:Toml} {filename:wrangler.toml} -compatibility_flags = ["nodejs_compat"] -``` - - - -We recommend that you also keep `compatibility_date` and Wrangler up to date. Some instrumentation depends on Node.js APIs that Cloudflare only exposes from a given compatibility date on, and an older date can turn that instrumentation off without an error message. The Vercel AI integration, for example, needs `2026-02-19` or later. - - diff --git a/docs/platforms/javascript/guides/cloudflare/features/pages.mdx b/docs/platforms/javascript/guides/cloudflare/features/pages.mdx index 0e828df487bd24..0bd58f0ade1ef3 100644 --- a/docs/platforms/javascript/guides/cloudflare/features/pages.mdx +++ b/docs/platforms/javascript/guides/cloudflare/features/pages.mdx @@ -82,7 +82,7 @@ If you don't have access to the `onRequest` middleware API, you can use the `wra ```javascript // hooks.server.js -import * as Sentry from "@sentry/cloudflare"; +import { wrapRequestHandler } from "@sentry/cloudflare/request"; export const handle = ({ event, resolve }) => { const requestHandlerOptions = { @@ -93,7 +93,7 @@ export const handle = ({ event, resolve }) => { request: event.request, context: event.platform.ctx, }; - return Sentry.wrapRequestHandler(requestHandlerOptions, () => resolve(event)); + return wrapRequestHandler(requestHandlerOptions, () => resolve(event)); }; ``` diff --git a/docs/platforms/javascript/guides/cloudflare/index.mdx b/docs/platforms/javascript/guides/cloudflare/index.mdx index 9b14a49c51b738..478a1db799761e 100644 --- a/docs/platforms/javascript/guides/cloudflare/index.mdx +++ b/docs/platforms/javascript/guides/cloudflare/index.mdx @@ -60,12 +60,6 @@ Run the command for your preferred package manager to add the Sentry SDK to your - - -Importing Sentry from the `@sentry/cloudflare/nodejs_compat` entrypoint unlocks additional Node.js SDK features on Cloudflare. It requires SDK version `10.64.0` or higher and will become the default in the next major version. [Learn more](./features/nodejs-compat). - - - ## Configure This guide sets Sentry up through Vite, which is what we recommend for Cloudflare Workers. The plugin does the wiring at build time, so your Worker code stays untouched. @@ -82,9 +76,9 @@ Not using Vite? See the Wrangler setup -Add the Sentry plugin to your existing `vite.config.ts`, next to `cloudflare()`. Both behaviors are experimental in this version, so turn them on explicitly. +Add the Sentry plugin to your existing `vite.config.ts`, next to `cloudflare()`. It needs no options. -`autoInstrumentation` wraps your Worker entry, and any Durable Object, Workflow or Agents SDK class in your wrangler config, at build time, so you don't have to call `Sentry.withSentry()` yourself. `useDiagnosticsChannelInjection` instruments bundled dependencies such as database clients, which is the only way to trace them in the Workers runtime, where the SDK can't patch them at runtime. +The plugin wraps your Worker entry, and any Durable Object, Workflow or Agents SDK class in your wrangler config, at build time, so you don't have to call `Sentry.withSentry()` yourself. It also instruments bundled dependencies such as database clients, which is the only way to trace them in the Workers runtime, where the SDK can't patch them at runtime. To see its options, which packages it instruments, and how to opt out of either behavior, see Vite Plugin. @@ -97,15 +91,8 @@ To see its options, which packages it instruments, and how to opt out of either import { defineConfig } from "vite"; export default defineConfig({ - plugins: [ - cloudflare(), -+ sentryCloudflareVitePlugin({ -+ _experimental: { -+ autoInstrumentation: true, -+ useDiagnosticsChannelInjection: true, -+ }, -+ }), - ], +- plugins: [cloudflare()], ++ plugins: [cloudflare(), sentryCloudflareVitePlugin()], }); ``` diff --git a/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx b/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx index 85d38b7644969c..a10db9b605c16e 100644 --- a/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx +++ b/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx @@ -5,17 +5,12 @@ description: "Learn how to use the Sentry Cloudflare Vite plugin to instrument b - - The Sentry Cloudflare Vite plugin has **experimental** stability. - Configuration options and behavior may change or be removed in any release. - - The Sentry Cloudflare Vite plugin (`sentryCloudflareVitePlugin`) instruments your Worker at build time. It can: 1. **Instrument bundled dependencies**: instruments supported packages in your bundle, such as database clients and AI SDKs, giving you more traces out of the box. 2. **Auto-instrument your Worker entry**: wraps your default export with `Sentry.withSentry()`, and Durable Object, Workflow, and Agents SDK classes with the matching `instrument*WithSentry` helper at build time, so you don't need to modify your code. -Both are opt-in while the plugin is experimental. Turn them on with [`_experimental.useDiagnosticsChannelInjection`](#_experimentalusediagnosticschannelinjection) and [`_experimental.autoInstrumentation`](#_experimentalautoinstrumentation). +Both run by default. Turn either off with [`buildTimeInstrumentation`](#buildtimeinstrumentation) or [`autoInstrumentation`](#autoinstrumentation). The quick start covers adding the plugin and creating `instrument.server.ts`. This page documents what it instruments, its @@ -25,7 +20,7 @@ options, and the details that matter once it's running. The plugin reads your wrangler config (probing `wrangler.json`, `wrangler.jsonc`, and `wrangler.toml` at the Vite root, or the file set with [`wranglerConfigPath`](#wranglerconfigpath)) to find the entry point, Durable Objects, workflows, and Agents SDK classes. It wraps Agents SDK classes (`Agent`, `AIChatAgent`, `McpAgent`) with `instrumentAgentWithSentry`, which also gives them automatic conversation IDs (see Cloudflare Agents SDK). -An entry you wrapped with `withSentry` yourself is left untouched, so manual instrumentation keeps working next to the plugin. If you'd rather wrap the entry yourself, leave `_experimental.autoInstrumentation` off and follow the Wrangler setup. +An entry you wrapped with `withSentry` yourself is left untouched, so manual instrumentation keeps working next to the plugin. To keep the plugin out of your entry entirely, set [`autoInstrumentation`](#autoinstrumentation) to `false` and wrap it yourself as shown in the Wrangler setup. With auto-instrumentation, you can optionally provide Sentry options via a co-located `instrument.server.*` file (`.ts`, `.mts`, `.js`, `.mjs`, or `.cjs`) next to your Worker entry. The plugin resolves this location from `main` in your wrangler config. For example, if `main` is `src/worker/index.ts`, place the file at `src/worker/instrument.server.ts`, not at the project root. Use `defineCloudflareOptions` for full type-checking: @@ -40,20 +35,7 @@ export default defineCloudflareOptions((env) => ({ If no `instrument.server.*` file exists, the SDK reads all configuration (DSN, release, environment, sample rate, etc.) from the Worker's `env` bindings at runtime. -Configured Durable Object, Workflow, and Agents SDK classes must be declared in the Worker entry for the plugin to wrap them automatically. The plugin cannot rewrite a class that the entry only imports or re-exports from another module. In that case, wrap the imported class in the entry with its matching helper and pass it the options callback from `instrument.server.*`: - -```typescript {filename:src/worker/index.ts} -import * as Sentry from "@sentry/cloudflare"; -import sentryOptions from "./instrument.server"; -import { MyAgent as MyAgentBase } from "./my-agent"; - -export const MyAgent = Sentry.instrumentAgentWithSentry( - sentryOptions, - MyAgentBase -); -``` - -Use `instrumentDurableObjectWithSentry` for a plain Durable Object or `instrumentWorkflowWithSentry` for a Workflow. +Configured classes are wrapped wherever they reach the Worker entry, whether they're declared there, imported from another module and exported by name, or re-exported straight through. A class you wrapped yourself is left as it is. ### Derived RPC Trace Propagation @@ -63,7 +45,7 @@ The plugin knows which bindings point at classes it wrapped itself: Durable Obje Bindings to _other_ Workers stay opt-in, because their receivers may not run Sentry. List those yourself in `instrument.server.*`; whatever you list is added on top of the derived names. -The plugin derives only the classes it wrapped itself. A class you wrapped by hand, or one re-exported from another module, runs on its own options and stays out. +The plugin derives only the classes it wrapped itself. A class you wrapped by hand runs on its own options and stays out. This applies to Vite builds only. At runtime a `DurableObjectNamespace` exposes no origin and a `Fetcher` does not say which service it points at, so a plain wrangler build still has to list its bindings. @@ -79,9 +61,6 @@ export default defineConfig({ cloudflare({ configPath: "./wrangler.agent.jsonc" }), sentryCloudflareVitePlugin({ wranglerConfigPath: "./wrangler.agent.jsonc", - _experimental: { - autoInstrumentation: true, - }, }), ], }); @@ -89,23 +68,17 @@ export default defineConfig({ - - -Experimental options that may change or be removed without notice. - - - - + -Build-time instrumentation of supported dependencies. The plugin injects `diagnostics_channel.tracingChannel` calls into the bundled packages, and next to each one a snippet that registers the matching Sentry channel subscriber, which the SDK picks up in `Sentry.withSentry()`. This is how those packages get traced in the Workers runtime, where the SDK can't monkey-patch them. Both `vite build` and `vite dev` are instrumented. +Build-time instrumentation of supported dependencies. The plugin injects `diagnostics_channel.tracingChannel` calls into the bundled packages, and next to each one a snippet that registers the matching Sentry channel subscriber, which the SDK picks up in `Sentry.withSentry()`. This is how those packages get traced in the Workers runtime, where the SDK can't monkey-patch them. Both `vite build` and `vite dev` are instrumented. Set to `false` to opt out. A package is only instrumented if it's actually bundled. A dependency you mark as external is resolved at runtime and never passes through the build, so it stays untraced. - + -Wraps your Worker at build time so you don't have to edit your entry. The plugin reads your wrangler config, wraps the default export with `Sentry.withSentry()` (sourcing options from a co-located `instrument.server.*` file, falling back to `env`), and wraps configured classes with the matching helper: Durable Objects with `instrumentDurableObjectWithSentry`, Workflows with `instrumentWorkflowWithSentry`, and Agents SDK classes with `instrumentAgentWithSentry` (SDK version 10.69.0 or higher). Both `vite build` and `vite dev` are instrumented. Entries you wrapped yourself are left alone, so this is safe alongside manual instrumentation. The plugin also adds the bindings that resolve to the wrapped classes to `rpcTracePropagationBindings` (SDK version 10.72.0 or higher). +Wraps your Worker at build time so you don't have to edit your entry. The plugin reads your wrangler config, wraps the default export with `Sentry.withSentry()` (sourcing options from a co-located `instrument.server.*` file, falling back to `env`), and wraps configured classes with the matching helper: Durable Objects with `instrumentDurableObjectWithSentry`, Workflows with `instrumentWorkflowWithSentry`, and Agents SDK classes with `instrumentAgentWithSentry`. Both `vite build` and `vite dev` are instrumented. Entries you wrapped yourself are left alone, so this is safe alongside manual instrumentation. The plugin also adds the bindings that resolve to the wrapped classes to `rpcTracePropagationBindings`. Set to `false` to opt out. diff --git a/docs/platforms/javascript/guides/cloudflare/install/wrangler.mdx b/docs/platforms/javascript/guides/cloudflare/install/wrangler.mdx index 4ae0a8c0fd49c5..a248dc60f98ccd 100644 --- a/docs/platforms/javascript/guides/cloudflare/install/wrangler.mdx +++ b/docs/platforms/javascript/guides/cloudflare/install/wrangler.mdx @@ -17,7 +17,7 @@ Everything else is the same: install, Wrangler configuration, source maps, and t `withSentry` gives you the same errors and request traces as the plugin. What a plain Wrangler build can't do is instrument your bundled dependencies. -The Workers runtime doesn't let the SDK patch modules at runtime, so packages like database and AI clients are only traced when something rewrites them during the build. That's what the Vite plugin's `_experimental.useDiagnosticsChannelInjection` does. Without it, spans from those packages are missing, and you only get the spans the SDK creates itself. +The Workers runtime doesn't let the SDK patch modules at runtime, so packages like database and AI clients are only traced when something rewrites them during the build. That's what the Vite plugin's `buildTimeInstrumentation` does. Without it, spans from those packages are missing, and you only get the spans the SDK creates itself. You also have to keep the wrapper in your code, and list your RPC trace propagation bindings by hand, because a plain build can't derive them. See RPC Trace Propagation. diff --git a/docs/product/mcp-servers/getting-started.mdx b/docs/product/mcp-servers/getting-started.mdx index d4ab1888f977ac..0c4febacedf6ee 100644 --- a/docs/product/mcp-servers/getting-started.mdx +++ b/docs/product/mcp-servers/getting-started.mdx @@ -75,7 +75,7 @@ Defaults to `dataCollection.genAI.outputs`. In Sentry JavaScript SDK 10.x, when #### Cloudflare Workers -MCP work on Cloudflare can finish after the Worker returns an HTTP response. Configure `traceLifecycle: "stream"` so spans are sent when they finish instead of depending on a static request snapshot. This requires `@sentry/cloudflare` version `10.49.0` or newer. +MCP work on Cloudflare can finish after the Worker returns an HTTP response. The SDK streams spans by default, sending each one when it finishes, so this work is captured without extra configuration. Setting `traceLifecycle: "static"` drops the spans that finish after the response. See [MCP Monitoring on Cloudflare](/platforms/javascript/guides/cloudflare/mcp-monitoring/) for the configuration and filtering differences in stream mode. diff --git a/platform-includes/configuration/integrations/javascript.cloudflare.mdx b/platform-includes/configuration/integrations/javascript.cloudflare.mdx index deddfb8faa9f77..8a6d16786aaafa 100644 --- a/platform-includes/configuration/integrations/javascript.cloudflare.mdx +++ b/platform-includes/configuration/integrations/javascript.cloudflare.mdx @@ -14,6 +14,5 @@ | [`supabaseIntegration`](./supabase) | | ✓ | ✓ | | | | [`instrumentPostgresJsSql`](./postgresjs) | | | ✓ | | | | [`prismaIntegration`](./prisma) | | | ✓ | | | -| [`honoIntegration`](./hono) | ✓ | ✓ | | | | -The [`prismaIntegration`](./prisma) is only available through the [`@sentry/cloudflare/nodejs_compat`](../../features/nodejs-compat) entrypoint. +The [`prismaIntegration`](./prisma) needs the `nodejs_compat` compatibility flag on your Worker. diff --git a/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx b/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx index 7073f9ba97de67..805bb88f317ecb 100644 --- a/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx +++ b/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx @@ -11,7 +11,11 @@ By default, traces are not propagated across [RPC calls](https://developers.clou That trailing argument is why propagation is opt-in per binding: only a Sentry-instrumented receiver strips it again. List the bindings whose receiver you know runs Sentry in `rpcTracePropagationBindings` (SDK version 10.72.0 or higher). Setting the option also turns on the receiver side, so a Worker that both calls and receives needs nothing else. - If you build with the Sentry Cloudflare Vite plugin and its `autoInstrumentation` option, the plugin configures the bindings that point at classes in the same Worker. You only need to list bindings to other Workers. + If you build with the Sentry + Cloudflare Vite plugin, it derives the bindings that point at + classes in this Worker, so you only need to list bindings to other Workers. + See Derived + RPC Trace Propagation. **Worker Side (Caller):** diff --git a/redirects.js b/redirects.js index d29abe41fdd5cb..1c914de692bae8 100644 --- a/redirects.js +++ b/redirects.js @@ -2292,6 +2292,22 @@ const userDocsRedirects = [ destination: '/platforms/javascript/guides/cloudflare/install/vite-plugin/:path*', }, + // The nodejs_compat entrypoint was removed in v11; the guide covers the single entry. + { + source: '/platforms/javascript/guides/cloudflare/features/nodejs-compat.md', + destination: '/platforms/javascript/guides/cloudflare.md', + }, + { + source: + '/platforms/javascript/guides/cloudflare/features/nodejs-compat/:path*', + destination: '/platforms/javascript/guides/cloudflare/', + }, + // honoIntegration was removed in v11 in favor of the @sentry/hono SDK. + { + source: + '/platforms/javascript/guides/cloudflare/configuration/integrations/hono/:path*', + destination: '/platforms/javascript/guides/hono/', + }, // Cloudflare AI pages moved from Features to Agent Tracing. { source: '/platforms/javascript/guides/cloudflare/features/agents-sdk.md',