autotel-cloudflare 3.0.0 → 4.0.0

package/src/handlers/workflows.ts

@@ -1,345 +0,0 @@
-/**
- * Cloudflare Workflows instrumentation for autotel-edge
- *
- * Instruments WorkflowEntrypoint classes to automatically trace workflow execution,
- * step operations, retries, and sleeps.
- *
- * Based on Cloudflare Workflows API:
- * https://developers.cloudflare.com/workflows/
- */
-
-import {
-  trace,
-  context as api_context,
-  SpanStatusCode,
-  SpanKind,
-} from '@opentelemetry/api';
-import type { WorkflowEvent, WorkflowStep } from 'cloudflare:workers';
-import type { ConfigurationOption, WorkflowTrigger } from 'autotel-edge';
-import { createInitialiser, setConfig, WorkerTracer } from 'autotel-edge';
-import { wrap } from '../bindings/common';
-
-type WorkflowRunFn = (
-  event: Readonly<WorkflowEvent<unknown>>,
-  step: WorkflowStep,
-) => Promise<unknown> | void;
-
-/**
- * Track cold starts per Workflow class
- */
-const coldStarts = new WeakMap<object, boolean>();
-
-function isColdStart(workflowClass: object): boolean {
-  if (!coldStarts.has(workflowClass)) {
-    coldStarts.set(workflowClass, true);
-    return true;
-  }
-  return false;
-}
-
-/**
- * Proxy the step object to instrument step.do(), step.sleep(), and step.sleepUntil() calls
- */
-function instrumentWorkflowStep(
-  step: WorkflowStep,
-  workflowName: string,
-): WorkflowStep {
-  const stepHandler: ProxyHandler<WorkflowStep> = {
-    get(target, prop) {
-      const value = Reflect.get(target, prop);
-
-      // Instrument step.do() to create spans for each workflow step
-      if (prop === 'do' && typeof value === 'function') {
-        return new Proxy(value, {
-          apply: (fnTarget, thisArg, args) => {
-            const [stepName] = args as [string, ...unknown[]];
-
-            const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
-
-            return tracer.startActiveSpan(
-              `Workflow ${workflowName}: ${stepName}`,
-              {
-                kind: SpanKind.INTERNAL,
-                attributes: {
-                  'workflow.step.name': stepName,
-                  'workflow.name': workflowName,
-                },
-              },
-              async (span) => {
-                try {
-                  const result = await Reflect.apply(fnTarget, thisArg, args);
-                  span.setStatus({ code: SpanStatusCode.OK });
-                  return result;
-                } catch (error) {
-                  span.recordException(error as Error);
-                  span.setStatus({
-                    code: SpanStatusCode.ERROR,
-                    message:
-                      error instanceof Error ? error.message : String(error),
-                  });
-                  throw error;
-                } finally {
-                  span.end();
-                }
-              },
-            );
-          },
-        });
-      }
-
-      // Instrument step.sleep() to track workflow delays
-      if (prop === 'sleep' && typeof value === 'function') {
-        return new Proxy(value, {
-          apply: (fnTarget, thisArg, args) => {
-            const [sleepName, duration] = args as [string, string | number];
-
-            const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
-
-            return tracer.startActiveSpan(
-              `Workflow ${workflowName}: sleep ${sleepName}`,
-              {
-                kind: SpanKind.INTERNAL,
-                attributes: {
-                  'workflow.sleep.name': sleepName,
-                  'workflow.sleep.duration': String(duration),
-                  'workflow.name': workflowName,
-                },
-              },
-              async (span) => {
-                try {
-                  const result = await Reflect.apply(fnTarget, thisArg, args);
-                  span.setStatus({ code: SpanStatusCode.OK });
-                  return result;
-                } catch (error) {
-                  span.recordException(error as Error);
-                  span.setStatus({
-                    code: SpanStatusCode.ERROR,
-                    message:
-                      error instanceof Error ? error.message : String(error),
-                  });
-                  throw error;
-                } finally {
-                  span.end();
-                }
-              },
-            );
-          },
-        });
-      }
-
-      if (prop === 'sleepUntil' && typeof value === 'function') {
-        return new Proxy(value, {
-          apply: (fnTarget, thisArg, args) => {
-            const [sleepName, timestamp] = args as [string, Date | number];
-
-            const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
-            const wakeAt =
-              timestamp instanceof Date
-                ? timestamp.toISOString()
-                : new Date(timestamp).toISOString();
-
-            return tracer.startActiveSpan(
-              `Workflow ${workflowName}: sleepUntil ${sleepName}`,
-              {
-                kind: SpanKind.INTERNAL,
-                attributes: {
-                  'workflow.sleep.name': sleepName,
-                  'workflow.sleep.until': wakeAt,
-                  'workflow.name': workflowName,
-                },
-              },
-              async (span) => {
-                try {
-                  const result = await Reflect.apply(fnTarget, thisArg, args);
-                  span.setStatus({ code: SpanStatusCode.OK });
-                  return result;
-                } catch (error) {
-                  span.recordException(error as Error);
-                  span.setStatus({
-                    code: SpanStatusCode.ERROR,
-                    message:
-                      error instanceof Error ? error.message : String(error),
-                  });
-                  throw error;
-                } finally {
-                  span.end();
-                }
-              },
-            );
-          },
-        });
-      }
-
-      // Pass through other step methods
-      if (typeof value === 'function') {
-        return value.bind(target);
-      }
-
-      return value;
-    },
-  };
-
-  return wrap(step, stepHandler);
-}
-
-/**
- * Instrument a Workflow run method
- */
-function instrumentWorkflowRun(
-  runFn: WorkflowRunFn,
-  workflowName: string,
-  workflowClass: object,
-): WorkflowRunFn {
-  return async function instrumentedRun(
-    this: unknown,
-    event: Readonly<WorkflowEvent<unknown>>,
-    step: WorkflowStep,
-  ): Promise<unknown> {
-    const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
-
-    // Instrument the step object to track individual operations
-    const instrumentedStep = instrumentWorkflowStep(step, workflowName);
-
-    const spanName = `Workflow ${workflowName}: run`;
-
-    return tracer.startActiveSpan(
-      spanName,
-      {
-        kind: SpanKind.INTERNAL,
-        attributes: {
-          'workflow.name': workflowName,
-          'workflow.instance_id': event.instanceId,
-          'faas.trigger': 'workflow',
-          'faas.coldstart': isColdStart(workflowClass),
-        },
-      },
-      async (span) => {
-        try {
-          const result = await runFn.call(this, event, instrumentedStep);
-          span.setStatus({ code: SpanStatusCode.OK });
-          return result;
-        } catch (error) {
-          span.recordException(error as Error);
-          span.setStatus({
-            code: SpanStatusCode.ERROR,
-            message: error instanceof Error ? error.message : String(error),
-          });
-          throw error;
-        } finally {
-          span.end();
-        }
-      },
-    );
-  };
-}
-
-/**
- * Instrument a Workflow instance
- */
-function instrumentWorkflowInstance(
-  workflowInstance: Record<string, unknown>,
-  workflowName: string,
-  workflowClass: object,
-): Record<string, unknown> {
-  const instanceHandler: ProxyHandler<Record<string, unknown>> = {
-    get(target, prop) {
-      const value = Reflect.get(target, prop);
-
-      if (prop === 'run' && typeof value === 'function') {
-        return instrumentWorkflowRun(
-          value.bind(target) as WorkflowRunFn,
-          workflowName,
-          workflowClass,
-        );
-      }
-
-      // Bind other methods to the target
-      if (typeof value === 'function') {
-        return value.bind(target);
-      }
-
-      return value;
-    },
-  };
-
-  return wrap(workflowInstance, instanceHandler);
-}
-
-/**
- * Instrument a Cloudflare Workflow class
- *
- * This wraps the WorkflowEntrypoint class to automatically trace workflow execution,
- * step operations, retries, and sleeps.
- *
- * **Usage:**
- * ```typescript
- * import { WorkflowEntrypoint } from 'cloudflare:workers'
- * import { instrumentWorkflow } from 'autotel-cloudflare/handlers'
- *
- * class MyWorkflow extends WorkflowEntrypoint {
- *   async run(event, step) {
- *     await step.do('submit payment', async () => {
- *       return await submitToPaymentProcessor(event.payload.payment)
- *     })
- *
- *     await step.sleep('wait for feedback', '2 days')
- *
- *     await step.do('send feedback email', sendFeedbackEmail)
- *   }
- * }
- *
- * export const CheckoutWorkflow = instrumentWorkflow(
- *   MyWorkflow,
- *   'checkout-workflow',
- *   (env: Env) => ({
- *     exporter: {
- *       url: env.OTLP_ENDPOINT,
- *       headers: { 'x-api-key': env.API_KEY }
- *     },
- *     service: {
- *       name: 'checkout-workflow',
- *       version: '1.0.0'
- *     }
- *   })
- * )
- * ```
- *
- * @param workflowClass - The WorkflowEntrypoint class to instrument
- * @param workflowName - The name of the workflow (used in span names)
- * @param config - Configuration or configuration function
- * @returns Instrumented Workflow class
- */
-export function instrumentWorkflow<
-  C extends new (...args: any[]) => any,
->(
-  workflowClass: C,
-  workflowName: string,
-  config: ConfigurationOption,
-): C {
-  const initialiser = createInitialiser(config);
-
-  const classHandler: ProxyHandler<C> = {
-    construct(target, args: any[]) {
-      // Extract env from constructor args (typically last arg)
-      const env = args[args.length - 1] || {};
-
-      const trigger: WorkflowTrigger = { type: 'workflow', name: workflowName };
-      const workflowConfig = initialiser(env, trigger);
-      const context = setConfig(workflowConfig);
-
-      // Create the workflow instance within the config context
-      const workflowInstance = api_context.with(context, () => {
-        return new target(...args);
-      });
-
-      // Instrument the instance
-      return instrumentWorkflowInstance(
-        workflowInstance,
-        workflowName,
-        workflowClass,
-      );
-    },
-  };
-
-  return wrap(workflowClass, classHandler);
-}

