Cloudflare Workers Traces Integration

Record oRPC procedure, middleware, and stream spans in Cloudflare Workers Traces through the Workers custom spans API, with no OpenTelemetry SDK.

Installation

npm install @orpc/cloudflare@beta

pnpm add @orpc/cloudflare@beta

yarn add @orpc/cloudflare@beta

bun add @orpc/cloudflare@beta

nub add @orpc/cloudflare@beta

aube add @orpc/cloudflare@beta

Setup

Enable traces in your Wrangler configuration, then register CloudflareTracer once at module scope. oRPC then records the same spans as the OpenTelemetry integration, nested under the spans Workers create automatically.

{
  "observability": {
    "traces": {
      "enabled": true
    }
  }
}

import { experimental_CloudflareTracer as CloudflareTracer } from '@orpc/cloudflare'

new CloudflareTracer().enable()

Context Propagation

Workers already join service binding and Durable Object calls into one trace. oRPC links also send a W3C traceparent header built from the active span, so servers outside Cloudflare, such as one using the OpenTelemetry integration, continue the same trace.

Workers decide whether to keep a trace only after the invocation, so the header always marks the trace as sampled, and the downstream server records it even if Workers later drop their part. Set propagationEnabled to false to stop sending the header and let downstream servers sample on their own:

new CloudflareTracer({
  propagationEnabled: false,
}).enable()

Middleware Span

oRPC creates a span for each middleware execution. Use tracing.getActiveSpan() to add attributes to it:

import { tracing } from 'cloudflare:workers'

export const someMiddleware = os.middleware(async (ctx, next) => {
  tracing.getActiveSpan()?.setAttribute('someAttribute', 'someValue')

  return next()
})

Object.defineProperty(someMiddleware, 'name', {
  value: 'someName',
})

Limitations

Workers Traces still lack some APIs oRPC relies on, so:

• Streamed inputs and outputs record no yielded and enqueued events.
• Handlers ignore an incoming traceparent header, since Workers Traces cannot start a span under a remote parent.