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

main
ts 168 lines 5.51 KB
Raw
1 import * as Namespace from "alchemy/Namespace";
2 import type { ResourceBinding } from "alchemy/Resource";
3 import * as AlchemyTelemetry from "alchemy/Telemetry";
4 /**
5 * Cloudflare Workers Observability tracer as a binding layer — the
6 * platform-native counterpart of `Axiom.Telemetry`.
7 */
8 import * as Data from "effect/Data";
9 import * as Effect from "effect/Effect";
10 import * as Layer from "effect/Layer";
11 import { layer as cloudflareTracerLayer } from "./CloudflareTracer.ts";
12 import { getCompatibility } from "./Compatibility.ts";
13 import { Worker, type WorkerProps } from "./Worker.ts";
14
15 /**
16 * Earliest compatibility date that exposes `tracing.startActiveSpan`
17 * (`cloudflare:workers`). ISO dates compare lexically.
18 */
19 export const MIN_CLOUDFLARE_TRACING_DATE = "2026-07-28";
20
21 /**
22 * Thrown when {@link Telemetry} is provided on a Worker whose resolved
23 * compatibility date is older than {@link MIN_CLOUDFLARE_TRACING_DATE}.
24 */
25 export class CloudflareTelemetryCompatibilityError extends Data.TaggedError(
26 "CloudflareTelemetryCompatibilityError",
27 )<{
28 date: string;
29 minimumDate: string;
30 }> {
31 override get message() {
32 return (
33 `Cloudflare.Telemetry() requires compatibility date >= ${this.minimumDate} ` +
34 `(tracing.startActiveSpan). This Worker is pinned to ${this.date}. ` +
35 `Set compatibility: { date: "${this.minimumDate}" } (or later) on the Worker.`
36 );
37 }
38 }
39
40 export interface CloudflareTelemetryProps {
41 /**
42 * Enable Workers Traces on the host Worker.
43 * @default true
44 */
45 enabled?: boolean;
46 /**
47 * Head-based sampling rate for Workers Traces (`0`–`1`).
48 * Omitted unless set — Cloudflare's default applies.
49 */
50 headSamplingRate?: number;
51 /**
52 * Persist traces in the Cloudflare dashboard. Omitted unless set.
53 * Pass `false` to export-only (no dashboard persist).
54 */
55 persist?: boolean;
56 }
57
58 const tracesFromProps = (props: CloudflareTelemetryProps) => ({
59 enabled: props.enabled ?? true,
60 ...(props.headSamplingRate !== undefined ? { headSamplingRate: props.headSamplingRate } : {}),
61 ...(props.persist !== undefined ? { persist: props.persist } : {}),
62 });
63
64 /**
65 * Fail deploy when `Cloudflare.Telemetry()` is bound and the Worker's
66 * resolved compatibility date is too old for `tracing.startActiveSpan`.
67 *
68 * @internal
69 */
70 export const assertCloudflareTelemetryCompatibility = (
71 news: WorkerProps,
72 bindings: ReadonlyArray<ResourceBinding<Worker["Binding"]>>,
73 ): Effect.Effect<void, CloudflareTelemetryCompatibilityError> => {
74 const hasBind = bindings.some((b) => b.data.observability?.traces != null);
75 if (!hasBind) return Effect.void;
76 const { date } = getCompatibility(news);
77 if (date >= MIN_CLOUDFLARE_TRACING_DATE) return Effect.void;
78 return Effect.fail(
79 new CloudflareTelemetryCompatibilityError({
80 date,
81 minimumDate: MIN_CLOUDFLARE_TRACING_DATE,
82 }),
83 );
84 };
85
86 /**
87 * Mirror Effect spans into Cloudflare Workers Observability.
88 *
89 * A binding layer: at deploy time it turns on `observability.traces` on the
90 * host Worker (the same path as `Cloudflare.cache()`) and registers a
91 * per-event Effect Tracer. Cloudflare auto-instruments fetch/KV/R2/D1;
92 * `Effect.withSpan` / `Effect.fn` frames nest in that waterfall. Cloudflare
93 * owns sampling and export — no OTLP URL, flush, or Wrangler block.
94 *
95 * Until the global default compatibility date is raised past 2026-07-28,
96 * pin `compatibility: { date: "2026-08-25" }` (or later) or deploy fails.
97 * `alchemy dev` does not gate the date: what a local Worker records is the
98 * local runtime's concern.
99 *
100 * Compose it into the Function/Worker's single `Effect.provide`:
101 *
102 * ### Enabling native tracing
103 * **Example:** Effect spans in the Workers Observability waterfall
104 * ```typescript
105 * export default Cloudflare.Worker(
106 * "Worker",
107 * {
108 * main: import.meta.url,
109 * compatibility: { date: "2026-08-25" },
110 * },
111 * Effect.gen(function* () {
112 * return {
113 * fetch: Effect.gen(function* () {
114 * yield* doWork().pipe(Effect.withSpan("operation"));
115 * return HttpServerResponse.text("ok");
116 * }),
117 * };
118 * }).pipe(
119 * Effect.provide(
120 * Layer.mergeAll(
121 * Cloudflare.R2.ReadWriteBucketBinding,
122 * Cloudflare.Telemetry(),
123 * ),
124 * ),
125 * ),
126 * );
127 * ```
128 *
129 * ### Combining with other exporters
130 * **Example:** Native traces plus another exporter's logs and metrics
131 * ```typescript
132 * Effect.provide(
133 * Layer.mergeAll(
134 * Cloudflare.Telemetry(),
135 * // omit `traces` — Cloudflare.Telemetry provides the Tracer
136 * Axiom.Telemetry({ token: Ingest, logs: Logs, metrics: Metrics }),
137 * ),
138 * )
139 * ```
140 *
141 * To ship the same waterfall (Effect + platform spans) elsewhere, export
142 * it from Cloudflare with `Cloudflare.Workers.ObservabilityDestination`
143 * rather than sending a second Worker-side OTLP trace stream.
144 *
145 * @layer
146 * @provides Tracer.Tracer
147 * @product Workers
148 * @category Workers & Compute
149 */
150 export const Telemetry = (
151 props: CloudflareTelemetryProps = {},
152 ): Layer.Layer<never, never, Worker> =>
153 Layer.unwrap(
154 Effect.gen(function* () {
155 const host = yield* Worker;
156 if (!globalThis.__ALCHEMY_RUNTIME__) {
157 yield* Namespace.push(
158 host.LogicalId,
159 host.bind("Cloudflare.Telemetry", {
160 observability: { traces: tracesFromProps(props) },
161 }),
162 );
163 }
164 // The runtime bridges build the registered Layer per event with a
165 // forked MemoMap, so the Tracer is naturally fresh per invocation.
166 return AlchemyTelemetry.layer(cloudflareTracerLayer);
167 }),
168 );