sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ Telemetry.ts

/**
 * 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<never> =>
  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<string | Redacted.Redacted<string>>;

/**
 * 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<string>;
  /**
   * Headers sent with each export request (e.g. auth tokens). `Redacted`
   * values bind as secrets.
   */
  headers?: Record<string, OtlpHeaderValue> | 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<string> | undefined;
  /** Headers for every signal; per-signal `headers` take precedence. */
  headers?: Record<string, OtlpHeaderValue> | undefined;
  traces?: OtlpSignalOptions | undefined;
  logs?: OtlpSignalOptions | undefined;
  metrics?: OtlpSignalOptions | undefined;
  /**
   * The exported `service.name`.
   * @default the deployed Function/Worker's physical name
   */
  serviceName?: Input<string> | 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<object, OtlpOptions[]>();

/**
 * 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<string | Redacted.Redacted<string>> => {
  const inputs: unknown[] = [];
  const capture = (value: unknown): Placeholder => {
    inputs.push(value);
    return { $input: inputs.length - 1 };
  };
  const captureHeaders = (
    headers: Record<string, OtlpHeaderValue> | undefined,
  ): Record<string, Placeholder> | 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<string, Placeholder> | undefined,
      ): Record<string, string> | undefined =>
        headers === undefined
          ? undefined
          : Object.fromEntries(
              Object.entries(headers).map(([key, value]) => [key, resolve(value)]),
            );
      const resolveSignal = (
        entry: { url: Placeholder; headers?: Record<string, Placeholder> },
        base: { url?: Placeholder; headers?: Record<string, Placeholder> },
        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<never> =>
  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;
    }),
  );