autotel-cloudflare 2.1.0

package/src/handlers/durable-objects.ts

@@ -0,0 +1,250 @@
+/**
+ * Durable Objects instrumentation for Cloudflare Workers
+ * 
+ * Note: This file uses Cloudflare Workers types (DurableObjectId, DurableObjectState, etc.)
+ * which are globally available via @cloudflare/workers-types when listed in tsconfig.json.
+ * These types are devDependencies only - they're not runtime dependencies.
+ * At runtime, Cloudflare Workers runtime provides the actual implementations.
+ */
+
+import {
+  trace,
+  context as api_context,
+  propagation,
+  SpanStatusCode,
+  SpanKind,
+} from '@opentelemetry/api';
+import type { ConfigurationOption } from 'autotel-edge';
+import { createInitialiser, setConfig, WorkerTracer } from 'autotel-edge';
+import { wrap } from '../bindings/common';
+
+// Durable Object types
+type DOFetchFn = (request: Request) => Response | Promise<Response>;
+type DOAlarmFn = () => void | Promise<void>;
+
+/**
+ * Track cold starts per DO class
+ */
+const coldStarts = new WeakMap<any, boolean>();
+
+function isColdStart(doClass: any): boolean {
+  if (!coldStarts.has(doClass)) {
+    coldStarts.set(doClass, true);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Instrument a Durable Object fetch method
+ */
+function instrumentDOFetch(
+  fetchFn: DOFetchFn,
+  id: DurableObjectId,
+  doClass: any,
+): DOFetchFn {
+  return async function instrumentedFetch(
+    this: any,
+    request: Request,
+  ): Promise<Response> {
+    const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
+
+    // Extract parent context from request headers
+    const parentContext = propagation.extract(
+      api_context.active(),
+      request.headers,
+    );
+
+    const url = new URL(request.url);
+    const spanName = `DO ${id.name || id.toString()}: ${request.method} ${url.pathname}`;
+
+    return tracer.startActiveSpan(
+      spanName,
+      {
+        kind: SpanKind.SERVER,
+        attributes: {
+          'http.request.method': request.method,
+          'url.full': request.url,
+          'do.id': id.toString(),
+          'do.id.name': id.name || '',
+          'faas.trigger': 'http',
+          'faas.coldstart': isColdStart(doClass),
+        },
+      },
+      parentContext,
+      async (span) => {
+        try {
+          const response = await fetchFn.call(this, request);
+
+          span.setAttributes({
+            'http.response.status_code': response.status,
+          });
+
+          if (response.ok) {
+            span.setStatus({ code: SpanStatusCode.OK });
+          } else {
+            span.setStatus({ code: SpanStatusCode.ERROR });
+          }
+
+          return response;
+        } 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 Durable Object alarm method
+ */
+function instrumentDOAlarm(
+  alarmFn: DOAlarmFn,
+  id: DurableObjectId,
+  doClass: any,
+): DOAlarmFn {
+  return async function instrumentedAlarm(this: any): Promise<void> {
+    const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
+
+    const spanName = `DO ${id.name || id.toString()}: alarm`;
+
+    return tracer.startActiveSpan(
+      spanName,
+      {
+        kind: SpanKind.INTERNAL,
+        attributes: {
+          'do.id': id.toString(),
+          'do.id.name': id.name || '',
+          'faas.trigger': 'timer',
+          'faas.coldstart': isColdStart(doClass),
+        },
+      },
+      async (span) => {
+        try {
+          await alarmFn.call(this);
+          span.setStatus({ code: SpanStatusCode.OK });
+        } 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 Durable Object instance
+ */
+function instrumentDOInstance(
+  doInstance: any,
+  state: DurableObjectState,
+  _env: any,
+  doClass: any,
+): any {
+  const instanceHandler: ProxyHandler<any> = {
+    get(target, prop) {
+      const value = Reflect.get(target, prop);
+
+      if (prop === 'fetch' && typeof value === 'function') {
+        return instrumentDOFetch(value.bind(target), state.id, doClass);
+      }
+
+      if (prop === 'alarm' && typeof value === 'function') {
+        return instrumentDOAlarm(value.bind(target), state.id, doClass);
+      }
+
+      // Bind other methods to the target
+      if (typeof value === 'function') {
+        return value.bind(target);
+      }
+
+      return value;
+    },
+  };
+
+  return wrap(doInstance, instanceHandler);
+}
+
+/**
+ * Instrument a Durable Object class
+ *
+ * This wraps the DO class to automatically trace all fetch and alarm calls,
+ * as well as initialize the telemetry configuration.
+ *
+ * **Usage:**
+ * ```typescript
+ * import { DurableObject } from 'cloudflare:workers'
+ * import { instrumentDO } from 'autotel-edge'
+ *
+ * export class Counter extends DurableObject<Env> {
+ *   async fetch(request: Request) {
+ *     // Your DO logic here
+ *     return new Response('OK')
+ *   }
+ * }
+ *
+ * // Wrap the class before exporting
+ * export const CounterDO = instrumentDO(Counter, (env: Env) => ({
+ *   exporter: {
+ *     url: env.OTLP_ENDPOINT,
+ *     headers: { 'x-api-key': env.API_KEY }
+ *   },
+ *   service: {
+ *     name: 'my-durable-object',
+ *     version: '1.0.0'
+ *   }
+ * }))
+ * ```
+ *
+ * **What you get:**
+ * - 🎯 Automatic spans for fetch() calls with HTTP attributes
+ * - ⏰ Automatic spans for alarm() calls
+ * - 🥶 Cold start tracking
+ * - 🔗 Context propagation from incoming requests
+ * - ⚡ Automatic span lifecycle management
+ *
+ * @param doClass - The Durable Object class to instrument
+ * @param config - Configuration or configuration function
+ * @returns Instrumented Durable Object class
+ */
+export function instrumentDO<C extends new (state: DurableObjectState, env: any) => any>(
+  doClass: C,
+  config: ConfigurationOption,
+): C {
+  const initialiser = createInitialiser(config);
+
+  const classHandler: ProxyHandler<C> = {
+    construct(target, [state, env]: [DurableObjectState, any]) {
+      // Initialize config for this DO instance
+      const trigger = {
+        id: state.id.toString(),
+        name: state.id.name,
+      };
+      const doConfig = initialiser(env, trigger);
+      const context = setConfig(doConfig);
+
+      // Create the DO instance within the config context
+      const doInstance = api_context.with(context, () => {
+        return new target(state, env);
+      });
+
+      // Instrument the instance
+      return instrumentDOInstance(doInstance, state, env, doClass);
+    },
+  };
+
+  return wrap(doClass, classHandler);
+}

package/src/handlers/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Handler instrumentation for Cloudflare Workers
+ */
+
+export { instrumentDO } from './durable-objects';
+export { instrumentWorkflow } from './workflows';

package/src/handlers/workflows.ts

@@ -0,0 +1,318 @@
+/**
+ * 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 { ConfigurationOption } from 'autotel-edge';
+import { createInitialiser, setConfig, WorkerTracer } from 'autotel-edge';
+import { wrap } from '../bindings/common';
+
+// Workflow types (these would come from @cloudflare/workers-types when available)
+type WorkflowEvent = any;
+type WorkflowStep = any;
+
+type WorkflowRunFn = (
+  event: WorkflowEvent,
+  step: WorkflowStep,
+) => Promise<void> | void;
+
+/**
+ * Track cold starts per Workflow class
+ */
+const coldStarts = new WeakMap<any, boolean>();
+
+function isColdStart(workflowClass: any): boolean {
+  if (!coldStarts.has(workflowClass)) {
+    coldStarts.set(workflowClass, true);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Proxy the step object to instrument step.do() 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, () => Promise<any>];
+
+            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();
+                }
+              },
+            );
+          },
+        });
+      }
+
+      // 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: any,
+): WorkflowRunFn {
+  return async function instrumentedRun(
+    this: any,
+    event: WorkflowEvent,
+    step: WorkflowStep,
+  ): Promise<void> {
+    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,
+          'faas.trigger': 'workflow',
+          'faas.coldstart': isColdStart(workflowClass),
+          // Add workflow event attributes if available
+          ...(event?.workflowId && { 'workflow.id': event.workflowId }),
+          ...(event?.runId && { 'workflow.run_id': event.runId }),
+        },
+      },
+      async (span) => {
+        try {
+          await runFn.call(this, event, instrumentedStep);
+          span.setStatus({ code: SpanStatusCode.OK });
+        } 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: any,
+  workflowName: string,
+  workflowClass: any,
+): any {
+  const instanceHandler: ProxyHandler<any> = {
+    get(target, prop) {
+      const value = Reflect.get(target, prop);
+
+      if (prop === 'run' && typeof value === 'function') {
+        return instrumentWorkflowRun(
+          value.bind(target),
+          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-edge'
+ *
+ * export class CheckoutWorkflow extends WorkflowEntrypoint {
+ *   async run(event, step) {
+ *     await step.do('submit payment', async () => {
+ *       return await submitToPaymentProcessor(event.params.payment)
+ *     })
+ *
+ *     await step.sleep('wait for feedback', '2 days')
+ *
+ *     await step.do('send feedback email', sendFeedbackEmail)
+ *   }
+ * }
+ *
+ * // Wrap the class before exporting
+ * export const CheckoutWorkflowInstrumented = instrumentWorkflow(
+ *   CheckoutWorkflow,
+ *   'checkout-workflow',
+ *   (env: Env) => ({
+ *     exporter: {
+ *       url: env.OTLP_ENDPOINT,
+ *       headers: { 'x-api-key': env.API_KEY }
+ *     },
+ *     service: {
+ *       name: 'checkout-workflow',
+ *       version: '1.0.0'
+ *     }
+ *   })
+ * )
+ * ```
+ *
+ * **What you get:**
+ * - 🎯 Automatic spans for workflow.run() execution
+ * - 📋 Automatic spans for each step.do() operation
+ * - ⏸️ Automatic spans for step.sleep() operations
+ * - 🔄 Automatic retry tracking (via step.do retries)
+ * - 🥶 Cold start tracking
+ * - ⚡ Automatic span lifecycle management
+ *
+ * @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] || {};
+
+      // Initialize config for this workflow instance
+      // Use Request as trigger type since workflows don't have a standard Trigger type yet
+      const trigger = new Request('https://workflow.local/run');
+      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

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

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * 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';
+
+// Cloudflare-specific wrappers
+export { instrument, wrapModule, wrapDurableObject } from './wrappers';
+
+// Cloudflare-specific handlers
+export { instrumentDO, instrumentWorkflow } from './handlers';
+
+// Cloudflare-specific bindings
+export {
+  instrumentKV,
+  instrumentR2,
+  instrumentD1,
+  instrumentServiceBinding,
+  instrumentBindings,
+} from './bindings';
+
+// Global instrumentations
+export { instrumentGlobalFetch, instrumentGlobalCache } from './global';

package/src/logger.ts

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

package/src/sampling.ts

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

package/src/testing.ts

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

package/src/wrappers/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Wrapper APIs for Cloudflare Workers
+ * Provides multiple API styles for maximum flexibility
+ */
+
+export { instrument } from './instrument';
+export { wrapModule } from './wrap-module';
+export { wrapDurableObject } from './wrap-do';