package/src/handlers.ts

@@ -1,6 +0,0 @@
-/**
- * Handler instrumentation entry point
- * Entry point: autotel-cloudflare/handlers
- */
-
-export * from './handlers/index';

package/src/index.ts

@@ -1,91 +0,0 @@
-/**
- * autotel-cloudflare
- *
- * The #1 OpenTelemetry package for Cloudflare Workers
- *
- * Features:
- * - Native Cloudflare OTel integration (works with wrangler.toml destinations)
- * - Complete bindings coverage (KV, R2, D1, DO, AI, Vectorize, etc.)
- * - Multiple API styles (instrument, wrapModule, functional)
- * - Advanced sampling strategies
- * - Events integration
- * - Zero vendor lock-in (OTLP compatible)
- *
- * @example Quick Start
- * ```typescript
- * import { wrapModule, trace } from 'autotel-cloudflare'
- *
- * const processOrder = trace(async (orderId: string) => {
- *   const order = await env.ORDERS_KV.get(orderId)
- *   return order
- * })
- *
- * export default wrapModule(
- *   {
- *     service: { name: 'my-worker' },
- *     instrumentBindings: true,
- *     sampling: 'adaptive'
- *   },
- *   {
- *     async fetch(req, env, ctx) {
- *       return Response.json(await processOrder('123'))
- *     }
- *   }
- * )
- * ```
- */
-
-// Re-export EVERYTHING from autotel-edge (vendor-agnostic foundation)
-export * from 'autotel-edge';
-export {
-  getRequestLogger,
-  getQueueLogger,
-  getWorkflowLogger,
-  getActorLogger,
-  createWorkersLogger,
-  type ExecutionLogger,
-  type ExecutionLoggerOptions,
-  type ExecutionLogSnapshot,
-  type WorkersLoggerOptions,
-} from './execution-logger';
-
-// Cloudflare-specific wrappers
-export {
-  instrument,
-  wrapModule,
-  wrapDurableObject,
-  defineWorkerFetch,
-  type DefineWorkerFetchOptions,
-  type WorkerFetchHandler,
-} from './wrappers';
-
-// Cloudflare-specific handlers
-export { instrumentDO, instrumentWorkflow } from './handlers';
-
-// Cloudflare-specific bindings
-export {
-  instrumentKV,
-  instrumentR2,
-  instrumentD1,
-  instrumentServiceBinding,
-  instrumentBindings,
-  instrumentAI,
-  instrumentVectorize,
-  instrumentHyperdrive,
-  instrumentQueueProducer,
-  instrumentAnalyticsEngine,
-  instrumentImages,
-  instrumentRateLimiter,
-  instrumentBrowserRendering,
-} from './bindings';
-
-// Global instrumentations
-export { instrumentGlobalFetch, instrumentGlobalCache } from './global';
-
-// Cloudflare native tracing helpers (auto-wired by the handler wrappers;
-// exported for manual detection). `enterSpan` is re-exported from autotel-edge
-// above via `export * from 'autotel-edge'`.
-export {
-  isNativeTracingAvailable,
-  getNativeTracerFromCtx,
-} from './native/native-tracing';

