/** * OpenTelemetry export for deployed Functions/Workers, built on Effect's * OTLP exporters (`effect/observability`) and configured through * alchemy's binding infrastructure — exporters are Layers, and their * configuration (endpoints, tokens) is wired from resource Outputs like any * other binding. * * Provide a telemetry Layer on the Function/Worker init Effect, composed * into the single `Effect.provide` alongside the other binding layers: * * ```ts * import * as Alchemy from "alchemy"; * import * as Axiom from "@alchemy.run/axiom"; * * Effect.gen(function* () { * // ... * }).pipe( * Effect.provide( * Layer.mergeAll( * Cloudflare.R2.ReadWriteBucketBinding, * // vendor sugar — binds dataset endpoints + ingest token: * Axiom.Telemetry({ token: Ingest, traces: Traces, logs: Logs }), * // or the generic OTLP form, wired from any Inputs/Outputs: * // Alchemy.Telemetry.layerOtlp({ url: collector.url, headers: { ... } }), * // or any custom exporter Layer: * // Alchemy.Telemetry.layer(myExporterLayer), * ), * ), * ); * ``` * * {@link layerOtlp} is a *binding* layer: at deploy time it binds the * configured endpoints/headers onto the host (Redacted values as secrets), * and at runtime the exporter reads those bound values back. Telemetry is * off until a layer is provided — Effect's default tracer is a no-op, so * all instrumentation stays free. * * `Telemetry` itself is a `Context.Reference` holding the Layer of * exporters to install for every event (fetch, queue, cron, RPC, Durable * Object call, Workflow run, Lambda invoke). The runtime bridges build that * Layer into the event's request scope, so: * * - the exporter's batching fiber runs inside the event's I/O context * (required on workerd, where timers/fetches are pinned to the request), * - buffered spans/logs/metrics are flushed when the request scope * finalizes — registered with `ctx.waitUntil`, so flushing never delays * the response. */ import * as Effect from "effect/Effect"; import * as Layer from "effect/Layer"; import * as Redacted from "effect/Redacted"; import type { Input } from "./Input.ts"; import * as Output from "./Output.ts"; import { CurrentRuntimeContext } from "./RuntimeContext.ts"; import { EXPORTERS_KEY, fromBoundConfig, type ResolvedDestination, type ResolvedSignal, Telemetry, type TelemetryLayer, } from "./TelemetryRuntime.ts"; export { buildEventTelemetry, provideProcessTelemetry, Telemetry, type TelemetryLayer, } from "./TelemetryRuntime.ts"; export { type Destination as RelayDestination, type RelayOptions, relay, type Signal as RelaySignal, } from "./TelemetryRelay.ts"; const reference = Telemetry; /** * Install a custom telemetry Layer (any Layer providing a `Tracer`, * loggers, and/or metric exporters). It is built once per event into the * event's request scope, so scoped exporters flush when the request scope * finalizes. * * Custom layers COMPOSE with the built-in OTLP destinations and with each * other: loggers and metric exporters merge; a custom `Tracer` (a single * Effect service) replaces the built-in one. * * The isolate {@link Telemetry} reference stays the bound OTLP reader. * The custom Layer is stored on `ctx.telemetry` and merged per event as * the override, so `Layer.mergeAll` order with {@link layerOtlp} does not * drop logs/metrics. * * Provide it on the Function/Worker's init Effect (merged into the single * `Effect.provide`): building the returned Layer registers the exporter * Layer on the current runtime context, where the runtime bridges pick it * up per event. Handlers' request-time context is assembled by the bridge, * so a plain `Layer.succeed` of the reference on the init Effect would * never reach them — the registration is what makes it visible at request * time. */ export const layer = (exporter: TelemetryLayer): Layer.Layer => Layer.effect( reference, Effect.gen(function* () { const ctx = yield* CurrentRuntimeContext; if (ctx !== undefined) { ctx.telemetry = ctx.telemetry === undefined ? exporter : Layer.mergeAll(ctx.telemetry, exporter); } return fromBoundConfig; }), ); /** * A header value: a plain string, a `Redacted` secret, or an Output of * either (e.g. an ApiToken's `token` attribute). */ export type OtlpHeaderValue = Input>; /** * OTLP configuration for one signal. `url` and header values accept plain * values or resource Outputs — they are *bound* onto the host at deploy * time like any other binding. */ export interface OtlpSignalOptions { /** The OTLP/HTTP URL exports for this signal are POSTed to. */ url: Input; /** * Headers sent with each export request (e.g. auth tokens). `Redacted` * values bind as secrets. */ headers?: Record | undefined; } /** * Options for {@link layerOtlp}. Configure a base `url` (with * `/v1/{signal}` appended per signal), per-signal urls, or a mix — a * per-signal entry takes precedence over the base. */ export interface OtlpOptions { /** Base OTLP/HTTP URL; `/v1/{traces,logs,metrics}` is appended per signal. */ url?: Input | undefined; /** Headers for every signal; per-signal `headers` take precedence. */ headers?: Record | undefined; traces?: OtlpSignalOptions | undefined; logs?: OtlpSignalOptions | undefined; metrics?: OtlpSignalOptions | undefined; /** * The exported `service.name`. * @default the deployed Function/Worker's physical name */ serviceName?: Input | undefined; } /** * A placeholder in the destinations template pointing at one captured * Input value. */ interface Placeholder { readonly $input: number; } /** * Per-runtime-context accumulator: every `layerOtlp` layer built for * the same host appends its destination here and rebinds the full list, so * merged layers compose instead of clobbering each other. */ const rcDestinations = new WeakMap(); /** * Compose the full destination list into a single Output: capture every * Input (urls, header values) into an `Output.all`, then materialize the * JSON array of {@link ResolvedDestination}. If any captured value is * `Redacted`, the whole JSON binds as a secret. */ const destinationsOutput = ( list: OtlpOptions[], ): Output.Output> => { const inputs: unknown[] = []; const capture = (value: unknown): Placeholder => { inputs.push(value); return { $input: inputs.length - 1 }; }; const captureHeaders = ( headers: Record | undefined, ): Record | undefined => headers === undefined ? undefined : Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, capture(value)])); const template = list.map((options) => ({ url: options.url !== undefined ? capture(options.url) : undefined, headers: captureHeaders(options.headers), traces: options.traces && { url: capture(options.traces.url), headers: captureHeaders(options.traces.headers), }, logs: options.logs && { url: capture(options.logs.url), headers: captureHeaders(options.logs.headers), }, metrics: options.metrics && { url: capture(options.metrics.url), headers: captureHeaders(options.metrics.headers), }, })); return ( Output.all(...inputs.map((input) => Output.asOutput(input as never))) as Output.Output< unknown[] > ).pipe( Output.map((values) => { let secret = false; const resolve = (placeholder: Placeholder): string => { let value = values[placeholder.$input]; if (Redacted.isRedacted(value)) { secret = true; value = Redacted.value(value); } return typeof value === "string" ? value : String(value); }; const resolveHeaders = ( headers: Record | undefined, ): Record | undefined => headers === undefined ? undefined : Object.fromEntries( Object.entries(headers).map(([key, value]) => [key, resolve(value)]), ); const resolveSignal = ( entry: { url: Placeholder; headers?: Record }, base: { url?: Placeholder; headers?: Record }, path: string, ): ResolvedSignal | undefined => { if (entry !== undefined) { return { url: resolve(entry.url), headers: resolveHeaders(entry.headers), }; } if (base.url !== undefined) { return { url: `${resolve(base.url).replace(/\/$/, "")}/v1/${path}`, headers: resolveHeaders(base.headers), }; } return undefined; }; const destinations = template.flatMap((entry): ResolvedDestination[] => { const destination: ResolvedDestination = { traces: resolveSignal(entry.traces as never, entry, "traces"), logs: resolveSignal(entry.logs as never, entry, "logs"), metrics: resolveSignal(entry.metrics as never, entry, "metrics"), }; return destination.traces || destination.logs || destination.metrics ? [destination] : []; }); const json = JSON.stringify(destinations); return secret ? Redacted.make(json) : json; }), ); }; /** * The built-in OTLP exporter as a *binding* layer. * * At deploy time, building this layer binds the configured urls and * headers onto the host Function/Worker (Redacted values as secret * bindings) — url and header values accept resource Outputs, so exporter * config is wired from resources like any other binding. At runtime the * exporter reads the bound values back and ships traces, logs, and metrics * over OTLP/HTTP JSON, flushed as each event's scope closes. * * Exporters COMPOSE: merge several `otlp` layers (or vendor sugar like * `Axiom.Telemetry`) and every destination receives the telemetry — spans * are serialized once, so trace/span ids agree across destinations: * * ```ts * Effect.provide( * Layer.mergeAll( * Cloudflare.R2.ReadWriteBucketBinding, * Axiom.Telemetry({ token: Ingest, traces: Traces, logs: Logs }), * Alchemy.Telemetry.layerOtlp({ * url: "https://api.honeycomb.io", * headers: { "x-honeycomb-team": apiKey }, * }), * ), * ) * ``` */ export const layerOtlp = (options: OtlpOptions): Layer.Layer => Layer.effect( reference, Effect.gen(function* () { const rc = yield* CurrentRuntimeContext; if (rc !== undefined && !globalThis.__ALCHEMY_RUNTIME__) { // Accumulate this destination with any bound by sibling layers on // the same host, and rebind the full list (rebinding the same key // just overwrites, so build order doesn't matter). const list = rcDestinations.get(rc) ?? []; list.push(options); rcDestinations.set(rc, list); yield* rc.set(EXPORTERS_KEY, destinationsOutput(list)); if (options.serviceName !== undefined) { yield* rc.set("OTEL_SERVICE_NAME", Output.asOutput(options.serviceName as never)); } } // The runtime half reads the bound destinations back per event (or // once per process via `provideProcessTelemetry`). return fromBoundConfig; }), );