From eeac6a83562694337cf6e1a800ecc0b91265b0fa Mon Sep 17 00:00:00 2001 From: JPeer264 Date: Wed, 29 Apr 2026 14:54:48 +0200 Subject: [PATCH 1/3] 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 730e128f42b97..5c97e674d00ac 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)_ + 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 Distributed Tracing. 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 0c73cfe57e754..e2f2d7812e84e 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 + + + +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. + + + 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. + + +**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 { + 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. + + + 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`). + ### Custom Instrumentation From fcaa374ebe230c8bd6a89f02c0bf8e198ff77755 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Peer=20St=C3=B6cklmair?= Date: Mon, 4 May 2026 11:59:19 +0200 Subject: [PATCH 2/3] Update platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx Co-authored-by: Sigrid <32902192+s1gr1d@users.noreply.github.com> --- .../distributed-tracing/how-to-use/javascript.cloudflare.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 e2f2d7812e84e..2da17aae8f2c6 100644 --- a/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx +++ b/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx @@ -60,7 +60,7 @@ export const MyDurableObject = Sentry.instrumentDurableObjectWithSentry( ); ``` -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. +The SDK propagates trace context (`sentry-trace` and `baggage`) by appending a trailing argument to outgoing RPC calls. The receiving SDK automatically strips it before your method is executed. Your method signatures are unaffected. 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`). From 5d0ae0ee373288bf68847070f632b122fe4412f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Peer=20St=C3=B6cklmair?= Date: Mon, 4 May 2026 11:59:46 +0200 Subject: [PATCH 3/3] Update platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx Co-authored-by: Sigrid <32902192+s1gr1d@users.noreply.github.com> --- .../distributed-tracing/how-to-use/javascript.cloudflare.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 2da17aae8f2c6..39f9eb20d80bc 100644 --- a/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx +++ b/platform-includes/distributed-tracing/how-to-use/javascript.cloudflare.mdx @@ -63,7 +63,7 @@ export const MyDurableObject = Sentry.instrumentDurableObjectWithSentry( The SDK propagates trace context (`sentry-trace` and `baggage`) by appending a trailing argument to outgoing RPC calls. The receiving SDK automatically strips it before your method is executed. Your method signatures are unaffected. - 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`). + If the receiving Worker is not instrumented with Sentry (or `enableRpcTracePropagation` is not enabled), the trailing trace argument won't be stripped and will be passed through to your method. This is harmless for methods with fixed parameter lists, but may cause unexpected behavior if your method relies on rest parameters `(...args)` or `arguments.length`. ### Custom Instrumentation