package/src/logger.ts

@@ -1,15 +0,0 @@
-/**
- * Logger entry point
- * Entry point: autotel-cloudflare/logger
- */
-
-export * from 'autotel-edge/logger';
-export {
-  getRequestLogger,
-  getQueueLogger,
-  getWorkflowLogger,
-  getActorLogger,
-  type ExecutionLogger,
-  type ExecutionLoggerOptions,
-  type ExecutionLogSnapshot,
-} from './execution-logger';

package/src/native/native-tracing.test.ts

@@ -1,54 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import {
-  isNativeTracingAvailable,
-  getNativeTracerFromCtx,
-} from './native-tracing';
-
-function ctxWithTracing() {
-  const enterSpan = vi.fn((_name: string, cb: (s: any) => unknown) =>
-    cb({ isTraced: true, setAttribute: vi.fn() }),
-  );
-  return { tracing: { enterSpan }, waitUntil() {}, passThroughOnException() {} };
-}
-
-describe('isNativeTracingAvailable', () => {
-  it('is true when ctx.tracing.enterSpan is a function', () => {
-    expect(isNativeTracingAvailable(ctxWithTracing())).toBe(true);
-  });
-
-  it('is false for a plain ExecutionContext (tracing disabled / old runtime)', () => {
-    expect(isNativeTracingAvailable({ waitUntil() {} })).toBe(false);
-  });
-
-  it('is false for null/undefined or malformed tracing', () => {
-    expect(isNativeTracingAvailable(undefined)).toBe(false);
-    expect(isNativeTracingAvailable(null)).toBe(false);
-    expect(isNativeTracingAvailable({ tracing: {} })).toBe(false);
-    expect(isNativeTracingAvailable({ tracing: { enterSpan: 123 } })).toBe(false);
-  });
-});
-
-describe('getNativeTracerFromCtx', () => {
-  it('returns null when native tracing is unavailable', () => {
-    expect(getNativeTracerFromCtx({ waitUntil() {} })).toBeNull();
-  });
-
-  it('wraps ctx.tracing.enterSpan as a NativeTracer', () => {
-    const ctx = ctxWithTracing();
-    const tracer = getNativeTracerFromCtx(ctx);
-    expect(tracer).not.toBeNull();
-
-    const result = tracer!.enterSpan('work', (span) => {
-      span.setAttribute('k', 'v');
-      return 7;
-    });
-
-    expect(result).toBe(7);
-    expect(ctx.tracing.enterSpan).toHaveBeenCalledWith('work', expect.any(Function));
-  });
-
-  it('attaches the supplied correlation id to the tracer', () => {
-    const tracer = getNativeTracerFromCtx(ctxWithTracing(), 'ray-xyz');
-    expect(tracer?.correlationId).toBe('ray-xyz');
-  });
-});

