sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Workers/ CloudflareTracer.ts

/**
 * Effect Tracer that mirrors `Effect.withSpan` / `Effect.fn` spans into
 * Cloudflare Workers Observability via `tracing.startActiveSpan`.
 *
 * Built once per event (see {@link Telemetry} + `buildEventTelemetry`).
 * Captures the invocation's async context; do not cache the built Tracer
 * across requests. Not exported from the Cloudflare barrel.
 */
import { AsyncLocalStorage } from "node:async_hooks";
import * as Cause from "effect/Cause";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Tracer from "effect/Tracer";
import cloudflare_workers from "./cloudflare_workers.ts";

type SpanOptions = Parameters<Tracer.Tracer["span"]>[0];
type RunInContext = ReturnType<typeof AsyncLocalStorage.snapshot>;
type CloudflareSpan = ReturnType<(typeof import("cloudflare:workers"))["tracing"]["startSpan"]>;

class Span extends Tracer.NativeSpan {
  constructor(
    options: SpanOptions,
    readonly runInContext: RunInContext,
    readonly cloudflareSpan?: CloudflareSpan,
  ) {
    // Cascade Cloudflare's decision: an untraced invocation (`isTraced`
    // false — e.g. traces disabled; head sampling is applied later, at
    // ingestion) or a runtime without the API marks the Effect span
    // unsampled, so descendants skip `startActiveSpan` entirely.
    super({
      ...options,
      sampled: options.sampled && (cloudflareSpan?.isTraced ?? false),
    });
  }

  override attribute(key: string, value: unknown): void {
    super.attribute(key, value);
    if (Predicate.isString(value) || Predicate.isNumber(value) || Predicate.isBoolean(value)) {
      this.cloudflareSpan?.setAttribute(key, value);
    }
  }

  override end(endTime: bigint, exit: Exit.Exit<unknown, unknown>): void {
    super.end(endTime, exit);
    const outcome = Exit.isSuccess(exit)
      ? "success"
      : Cause.hasInterruptsOnly(exit.cause)
        ? "interrupted"
        : "failure";
    this.cloudflareSpan?.setAttribute("effect.exit", outcome);
    // Only a failure (or defect) is an error. Success and pure interruption
    // stay `unset`: `ok` is final in Cloudflare, so the tracer never claims
    // it, and a cancellation is not an application error.
    if (Exit.isFailure(exit) && outcome === "failure") {
      this.cloudflareSpan?.setStatus({
        code: "error",
        message: Cause.prettyErrors(exit.cause)[0]?.message,
      });
    }
    this.cloudflareSpan?.end();
  }
}

/**
 * Per-event Tracer Layer. Cloudflare owns sampling and export; scalar
 * attributes are forwarded; events, links, and non-scalars stay
 * Effect-local. Completion is recorded as `effect.exit`, and a failure also
 * sets the span status to `error`. Effect trace/span IDs are independent
 * of Cloudflare's opaque IDs.
 */
export const layer: Layer.Layer<never> = Layer.effect(
  Tracer.Tracer,
  Effect.gen(function* () {
    // `tracing` only exists on compatibility dates >= 2026-07-28. Deploy
    // already rejects older dates (`assertCloudflareTelemetryCompatibility`),
    // so a missing API here (an old local workerd) just keeps spans
    // Effect-local.
    const { tracing } = yield* cloudflare_workers;
    const invocationContext = AsyncLocalStorage.snapshot();
    const contextFor = (span: Tracer.AnySpan | undefined): RunInContext => {
      while (span?._tag === "Span") {
        if (span instanceof Span) return span.runInContext;
        span = Option.getOrUndefined(span.parent);
      }
      return invocationContext;
    };

    return Tracer.make({
      span(options) {
        const parentContext = options.root
          ? invocationContext
          : contextFor(Option.getOrUndefined(options.parent));

        if (!options.sampled || tracing?.startActiveSpan === undefined) {
          return new Span(options, parentContext);
        }

        return parentContext(() =>
          tracing.startActiveSpan(
            options.name,
            (span) => new Span(options, AsyncLocalStorage.snapshot(), span),
          ),
        );
      },
      context(primitive, fiber) {
        return contextFor(fiber.cache.span)(() => primitive["~effect/Effect/evaluate"](fiber));
      },
    });
  }),
);