autotel-cloudflare/dist/handlers.d.ts

The #1 OpenTelemetry package for Cloudflare Workers - complete bindings coverage, native CF OTel integration, advanced sampling

import { ConfigurationOption } from 'autotel-edge';

/**
 * 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.
 */

/**
 * 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
 */
declare function instrumentDO<C extends new (state: DurableObjectState, env: any) => any>(doClass: C, config: ConfigurationOption): C;

/**
 * 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/
 */

/**
 * 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
 */
declare function instrumentWorkflow<C extends new (...args: any[]) => any>(workflowClass: C, workflowName: string, config: ConfigurationOption): C;

export { instrumentDO, instrumentWorkflow };