package/src/native/native-tracing.ts

@@ -1,83 +0,0 @@
-/**
- * Cloudflare native tracing adapter
- *
- * Bridges Cloudflare Workers' built-in custom-span API
- * (`ctx.tracing.enterSpan()` / `import { tracing } from "cloudflare:workers"`)
- * to autotel-edge's runtime-agnostic {@link NativeTracer} seam.
- *
- * When a Worker has tracing enabled (`observability.traces.enabled = true` in
- * Wrangler) the runtime exposes `ctx.tracing`. The handler wrappers detect it,
- * wrap it as a {@link NativeTracer}, and install it into the active context with
- * `withNativeTracer()`. From then on every autotel `span()` / `trace()` /
- * `enterSpan()` call — including deep inside utility functions and libraries —
- * automatically routes to Cloudflare's native tracer and nests inside the
- * platform's trace waterfall (fetch / KV / R2 / D1 / handler spans), exported
- * by Cloudflare to whichever destination is configured in Wrangler.
- *
- * No `cloudflare:workers` import is required here: the native tracer travels
- * through autotel's AsyncLocalStorage context, so code without access to `ctx`
- * still picks it up via `getActiveNativeTracer()`.
- */
-
-import type { NativeTracer, NativeSpanHandle } from 'autotel-edge';
-
-/**
- * Cloudflare's native custom-span surface. Declared locally because it is not
- * yet present in `@cloudflare/workers-types`. Structurally compatible with
- * autotel-edge's {@link NativeSpanHandle}.
- */
-interface CloudflareSpan {
-  readonly isTraced: boolean;
-  setAttribute(key: string, value: string | number | boolean | undefined): void;
-}
-
-/**
- * Cloudflare's `tracing` object, available as `ctx.tracing` on the
- * ExecutionContext and as the `tracing` export of `cloudflare:workers`.
- */
-interface CloudflareTracing {
-  enterSpan<T, A extends unknown[]>(
-    name: string,
-    callback: (span: CloudflareSpan, ...args: A) => T,
-    ...args: A
-  ): T;
-}
-
-type MaybeTracingCarrier = { tracing?: CloudflareTracing } | null | undefined;
-
-function readTracing(carrier: unknown): CloudflareTracing | undefined {
-  const tracing = (carrier as MaybeTracingCarrier)?.tracing;
-  return typeof tracing?.enterSpan === 'function' ? tracing : undefined;
-}
-
-/**
- * Returns `true` when Cloudflare native custom-span tracing is available on the
- * given ExecutionContext (i.e. tracing is enabled for this Worker).
- */
-export function isNativeTracingAvailable(ctx: unknown): boolean {
-  return readTracing(ctx) !== undefined;
-}
-
-/**
- * Wrap Cloudflare's `ctx.tracing` as an autotel {@link NativeTracer}, or return
- * `null` when native tracing is unavailable on this context.
- *
- * @param correlationId Optional per-request id (e.g. the `cf-ray` header)
- * surfaced as `ctx.correlationId` and a `correlation.id` span attribute, so
- * logs, custom spans, and the Cloudflare dashboard share one queryable key
- * today — before Cloudflare exposes in-code trace/span ids.
- */
-export function getNativeTracerFromCtx(
-  ctx: unknown,
-  correlationId?: string,
-): NativeTracer | null {
-  const tracing = readTracing(ctx);
-  if (!tracing) {
-    return null;
-  }
-  return {
-    correlationId,
-    enterSpan: <T>(name: string, callback: (span: NativeSpanHandle) => T): T =>
-      tracing.enterSpan(name, callback as (span: CloudflareSpan) => T),
-  };
-}

package/src/native.ts

@@ -1,12 +0,0 @@
-/**
- * autotel-cloudflare/native
- *
- * Cloudflare native tracing helpers. Most users never need this entry point —
- * the handler wrappers (`instrument`, `wrapModule`, `defineWorkerFetch`,
- * `wrapDurableObject`) auto-detect and wire up native tracing for you. Import
- * from here only when you want to detect native tracing yourself.
- */
-export {
-  isNativeTracingAvailable,
-  getNativeTracerFromCtx,
-} from './native/native-tracing';

package/src/parse-error.ts

@@ -1 +0,0 @@
-export { parseError, type ParsedError } from 'autotel-edge/parse-error';

package/src/sampling.ts

@@ -1,6 +0,0 @@
-/**
- * Sampling strategies entry point (re-export from autotel-edge)
- * Entry point: autotel-cloudflare/sampling
- */
-
-export * from 'autotel-edge/sampling';

package/src/testing.ts

@@ -1,6 +0,0 @@
-/**
- * Testing utilities entry point (re-export from autotel-edge)
- * Entry point: autotel-cloudflare/testing
- */
-
-export * from 'autotel-edge/testing';