From eeac6a83562694337cf6e1a800ecc0b91265b0fa Mon Sep 17 00:00:00 2001
From: JPeer264 <jan.peer@sentry.io>
Date: Wed, 29 Apr 2026 14:54:48 +0200
Subject: [PATCH] docs: Add distributed tracing for RPC in Cloudflare

---
 .../cloudflare/features/durableobject.mdx     |  6 +-
 .../how-to-use/javascript.cloudflare.mdx      | 68 ++++++++++++++++++-
 2 files changed, 72 insertions(+), 2 deletions(-)

diff --git a/docs/platforms/javascript/guides/cloudflare/features/durableobject.mdx b/docs/platforms/javascript/guides/cloudflare/features/durableobject.mdx
index 730e128f42b979..5c97e674d00acb 100644
--- a/docs/platforms/javascript/guides/cloudflare/features/durableobject.mdx
+++ b/docs/platforms/javascript/guides/cloudflare/features/durableobject.mdx
@@ -3,7 +3,7 @@ title: Cloudflare Durable Objects
 description: "Learn how to add Sentry instrumentation for Cloudflare Durable Objects."
 ---
 
-_(Available in version [9.16.0](https://github.com/getsentry/sentry-javascript/releases/tag/9.16.0) and above)_
+<AvailableSince version="9.16.0" />
 
 You can use the `instrumentDurableObjectWithSentry` method to instrument [Cloudflare Durable Objects](https://developers.cloudflare.com/durable-objects/).
 
@@ -23,3 +23,7 @@ export const MyDurableObject = Sentry.instrumentDurableObjectWithSentry(
   MyDurableObjectBase
 );
 ```
+
+## RPC Trace Propagation
+
+To enable distributed tracing across RPC calls to your Durable Objects, see <PlatformLink to="/tracing/distributed-tracing">Distributed Tracing</PlatformLink>.
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 0c73cfe57e7549..e2f2d7812e84ef 100644
--- a/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx
+++ b/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx
@@ -1,4 +1,70 @@
-The Sentry Cloudflare SDK has out of the box support for distributed tracing if you've setup the SDK to send traces.
+The Sentry Cloudflare SDK automatically propagates traces for incoming and outgoing HTTP requests if you've setup the SDK to send traces.
+
+For RPC calls within Cloudflare (Worker-to-Durable Object, Worker-to-Worker via service bindings), trace propagation must be explicitly enabled. See [RPC Trace Propagation](#rpc-trace-propagation) below.
+
+### RPC Trace Propagation
+
+<AvailableSince version="10.51.0" />
+
+By default, traces are not propagated across [RPC calls](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/rpc/) between Workers and Durable Objects. This is because [Cap'n Proto](https://capnproto.org/) (which powers Cloudflare RPC) has no native support for headers or metadata.
+
+To enable trace propagation for RPC method calls, set `enableRpcTracePropagation: true` on **both** the caller and receiver sides.
+
+<Alert level="warning" title="Performance Consideration">
+  RPC trace propagation requires instrumenting the environment bindings, which adds overhead to every RPC call. Only enable this option if you need distributed tracing across service boundaries.
+</Alert>
+
+**Worker Side (Caller):**
+
+```typescript
+import * as Sentry from "@sentry/cloudflare";
+
+export default Sentry.withSentry(
+  (env) => ({
+    dsn: env.SENTRY_DSN,
+    tracesSampleRate: 1.0,
+    enableRpcTracePropagation: true,
+  }),
+  {
+    async fetch(request, env, ctx) {
+      const id = env.MY_DURABLE_OBJECT.idFromName("test");
+      const stub = env.MY_DURABLE_OBJECT.get(id);
+
+      // This RPC call will now propagate trace context
+      const result = await stub.sayHello("World");
+
+      return new Response(result);
+    },
+  }
+);
+```
+
+**Durable Object Side (Receiver):**
+
+```typescript
+import * as Sentry from "@sentry/cloudflare";
+
+class MyDurableObjectBase extends DurableObject<Env> {
+  sayHello(name: string): string {
+    return `Hello, ${name}!`;
+  }
+}
+
+export const MyDurableObject = Sentry.instrumentDurableObjectWithSentry(
+  (env: Env) => ({
+    dsn: env.SENTRY_DSN,
+    tracesSampleRate: 1.0,
+    enableRpcTracePropagation: true,
+  }),
+  MyDurableObjectBase
+);
+```
+
+The SDK appends trace data (`sentry-trace` and `baggage`) as a trailing argument object to every RPC call. On the receiving side, this argument is stripped before your method is invoked, so it's completely transparent to your code.
+
+<Alert>
+  If the receiver is not instrumented with Sentry (or `enableRpcTracePropagation` is not enabled), the trailing trace argument will remain in the args array. This is usually harmless unless your method uses rest parameters (`...args`).
+</Alert>
 
 ### Custom Instrumentation