The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 164 lines 5.12 KB
Raw
1 ---
2 title: Native Workers tracing
3 description: Mirror Effect spans into Cloudflare Workers Observability with Cloudflare.Telemetry() — the same Layer shape as Axiom.Telemetry, with Cloudflare owning sampling and export.
4 sidebar:
5 order: 15
6 ---
7
8 Cloudflare Workers can emit OpenTelemetry traces natively: fetch, KV, R2,
9 and D1 are auto-instrumented, and custom spans join that waterfall via
10 `tracing.startActiveSpan`. Alchemy's `Cloudflare.Telemetry()` Layer
11 forwards `Effect.withSpan` / `Effect.fn` frames into that API so Effect
12 code shows up next to the platform spans.
13
14 ## Provide the layer
15
16 Pin a compatibility date at or after `2026-07-28` (`startActiveSpan` GA).
17 The global Worker default is still older, so omit the date and deploy
18 fails instead of silently dropping Effect spans.
19
20 ```typescript
21 export default Cloudflare.Worker(
22 "Worker",
23 {
24 main: import.meta.url,
25 compatibility: { date: "2026-08-25" },
26 },
27 Effect.gen(function* () {
28 return {
29 fetch: Effect.gen(function* () {
30 yield* doWork().pipe(Effect.withSpan("operation"));
31 return HttpServerResponse.text("ok");
32 }),
33 };
34 }).pipe(
35 Effect.provide(
36 Layer.mergeAll(
37 Cloudflare.R2.ReadWriteBucketBinding,
38 Cloudflare.Telemetry(),
39 ),
40 ),
41 ),
42 );
43 ```
44
45 You do **not** set `observability.traces.enabled` on the Worker, write a
46 Wrangler `observability` block, or configure an OTLP URL. The Layer
47 enables traces on the host (the same bind path as `Cloudflare.cache()`)
48 and installs a per-event Effect Tracer. Cloudflare owns sampling and
49 export — spans submit with the request, no `waitUntil` flush.
50
51 Existing `Effect.withSpan` / `Effect.fn` instrumentation does not change.
52
53 During `alchemy dev` the compatibility date is not gated and the Layer
54 has no deploy-time effect; whether spans are recorded locally is up to
55 the local runtime. A Worker opted out of local emulation with
56 `Alchemy.remote()` traces normally.
57
58 ## What you get
59
60 ### Effect spans in the platform waterfall
61
62 `Effect.withSpan` frames nest with Cloudflare's own spans. A KV read
63 inside a span shows up as its child, even when the fiber that issued it
64 was forked or resumed on a later tick.
65
66 ```typescript
67 const handle = Effect.gen(function* () {
68 const user = yield* kv.get("user:1").pipe(Effect.withSpan("load.user"));
69 yield* Effect.all([enrich(user), audit(user)], { concurrency: "unbounded" });
70 }).pipe(Effect.withSpan("handle"));
71 ```
72
73 ```text
74 http.server GET
75 └─ handle
76 ├─ load.user
77 │ └─ kv_get
78 ├─ enrich
79 └─ audit
80 ```
81
82 ### Attributes
83
84 Scalar annotations (`string`, `number`, `boolean`) are forwarded to the
85 Cloudflare span. Nested objects, span events, and links stay Effect-local.
86
87 ```typescript
88 yield* Effect.annotateCurrentSpan("user.id", userId); // forwarded
89 yield* Effect.annotateCurrentSpan("retries", 2); // forwarded
90 yield* Effect.annotateCurrentSpan("cached", true); // forwarded
91 yield* Effect.annotateCurrentSpan("input", { nested }); // Effect-local
92 ```
93
94 ### Outcome
95
96 Completion is recorded as the `effect.exit` attribute: `success`,
97 `failure`, or `interrupted`. A failure also sets the span status to
98 `error`, with the first error's message, so OpenTelemetry destinations
99 mark the span as failed. Success and interruption leave the status
100 `unset`. The Workers Observability dashboard doesn't show span status
101 yet, so filter on `effect.exit` there.
102
103 ```typescript
104 yield* Effect.fail(new Error("boom")).pipe(
105 Effect.withSpan("failing"), // effect.exit = "failure", status = error
106 Effect.ignore,
107 );
108 const fiber = yield* Effect.forkChild(
109 Effect.sleep("30 seconds").pipe(Effect.withSpan("slow")),
110 );
111 yield* Fiber.interrupt(fiber); // effect.exit = "interrupted"
112 ```
113
114 ### Sampling and persistence
115
116 `headSamplingRate` and `persist` are passed straight through to the
117 Worker's `observability.traces`. Omit them to keep Cloudflare's defaults.
118 Cloudflare applies the sampling rate when it ingests the trace, so every
119 invocation still sees a live `Tracer`.
120
121 ```typescript
122 Cloudflare.Telemetry({
123 headSamplingRate: 0.1, // keep 10% of invocations
124 persist: false, // export only, nothing in the dashboard
125 })
126 ```
127
128 ## Combining with other exporters
129
130 Effect has a single `Tracer`, and `Cloudflare.Telemetry()` provides it.
131 Any other exporter you merge in keeps its loggers and metric exporters;
132 only its `traces` are superseded. With Axiom, for example, leave `traces`
133 off and the logs and metrics still flow, in either `Layer.mergeAll`
134 order:
135
136 ```typescript
137 Effect.provide(
138 Layer.mergeAll(
139 Cloudflare.Telemetry(),
140 Axiom.Telemetry({ token: Ingest, logs: Logs, metrics: Metrics }),
141 ),
142 )
143 ```
144
145 The same goes for the generic `Alchemy.Telemetry.layerOtlp({ logs, metrics })`.
146
147 To ship the waterfall (Effect + platform spans) to another backend,
148 export it from Cloudflare with an
149 [`ObservabilityDestination`](/cloudflare/observability/axiom-observability)
150 rather than sending a second Worker-side OTLP trace stream.
151
152 ## Async Workers
153
154 Non-Effect Workers keep the `observability` prop — there is no Tracer to
155 install:
156
157 ```typescript
158 yield* Cloudflare.Worker("Api", {
159 main: "./src/api.ts",
160 observability: {
161 traces: { enabled: true },
162 },
163 });
164 ```