autotel-cloudflare/dist/index.d.ts

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

import { ConfigurationOption } from 'autotel-edge';
export * from 'autotel-edge';
import { W as WorkersLoggerOptions } from './logger-Cm_73k3-.js';
export { c as createWorkersLogger, g as getActorLogger, a as getQueueLogger, b as getRequestLogger, d as getWorkflowLogger } from './logger-Cm_73k3-.js';
import { ExecutionLogger } from 'autotel-edge/logger';
export { ExecutionLogSnapshot, ExecutionLogger, ExecutionLoggerOptions } from 'autotel-edge/logger';
export { instrumentDO, instrumentWorkflow } from './handlers.js';
export { instrumentAI, instrumentAnalyticsEngine, instrumentBindings, instrumentBrowserRendering, instrumentD1, instrumentHyperdrive, instrumentImages, instrumentKV, instrumentQueueProducer, instrumentR2, instrumentRateLimiter, instrumentServiceBinding, instrumentVectorize } from './bindings.js';

/**
 * Handler instrumentation for Cloudflare Workers
 *
 * Note: This file uses Cloudflare Workers types (ExportedHandler, Request, Response, 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.
 *
 * Provides automatic OpenTelemetry tracing for:
 * - HTTP handlers (fetch)
 * - Scheduled/cron handlers
 * - Queue handlers (with message tracking)
 * - Email handlers
 * - Auto-instrumentation of Cloudflare bindings (KV, R2, D1, Service Bindings)
 * - Global fetch and cache instrumentation
 * - Post-processor support for span customization
 * - Tail sampling support
 * - Cold start tracking
 */

/**
 * Instrument a Cloudflare Workers handler
 *
 * @example
 * ```typescript
 * import { instrument } from 'autotel-edge'
 *
 * const handler = {
 *   async fetch(request, env, ctx) {
 *     return new Response('Hello World')
 *   }
 * }
 *
 * export default instrument(handler, {
 *   exporter: {
 *     url: env.OTLP_ENDPOINT,
 *     headers: { 'x-api-key': env.API_KEY }
 *   },
 *   service: { name: 'my-worker' }
 * })
 * ```
 */
declare function instrument<E, Q = any, C = any>(handler: ExportedHandler<E, Q, C>, config: ConfigurationOption): ExportedHandler<E, Q, C>;

/**
 * workers-honeycomb-logger style wrapper API
 *
 * @example
 * ```typescript
 * import { wrapModule } from 'autotel-cloudflare'
 *
 * const handler = {
 *   async fetch(req, env, ctx) {
 *     return new Response('Hello')
 *   }
 * }
 *
 * export default wrapModule(
 *   { service: { name: 'my-worker' } },
 *   handler
 * )
 * ```
 */

/**
 * Wrap a Cloudflare Workers module-style handler
 * Alternative API style inspired by workers-honeycomb-logger
 *
 * @param config Configuration (can be static object or function)
 * @param handler The worker handler to wrap
 * @returns Instrumented handler
 */
declare function wrapModule<E, Q = any, C = any>(config: ConfigurationOption, handler: ExportedHandler<E, Q, C>): ExportedHandler<E, Q, C>;

/**
 * Durable Object wrapper
 *
 * @example
 * ```typescript
 * import { wrapDurableObject } from 'autotel-cloudflare'
 *
 * class Counter implements DurableObject {
 *   async fetch(request: Request) {
 *     return new Response('count')
 *   }
 * }
 *
 * export default wrapDurableObject({ service: { name: 'counter-do' } }, Counter)
 * ```
 */

/**
 * Wrap a Durable Object class with instrumentation
 * Alternative API style inspired by workers-honeycomb-logger
 *
 * @param config Configuration (can be static object or function)
 * @param doClass The Durable Object class to wrap
 * @returns Instrumented Durable Object class
 */
declare function wrapDurableObject<T extends DurableObject>(config: ConfigurationOption, doClass: new (state: DurableObjectState, env: any) => T): new (state: DurableObjectState, env: any) => T;

/**
 * Ergonomic wrapper for Cloudflare Workers `fetch` handlers.
 *
 * `defineWorkerFetch` instruments the handler the same way `instrument()` does
 * (so span exports already flush via `ctx.waitUntil`), and additionally injects
 * a request-scoped `ExecutionLogger` as the fourth argument — pre-populated
 * with method, path, cf-ray and `request.cf` context.
 *
 * Use this instead of `wrapModule` / `instrument` when your handler wants the
 * logger handed in directly rather than reaching for `getRequestLogger()`.
 *
 * @example
 * ```ts
 * import { defineWorkerFetch } from 'autotel-cloudflare'
 *
 * export default defineWorkerFetch(
 *   { service: { name: 'my-worker' } },
 *   async (request, env, ctx, log) => {
 *     log.set({ route: '/health' })
 *     log.emitNow({ status: 200 })
 *     return new Response('ok')
 *   },
 * )
 * ```
 */

type DefineWorkerFetchOptions = WorkersLoggerOptions;
type WorkerFetchHandler<E> = (request: Request, env: E, ctx: ExecutionContext, log: ExecutionLogger) => Response | Promise<Response>;
/**
 * Wrap a Workers fetch handler so:
 *   - the handler is instrumented (spans, propagation, waitUntil export flush)
 *   - the handler receives a request-scoped logger as its fourth argument
 */
declare function defineWorkerFetch<E = unknown>(config: ConfigurationOption, handler: WorkerFetchHandler<E>, loggerOptions?: DefineWorkerFetchOptions): {
    fetch: (request: Request, env: E, ctx: ExecutionContext) => Promise<Response>;
};

/**
 * Global fetch() instrumentation for autotel-edge
 *
 * Automatically traces all outgoing fetch() calls with:
 * - HTTP method, URL, status code
 * - Request/response headers
 * - Automatic context propagation
 * - Error tracking
 */
/**
 * Instrument the global fetch function
 *
 * This wraps globalThis.fetch to automatically create spans for all outgoing HTTP requests.
 *
 * **Note:** This is called automatically when the library is initialized with
 * `instrumentation.instrumentGlobalFetch: true` (default).
 */
declare function instrumentGlobalFetch(): void;

/**
 * Global Cache API instrumentation for Cloudflare Workers
 *
 * Automatically traces cache operations:
 * - cache.match() - Read from cache
 * - cache.put() - Write to cache
 * - cache.delete() - Delete from cache
 */
/**
 * Instrument the global caches API
 *
 * This wraps globalThis.caches to automatically create spans for all cache operations.
 *
 * **Note:** This is called automatically when the library is initialized with
 * `instrumentation.instrumentGlobalCache: true` (default).
 */
declare function instrumentGlobalCache(): void;

export { type DefineWorkerFetchOptions, type WorkerFetchHandler, WorkersLoggerOptions, defineWorkerFetch, instrument, instrumentGlobalCache, instrumentGlobalFetch, wrapDurableObject, wrapModule };