diff --git a/docs/platforms/javascript/common/agent-tracing/index.mdx b/docs/platforms/javascript/common/agent-tracing/index.mdx index f783c167a6d34..53bde1929d3d4 100644 --- a/docs/platforms/javascript/common/agent-tracing/index.mdx +++ b/docs/platforms/javascript/common/agent-tracing/index.mdx @@ -230,7 +230,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/mcp-monitoring/index.mdx b/docs/platforms/javascript/common/mcp-monitoring/index.mdx index b2e41af08a68d..4728e643811e7 100644 --- a/docs/platforms/javascript/common/mcp-monitoring/index.mdx +++ b/docs/platforms/javascript/common/mcp-monitoring/index.mdx @@ -56,29 +56,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()`. In transaction mode, 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. -Span streaming is enabled by default, so the SDK can send each sampled span when it finishes. Use `traceLifecycle: "stream"` to preserve spans that finish after the response. You still need to wrap the MCP server as shown above. +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, - }), - worker -); -``` - -Use `beforeSendSpan` to modify each finished span's `name` and `attributes`, with an `is_segment` guard to target service spans. Use the object form of `ignoreSpans` to drop spans by name and operation. See Streamed Spans for examples. +Streaming sends span records instead of assembling one transaction event with embedded spans. `beforeSendTransaction` and `ignoreTransactions` don't apply to streamed spans. Use beforeSendSpan and ignoreSpans instead. 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. 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 d74c495d47609..50a6f45095517 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 adba0ecd9b05b..0000000000000 --- 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 febbd812a4af1..c6f8ae2472a07 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 44d85ea68781e..0000000000000 --- 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 afc7c2d363142..4b73ef8dccd58 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 1ca6aba3bf96a..ea39fc1018fe9 100644 --- a/docs/platforms/javascript/guides/cloudflare/index.mdx +++ b/docs/platforms/javascript/guides/cloudflare/index.mdx @@ -59,12 +59,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. diff --git a/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx b/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx index 8007e7ff0208c..d5f43e559d5ab 100644 --- a/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx +++ b/docs/platforms/javascript/guides/cloudflare/install/vite-plugin.mdx @@ -5,11 +5,6 @@ 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. @@ -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). -Any 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, set `autoInstrumentation: false` 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. @@ -96,7 +78,7 @@ A package is only instrumented if it's actually bundled. A dependency you mark a -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). Set to `false` to opt out. +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/product/mcp-servers/getting-started.mdx b/docs/product/mcp-servers/getting-started.mdx index 3cb4760765a24..4705cbc8f315e 100644 --- a/docs/product/mcp-servers/getting-started.mdx +++ b/docs/product/mcp-servers/getting-started.mdx @@ -76,7 +76,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 82ee0233153bd..a4c0a16fb41bf 100644 --- a/platform-includes/configuration/integrations/javascript.cloudflare.mdx +++ b/platform-includes/configuration/integrations/javascript.cloudflare.mdx @@ -14,8 +14,7 @@ | [`supabaseIntegration`](./supabase) | | ✓ | ✓ | | | | [`instrumentPostgresJsSql`](./postgresjs) | | | ✓ | | | | [`prismaIntegration`](./prisma) | | | ✓ | | | -| [`honoIntegration`](./hono) | ✓ | ✓ | | | | [Mistral AI](./mistral) is automatically instrumented when built with the Sentry Cloudflare Vite plugin. Without the plugin, use `instrumentMistralAiClient`. -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 7073f9ba97de6..805bb88f317ec 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 de8c5c6479dd3..c65c4da64712c 100644 --- a/redirects.js +++ b/redirects.js @@ -2367,6 +2367,22 @@ const userDocsRedirects = [ source: '/platforms/javascript/guides/cloudflare/features/vite-plugin/:path*', 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',