Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/platforms/javascript/common/agent-tracing/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

</PlatformSection>

Expand Down
24 changes: 3 additions & 21 deletions docs/platforms/javascript/common/mcp-monitoring/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <PlatformLink to="/tracing/streamed-spans/">Streamed Spans</PlatformLink> 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 <PlatformLink to="/configuration/options/#beforeSendSpan">beforeSendSpan</PlatformLink> and <PlatformLink to="/configuration/options/#ignoreSpans">ignoreSpans</PlatformLink> 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 <PlatformLink to="/agent-tracing/agents-sdk/">Agents SDK</PlatformLink>.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ export const MyAgent = Sentry.instrumentAgentWithSentry(

The Worker that calls the agent names its binding in `rpcTracePropagationBindings`. See <PlatformLink to="/tracing/distributed-tracing/#rpc-trace-propagation">RPC Trace Propagation</PlatformLink>.

`instrumentAgentWithSentry` works with `Agent` from `agents`, `AIChatAgent` from `@cloudflare/ai-chat`, and `McpAgent` from `agents/mcp`. When you build with the <PlatformLink to="/install/vite-plugin/">Sentry Cloudflare Vite plugin</PlatformLink>'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 <PlatformLink to="/install/vite-plugin/">Sentry Cloudflare Vite plugin</PlatformLink>, it detects and wraps Agent classes for you, so you only need this wrapper on a plain Wrangler build.

## Conversation IDs

Expand Down

This file was deleted.

Original file line number Diff line number Diff line change
@@ -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."
---

<Alert>

On Cloudflare, the `prismaIntegration` is only available through the <PlatformLink to="/features/nodejs-compat">`@sentry/cloudflare/nodejs_compat`</PlatformLink> entrypoint, which requires SDK version `10.64.0` or higher.

</Alert>

_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,
Expand Down

This file was deleted.

Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand All @@ -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));
};
Comment thread
sentry[bot] marked this conversation as resolved.
```

Expand Down
6 changes: 0 additions & 6 deletions docs/platforms/javascript/guides/cloudflare/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -59,12 +59,6 @@ Run the command for your preferred package manager to add the Sentry SDK to your
</SplitSection>
</SplitLayout>

<Alert>

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).

</Alert>

## 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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,6 @@ description: "Learn how to use the Sentry Cloudflare Vite plugin to instrument b

<AvailableSince version="10.68.0" />

<Alert>
The Sentry Cloudflare Vite plugin has **experimental** stability.
Configuration options and behavior may change or be removed in any release.
</Alert>

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.
Expand All @@ -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 <PlatformLink to="/agent-tracing/agents-sdk/">Cloudflare Agents SDK</PlatformLink>).

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 <PlatformLink to="/install/wrangler/">Wrangler setup</PlatformLink>.
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 <PlatformLink to="/install/wrangler/">Wrangler setup</PlatformLink>.

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:

Expand All @@ -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

Expand All @@ -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.

Expand Down Expand Up @@ -96,7 +78,7 @@ A package is only instrumented if it's actually bundled. A dependency you mark a

<SdkOption name="autoInstrumentation" type="boolean" defaultValue="true">

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.

</SdkOption>

Expand Down
2 changes: 1 addition & 1 deletion docs/product/mcp-servers/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Alert>
If you build with the <PlatformLink to="/install/vite-plugin/">Sentry Cloudflare Vite plugin</PlatformLink> 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 <PlatformLink to="/install/vite-plugin/">Sentry
Cloudflare Vite plugin</PlatformLink>, it derives the bindings that point at
classes in this Worker, so you only need to list bindings to other Workers.
See <PlatformLink to="/install/vite-plugin/#derived-rpc-trace-propagation">Derived
RPC Trace Propagation</PlatformLink>.
</Alert>

**Worker Side (Caller):**
Expand Down
16 changes: 16 additions & 0 deletions redirects.js
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
Loading