@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 311 lines 11.3 KB
Raw
1 /**
2 * OpenTelemetry export for deployed Functions/Workers, built on Effect's
3 * OTLP exporters (`effect/observability`) and configured through
4 * alchemy's binding infrastructure — exporters are Layers, and their
5 * configuration (endpoints, tokens) is wired from resource Outputs like any
6 * other binding.
7 *
8 * Provide a telemetry Layer on the Function/Worker init Effect, composed
9 * into the single `Effect.provide` alongside the other binding layers:
10 *
11 * ```ts
12 * import * as Alchemy from "alchemy";
13 * import * as Axiom from "@alchemy.run/axiom";
14 *
15 * Effect.gen(function* () {
16 * // ...
17 * }).pipe(
18 * Effect.provide(
19 * Layer.mergeAll(
20 * Cloudflare.R2.ReadWriteBucketBinding,
21 * // vendor sugar — binds dataset endpoints + ingest token:
22 * Axiom.Telemetry({ token: Ingest, traces: Traces, logs: Logs }),
23 * // or the generic OTLP form, wired from any Inputs/Outputs:
24 * // Alchemy.Telemetry.layerOtlp({ url: collector.url, headers: { ... } }),
25 * // or any custom exporter Layer:
26 * // Alchemy.Telemetry.layer(myExporterLayer),
27 * ),
28 * ),
29 * );
30 * ```
31 *
32 * {@link layerOtlp} is a *binding* layer: at deploy time it binds the
33 * configured endpoints/headers onto the host (Redacted values as secrets),
34 * and at runtime the exporter reads those bound values back. Telemetry is
35 * off until a layer is provided — Effect's default tracer is a no-op, so
36 * all instrumentation stays free.
37 *
38 * `Telemetry` itself is a `Context.Reference` holding the Layer of
39 * exporters to install for every event (fetch, queue, cron, RPC, Durable
40 * Object call, Workflow run, Lambda invoke). The runtime bridges build that
41 * Layer into the event's request scope, so:
42 *
43 * - the exporter's batching fiber runs inside the event's I/O context
44 * (required on workerd, where timers/fetches are pinned to the request),
45 * - buffered spans/logs/metrics are flushed when the request scope
46 * finalizes — registered with `ctx.waitUntil`, so flushing never delays
47 * the response.
48 */
49 import * as Effect from "effect/Effect";
50 import * as Layer from "effect/Layer";
51 import * as Redacted from "effect/Redacted";
52 import type { Input } from "./Input.ts";
53 import * as Output from "./Output.ts";
54 import { CurrentRuntimeContext } from "./RuntimeContext.ts";
55 import {
56 EXPORTERS_KEY,
57 fromBoundConfig,
58 type ResolvedDestination,
59 type ResolvedSignal,
60 Telemetry,
61 type TelemetryLayer,
62 } from "./TelemetryRuntime.ts";
63
64 export {
65 buildEventTelemetry,
66 provideProcessTelemetry,
67 Telemetry,
68 type TelemetryLayer,
69 } from "./TelemetryRuntime.ts";
70 export {
71 type Destination as RelayDestination,
72 type RelayOptions,
73 relay,
74 type Signal as RelaySignal,
75 } from "./TelemetryRelay.ts";
76
77 const reference = Telemetry;
78
79 /**
80 * Install a custom telemetry Layer (any Layer providing a `Tracer`,
81 * loggers, and/or metric exporters). It is built once per event into the
82 * event's request scope, so scoped exporters flush when the request scope
83 * finalizes.
84 *
85 * Custom layers COMPOSE with the built-in OTLP destinations and with each
86 * other: loggers and metric exporters merge; a custom `Tracer` (a single
87 * Effect service) replaces the built-in one.
88 *
89 * The isolate {@link Telemetry} reference stays the bound OTLP reader.
90 * The custom Layer is stored on `ctx.telemetry` and merged per event as
91 * the override, so `Layer.mergeAll` order with {@link layerOtlp} does not
92 * drop logs/metrics.
93 *
94 * Provide it on the Function/Worker's init Effect (merged into the single
95 * `Effect.provide`): building the returned Layer registers the exporter
96 * Layer on the current runtime context, where the runtime bridges pick it
97 * up per event. Handlers' request-time context is assembled by the bridge,
98 * so a plain `Layer.succeed` of the reference on the init Effect would
99 * never reach them — the registration is what makes it visible at request
100 * time.
101 */
102 export const layer = (exporter: TelemetryLayer): Layer.Layer<never> =>
103 Layer.effect(
104 reference,
105 Effect.gen(function* () {
106 const ctx = yield* CurrentRuntimeContext;
107 if (ctx !== undefined) {
108 ctx.telemetry =
109 ctx.telemetry === undefined ? exporter : Layer.mergeAll(ctx.telemetry, exporter);
110 }
111 return fromBoundConfig;
112 }),
113 );
114
115 /**
116 * A header value: a plain string, a `Redacted` secret, or an Output of
117 * either (e.g. an ApiToken's `token` attribute).
118 */
119 export type OtlpHeaderValue = Input<string | Redacted.Redacted<string>>;
120
121 /**
122 * OTLP configuration for one signal. `url` and header values accept plain
123 * values or resource Outputs — they are *bound* onto the host at deploy
124 * time like any other binding.
125 */
126 export interface OtlpSignalOptions {
127 /** The OTLP/HTTP URL exports for this signal are POSTed to. */
128 url: Input<string>;
129 /**
130 * Headers sent with each export request (e.g. auth tokens). `Redacted`
131 * values bind as secrets.
132 */
133 headers?: Record<string, OtlpHeaderValue> | undefined;
134 }
135
136 /**
137 * Options for {@link layerOtlp}. Configure a base `url` (with
138 * `/v1/{signal}` appended per signal), per-signal urls, or a mix — a
139 * per-signal entry takes precedence over the base.
140 */
141 export interface OtlpOptions {
142 /** Base OTLP/HTTP URL; `/v1/{traces,logs,metrics}` is appended per signal. */
143 url?: Input<string> | undefined;
144 /** Headers for every signal; per-signal `headers` take precedence. */
145 headers?: Record<string, OtlpHeaderValue> | undefined;
146 traces?: OtlpSignalOptions | undefined;
147 logs?: OtlpSignalOptions | undefined;
148 metrics?: OtlpSignalOptions | undefined;
149 /**
150 * The exported `service.name`.
151 * @default the deployed Function/Worker's physical name
152 */
153 serviceName?: Input<string> | undefined;
154 }
155
156 /**
157 * A placeholder in the destinations template pointing at one captured
158 * Input value.
159 */
160 interface Placeholder {
161 readonly $input: number;
162 }
163
164 /**
165 * Per-runtime-context accumulator: every `layerOtlp` layer built for
166 * the same host appends its destination here and rebinds the full list, so
167 * merged layers compose instead of clobbering each other.
168 */
169 const rcDestinations = new WeakMap<object, OtlpOptions[]>();
170
171 /**
172 * Compose the full destination list into a single Output: capture every
173 * Input (urls, header values) into an `Output.all`, then materialize the
174 * JSON array of {@link ResolvedDestination}. If any captured value is
175 * `Redacted`, the whole JSON binds as a secret.
176 */
177 const destinationsOutput = (
178 list: OtlpOptions[],
179 ): Output.Output<string | Redacted.Redacted<string>> => {
180 const inputs: unknown[] = [];
181 const capture = (value: unknown): Placeholder => {
182 inputs.push(value);
183 return { $input: inputs.length - 1 };
184 };
185 const captureHeaders = (
186 headers: Record<string, OtlpHeaderValue> | undefined,
187 ): Record<string, Placeholder> | undefined =>
188 headers === undefined
189 ? undefined
190 : Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, capture(value)]));
191 const template = list.map((options) => ({
192 url: options.url !== undefined ? capture(options.url) : undefined,
193 headers: captureHeaders(options.headers),
194 traces: options.traces && {
195 url: capture(options.traces.url),
196 headers: captureHeaders(options.traces.headers),
197 },
198 logs: options.logs && {
199 url: capture(options.logs.url),
200 headers: captureHeaders(options.logs.headers),
201 },
202 metrics: options.metrics && {
203 url: capture(options.metrics.url),
204 headers: captureHeaders(options.metrics.headers),
205 },
206 }));
207 return (
208 Output.all(...inputs.map((input) => Output.asOutput(input as never))) as Output.Output<
209 unknown[]
210 >
211 ).pipe(
212 Output.map((values) => {
213 let secret = false;
214 const resolve = (placeholder: Placeholder): string => {
215 let value = values[placeholder.$input];
216 if (Redacted.isRedacted(value)) {
217 secret = true;
218 value = Redacted.value(value);
219 }
220 return typeof value === "string" ? value : String(value);
221 };
222 const resolveHeaders = (
223 headers: Record<string, Placeholder> | undefined,
224 ): Record<string, string> | undefined =>
225 headers === undefined
226 ? undefined
227 : Object.fromEntries(
228 Object.entries(headers).map(([key, value]) => [key, resolve(value)]),
229 );
230 const resolveSignal = (
231 entry: { url: Placeholder; headers?: Record<string, Placeholder> },
232 base: { url?: Placeholder; headers?: Record<string, Placeholder> },
233 path: string,
234 ): ResolvedSignal | undefined => {
235 if (entry !== undefined) {
236 return {
237 url: resolve(entry.url),
238 headers: resolveHeaders(entry.headers),
239 };
240 }
241 if (base.url !== undefined) {
242 return {
243 url: `${resolve(base.url).replace(/\/$/, "")}/v1/${path}`,
244 headers: resolveHeaders(base.headers),
245 };
246 }
247 return undefined;
248 };
249 const destinations = template.flatMap((entry): ResolvedDestination[] => {
250 const destination: ResolvedDestination = {
251 traces: resolveSignal(entry.traces as never, entry, "traces"),
252 logs: resolveSignal(entry.logs as never, entry, "logs"),
253 metrics: resolveSignal(entry.metrics as never, entry, "metrics"),
254 };
255 return destination.traces || destination.logs || destination.metrics ? [destination] : [];
256 });
257 const json = JSON.stringify(destinations);
258 return secret ? Redacted.make(json) : json;
259 }),
260 );
261 };
262
263 /**
264 * The built-in OTLP exporter as a *binding* layer.
265 *
266 * At deploy time, building this layer binds the configured urls and
267 * headers onto the host Function/Worker (Redacted values as secret
268 * bindings) — url and header values accept resource Outputs, so exporter
269 * config is wired from resources like any other binding. At runtime the
270 * exporter reads the bound values back and ships traces, logs, and metrics
271 * over OTLP/HTTP JSON, flushed as each event's scope closes.
272 *
273 * Exporters COMPOSE: merge several `otlp` layers (or vendor sugar like
274 * `Axiom.Telemetry`) and every destination receives the telemetry — spans
275 * are serialized once, so trace/span ids agree across destinations:
276 *
277 * ```ts
278 * Effect.provide(
279 * Layer.mergeAll(
280 * Cloudflare.R2.ReadWriteBucketBinding,
281 * Axiom.Telemetry({ token: Ingest, traces: Traces, logs: Logs }),
282 * Alchemy.Telemetry.layerOtlp({
283 * url: "https://api.honeycomb.io",
284 * headers: { "x-honeycomb-team": apiKey },
285 * }),
286 * ),
287 * )
288 * ```
289 */
290 export const layerOtlp = (options: OtlpOptions): Layer.Layer<never> =>
291 Layer.effect(
292 reference,
293 Effect.gen(function* () {
294 const rc = yield* CurrentRuntimeContext;
295 if (rc !== undefined && !globalThis.__ALCHEMY_RUNTIME__) {
296 // Accumulate this destination with any bound by sibling layers on
297 // the same host, and rebind the full list (rebinding the same key
298 // just overwrites, so build order doesn't matter).
299 const list = rcDestinations.get(rc) ?? [];
300 list.push(options);
301 rcDestinations.set(rc, list);
302 yield* rc.set(EXPORTERS_KEY, destinationsOutput(list));
303 if (options.serviceName !== undefined) {
304 yield* rc.set("OTEL_SERVICE_NAME", Output.asOutput(options.serviceName as never));
305 }
306 }
307 // The runtime half reads the bound destinations back per event (or
308 // once per process via `provideProcessTelemetry`).
309 return fromBoundConfig;
310 }),
311 );