autotel 2.1.0

package/dist/index.d.cts

@@ -0,0 +1,758 @@
+import { NodeSDKConfiguration, NodeSDK } from '@opentelemetry/sdk-node';
+import { SpanProcessor, SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { Resource } from '@opentelemetry/resources';
+import { Sampler } from './sampling.cjs';
+export { AdaptiveSampler, AlwaysSampler, NeverSampler, RandomSampler, SamplingContext, UserIdSampler } from './sampling.cjs';
+import { EventSubscriber } from './event-subscriber.cjs';
+export { EventAttributes, FunnelStatus, OutcomeStatus } from './event-subscriber.cjs';
+import { Logger } from './logger.cjs';
+import { Attributes, Span, Context } from '@opentelemetry/api';
+export { Context, Span, SpanContext, SpanKind, SpanStatusCode, Tracer, context, trace as otelTrace, propagation } from '@opentelemetry/api';
+import { MetricReader } from '@opentelemetry/sdk-metrics';
+import { LogRecordProcessor } from '@opentelemetry/sdk-logs';
+export { InstrumentOptions, SpanOptions, WithBaggageOptions, WithNewContextOptions, ctx, instrument, span, trace, withBaggage, withNewContext, withTracing } from './functional.cjs';
+export { Event, EventsOptions, getEvents, resetEvents } from './event.cjs';
+export { Metric, MetricsOptions, getMetrics, resetMetrics } from './metric.cjs';
+export { createCounter, createHistogram, createObservableGauge, createUpDownCounter, getMeter } from './metric-helpers.cjs';
+export { createDeterministicTraceId, finalizeSpan, flattenMetadata, getActiveContext, getActiveSpan, getTracer, runWithSpan } from './trace-helpers.cjs';
+export { getAutotelTracer, getAutotelTracerProvider, setAutotelTracerProvider } from './tracer-provider.cjs';
+export { DBConfig, HTTPConfig, LLMConfig, MessagingConfig, traceDB, traceHTTP, traceLLM, traceMessaging } from './semantic-helpers.cjs';
+export { T as TraceContext, d as defineBaggageSchema } from './trace-context-DRZdUvVY.cjs';
+import 'pino';
+import './event-testing.cjs';
+import './metric-testing.cjs';
+
+/**
+ * Input validation for events events and attributes
+ *
+ * Prevents:
+ * - Invalid event names
+ * - Oversized payloads
+ * - Circular references
+ * - Sensitive data leaks
+ */
+
+interface ValidationConfig {
+    /** Max event name length (default: 100) */
+    maxEventNameLength: number;
+    /** Max attribute key length (default: 100) */
+    maxAttributeKeyLength: number;
+    /** Max attribute value length for strings (default: 1000) */
+    maxAttributeValueLength: number;
+    /** Max total attributes per event (default: 50) */
+    maxAttributeCount: number;
+    /** Max nesting depth for objects (default: 3) */
+    maxNestingDepth: number;
+    /** Sensitive field patterns to redact */
+    sensitivePatterns: RegExp[];
+}
+
+/**
+ * Simplified initialization for autotel
+ *
+ * Single init() function with sensible defaults.
+ * Replaces initInstrumentation() and separate events config.
+ */
+
+interface AutotelConfig {
+    /** Service name (required) */
+    service: string;
+    /** Event subscribers - bring your own (PostHog, Mixpanel, etc.) */
+    subscribers?: EventSubscriber[];
+    /**
+     * Additional OpenTelemetry instrumentations to register.
+     * Useful when you want HTTP/Prisma/etc auto instrumentation alongside
+     * the functional helpers.
+     *
+     * **Important:** If you need custom instrumentation configs (like `requireParentSpan: false`),
+     * use EITHER manual instrumentations OR integrations, not both for the same library.
+     * Manual instrumentations always take precedence over auto-instrumentations.
+     *
+     * @example Manual instrumentations with custom config
+     * ```typescript
+     * import { MongoDBInstrumentation } from '@opentelemetry/instrumentation-mongodb'
+     *
+     * init({
+     *   service: 'my-app',
+     *   integrations: false,  // Disable auto-instrumentations
+     *   instrumentations: [
+     *     new MongoDBInstrumentation({
+     *       requireParentSpan: false  // Custom config
+     *     })
+     *   ]
+     * })
+     * ```
+     *
+     * @example Mix auto + manual (auto for most, manual for specific configs)
+     * ```typescript
+     * import { MongoDBInstrumentation } from '@opentelemetry/instrumentation-mongodb'
+     *
+     * init({
+     *   service: 'my-app',
+     *   integrations: ['http', 'express'],  // Auto for these
+     *   instrumentations: [
+     *     new MongoDBInstrumentation({
+     *       requireParentSpan: false  // Manual config for MongoDB
+     *     })
+     *   ]
+     * })
+     * ```
+     */
+    instrumentations?: NodeSDKConfiguration['instrumentations'];
+    /**
+     * Simple integration names for auto-instrumentation.
+     * Uses @opentelemetry/auto-instrumentations-node (peer dependency).
+     *
+     * **Important:** If you provide manual instrumentations for the same library,
+     * the manual config takes precedence and auto-instrumentation for that library is disabled.
+     *
+     * @example Enable all integrations (simple approach)
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   integrations: true  // Enable all with defaults
+     * })
+     * ```
+     *
+     * @example Enable specific integrations
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   integrations: ['express', 'pino', 'http']
+     * })
+     * ```
+     *
+     * @example Configure specific integrations
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   integrations: {
+     *     express: { enabled: true },
+     *     pino: { enabled: true },
+     *     http: { enabled: false }
+     *   }
+     * })
+     * ```
+     *
+     * @example Manual config when you need custom settings
+     * ```typescript
+     * import { MongoDBInstrumentation } from '@opentelemetry/instrumentation-mongodb'
+     *
+     * init({
+     *   service: 'my-app',
+     *   integrations: false,  // Use manual control
+     *   instrumentations: [
+     *     new MongoDBInstrumentation({
+     *       requireParentSpan: false  // Custom config not available with auto
+     *     })
+     *   ]
+     * })
+     * ```
+     */
+    integrations?: string[] | boolean | Record<string, {
+        enabled?: boolean;
+    }>;
+    /**
+     * OTLP endpoint for traces/metrics/logs
+     * Only used if you don't provide custom exporters/processors
+     * @default process.env.OTLP_ENDPOINT || 'http://localhost:4318'
+     */
+    endpoint?: string;
+    /**
+     * Custom span processors for traces (supports multiple processors)
+     * Allows you to use any backend: Jaeger, Zipkin, Datadog, New Relic, etc.
+     * If not provided, defaults to OTLP with tail sampling
+     *
+     * @example Multiple processors
+     * ```typescript
+     * import { JaegerExporter } from '@opentelemetry/exporter-jaeger'
+     * import { BatchSpanProcessor, SimpleSpanProcessor, ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base'
+     *
+     * init({
+     *   service: 'my-app',
+     *   spanProcessors: [
+     *     new BatchSpanProcessor(new JaegerExporter()),
+     *     new SimpleSpanProcessor(new ConsoleSpanExporter())  // Debug alongside production
+     *   ]
+     * })
+     * ```
+     *
+     * @example Single processor
+     * ```typescript
+     * import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'
+     *
+     * init({
+     *   service: 'my-app',
+     *   spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())]
+     * })
+     * ```
+     */
+    spanProcessors?: SpanProcessor[];
+    /**
+     * Custom span exporters for traces (alternative to spanProcessors, supports multiple exporters)
+     * Provide either spanProcessors OR spanExporters, not both
+     * Each exporter will be wrapped in TailSamplingSpanProcessor + BatchSpanProcessor
+     *
+     * @example Multiple exporters
+     * ```typescript
+     * import { ZipkinExporter } from '@opentelemetry/exporter-zipkin'
+     * import { JaegerExporter } from '@opentelemetry/exporter-jaeger'
+     *
+     * init({
+     *   service: 'my-app',
+     *   spanExporters: [
+     *     new ZipkinExporter({ url: 'http://localhost:9411/api/v2/spans' }),
+     *     new JaegerExporter()  // Send to multiple backends simultaneously
+     *   ]
+     * })
+     * ```
+     *
+     * @example Single exporter
+     * ```typescript
+     * import { ZipkinExporter } from '@opentelemetry/exporter-zipkin'
+     *
+     * init({
+     *   service: 'my-app',
+     *   spanExporters: [new ZipkinExporter({ url: 'http://localhost:9411/api/v2/spans' })]
+     * })
+     * ```
+     */
+    spanExporters?: SpanExporter[];
+    /**
+     * Custom metric readers (supports multiple readers)
+     * Allows sending metrics to multiple backends: OTLP, Prometheus, custom readers
+     * Defaults to OTLP metrics exporter when metrics are enabled.
+     *
+     * @example Multiple metric readers
+     * ```typescript
+     * import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics'
+     * import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'
+     * import { PrometheusExporter } from '@opentelemetry/exporter-prometheus'
+     *
+     * init({
+     *   service: 'my-app',
+     *   metricReaders: [
+     *     new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter() }),
+     *     new PrometheusExporter()  // Export to multiple backends
+     *   ]
+     * })
+     * ```
+     */
+    metricReaders?: MetricReader[];
+    /**
+     * Custom log record processors. When omitted, logs are not configured.
+     */
+    logRecordProcessors?: LogRecordProcessor[];
+    /** Additional resource attributes to merge with defaults. */
+    resourceAttributes?: Attributes;
+    /** Provide a fully custom Resource to merge (advanced use case). */
+    resource?: Resource;
+    /**
+     * Headers for default OTLP exporters. Accepts either an object map or
+     * a "key=value" comma separated string.
+     */
+    otlpHeaders?: Record<string, string> | string;
+    /**
+     * OTLP protocol to use for traces, metrics, and logs
+     * - 'http': HTTP/protobuf (default, uses port 4318)
+     * - 'grpc': gRPC (uses port 4317)
+     *
+     * Can be overridden with OTEL_EXPORTER_OTLP_PROTOCOL env var.
+     *
+     * Note: gRPC exporters are optional peer dependencies. Install them with:
+     * ```bash
+     * pnpm add @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/exporter-metrics-otlp-grpc
+     * ```
+     *
+     * @example HTTP (default)
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   protocol: 'http',  // or omit (defaults to http)
+     *   endpoint: 'http://localhost:4318'
+     * })
+     * ```
+     *
+     * @example gRPC
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   protocol: 'grpc',
+     *   endpoint: 'grpc://localhost:4317'
+     * })
+     * ```
+     *
+     * @default 'http'
+     */
+    protocol?: 'http' | 'grpc';
+    /**
+     * Optional factory to build a customised NodeSDK instance from our defaults.
+     */
+    sdkFactory?: (defaults: Partial<NodeSDKConfiguration>) => NodeSDK;
+    /**
+     * Infrastructure metrics configuration
+     * - true: always enabled (default)
+     * - false: always disabled
+     * - 'auto': always enabled (same as true)
+     *
+     * Can be overridden with AUTOTELEMETRY_METRICS=on|off env var
+     */
+    metrics?: boolean | 'auto';
+    /** Sampling strategy (default: AdaptiveSampler with 10% baseline) */
+    sampler?: Sampler;
+    /** Service version (default: auto-detect from package.json or '1.0.0') */
+    version?: string;
+    /** Environment (default: process.env.NODE_ENV || 'development') */
+    environment?: string;
+    /**
+     * Logger instance for structured logging with automatic trace correlation
+     *
+     * **Recommended:** Bring your own Pino or Winston instance
+     *
+     * Autotel automatically instruments Pino and Winston loggers to:
+     * - Inject trace context (traceId, spanId) into every log record
+     * - Record errors in the active OpenTelemetry span
+     * - Bridge logs to the OpenTelemetry Logs API for OTLP export to Grafana, Datadog, etc.
+     *
+     * Supports any logger with 4 methods: info/warn/error/debug
+     * Default: silent logger (no-op)
+     *
+     * @example Using Pino (recommended)
+     * ```typescript
+     * import pino from 'pino'  // npm install pino
+     * import { init } from 'autotel'
+     *
+     * const logger = pino({ level: 'info' })
+     * init({ service: 'my-app', logger })
+     *
+     * // Logs automatically include traceId/spanId and export via OTLP!
+     * logger.info('User created', { userId: '123' })
+     * ```
+     *
+     * @example Using Winston
+     * ```typescript
+     * import winston from 'winston'  // npm install winston
+     * import { init } from 'autotel'
+     *
+     * const logger = winston.createLogger({
+     *   level: 'info',
+     *   format: winston.format.json()
+     * })
+     * init({ service: 'my-app', logger })
+     * ```
+     *
+     * @example Custom logger (any logger with 4 methods)
+     * ```typescript
+     * const logger = {
+     *   info: (msg, extra) => console.log(msg, extra),
+     *   warn: (msg, extra) => console.warn(msg, extra),
+     *   error: (msg, err, extra) => console.error(msg, err, extra),
+     *   debug: (msg, extra) => console.debug(msg, extra),
+     * }
+     * init({ service: 'my-app', logger })
+     * ```
+     */
+    logger?: Logger;
+    /**
+     * Automatically flush events queue when root spans end
+     * - true: Auto-flush on root span completion (default)
+     * - false: Use batching (events flush every 10 seconds automatically)
+     *
+     * Only flushes on root spans to avoid excessive network calls.
+     * Default is true for serverless/short-lived processes. Set to false
+     * for long-running services where batching is more efficient.
+     */
+    autoFlushEvents?: boolean;
+    /**
+     * Include OpenTelemetry span flushing in auto-flush (default: false)
+     *
+     * When enabled, spans are force-flushed along with events events on root
+     * span completion. This is useful for serverless/short-lived processes where
+     * spans may not export before the process ends.
+     *
+     * - true: Force-flush spans on root span completion (~50-200ms latency)
+     * - false: Spans export via normal batch processor (default behavior)
+     *
+     * Only applies when autoFlushEvents is also enabled.
+     *
+     * Note: For edge runtimes (Cloudflare Workers, Vercel Edge), use the
+     * 'autotel-edge' package instead, which handles this automatically.
+     *
+     * @example Serverless with auto-flush
+     * ```typescript
+     * init({
+     *   service: 'my-lambda',
+     *   autoFlushEvents: true,
+     *   autoFlush: true, // Force-flush spans
+     * });
+     * ```
+     */
+    autoFlush?: boolean;
+    /**
+     * Automatically copy baggage entries to span attributes
+     *
+     * When enabled, all baggage entries are automatically added as span attributes,
+     * making them visible in trace UIs (Jaeger, Grafana, DataDog, etc.) without
+     * manually calling ctx.setAttribute() for each entry.
+     *
+     * - `true`: adds baggage with 'baggage.' prefix (e.g. baggage.tenant.id)
+     * - `string`: uses custom prefix (e.g. 'ctx' → ctx.tenant.id, '' → tenant.id)
+     * - `false` or omit: disabled (default)
+     *
+     * @default false
+     *
+     * @example Enable with default prefix
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   baggage: true
+     * });
+     *
+     * // Now baggage automatically appears as span attributes
+     * await withBaggage({
+     *   baggage: { 'tenant.id': 't1', 'user.id': 'u1' },
+     *   fn: async () => {
+     *     // Span has baggage.tenant.id and baggage.user.id attributes!
+     *   }
+     * });
+     * ```
+     *
+     * @example Custom prefix
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   baggage: 'ctx' // Uses 'ctx.' prefix
+     * });
+     * // Creates attributes: ctx.tenant.id, ctx.user.id
+     * ```
+     *
+     * @example No prefix
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   baggage: '' // No prefix
+     * });
+     * // Creates attributes: tenant.id, user.id
+     * ```
+     */
+    baggage?: boolean | string;
+    /**
+     * Validation configuration for events events
+     * - Override default sensitive field patterns for redaction
+     * - Customize max lengths, nesting depth, etc.
+     *
+     * @example Disable redaction for development
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   validation: {
+     *     sensitivePatterns: [] // Disable all redaction
+     *   }
+     * })
+     * ```
+     *
+     * @example Add custom patterns
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   validation: {
+     *     sensitivePatterns: [
+     *       /password/i,
+     *       /apiKey/i,
+     *       /customSecret/i  // Your custom pattern
+     *     ]
+     *   }
+     * })
+     * ```
+     */
+    validation?: Partial<ValidationConfig>;
+    /**
+     * Debug mode for local span inspection.
+     * Enables console output to help you see spans as they're created.
+     *
+     * When true: Outputs spans to console AND sends to backend (if endpoint/exporter configured)
+     * When false/undefined: Sends to backend only (default behavior)
+     *
+     * Perfect for progressive development:
+     * - Start with debug: true (no endpoint) → console-only, see traces immediately
+     * - Add endpoint later → console + backend, verify before choosing provider
+     * - Remove debug in production → backend only, clean production config
+     *
+     * Can be overridden with AUTOLEMETRY_DEBUG environment variable.
+     *
+     * @example Getting started - see spans immediately
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   debug: true  // No endpoint yet - console only!
+     * })
+     * ```
+     *
+     * @example Testing with local collector
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   debug: true,
+     *   endpoint: 'http://localhost:4318'  // Console + OTLP
+     * })
+     * ```
+     *
+     * @example Production debugging
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   debug: true,  // See what's being sent
+     *   endpoint: 'https://api.honeycomb.io'
+     * })
+     * ```
+     *
+     * @example Environment variable
+     * ```bash
+     * AUTOLEMETRY_DEBUG=true node server.js
+     * ```
+     */
+    debug?: boolean;
+    /**
+     * OpenLLMetry integration for LLM observability.
+     * Requires @traceloop/node-server-sdk as an optional peer dependency.
+     *
+     * @example Enable OpenLLMetry with default settings
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   openllmetry: { enabled: true }
+     * })
+     * ```
+     *
+     * @example Enable with custom options
+     * ```typescript
+     * init({
+     *   service: 'my-app',
+     *   openllmetry: {
+     *     enabled: true,
+     *     options: {
+     *       disableBatch: process.env.NODE_ENV !== 'production',
+     *       apiKey: process.env.TRACELOOP_API_KEY
+     *     }
+     *   }
+     * })
+     * ```
+     */
+    openllmetry?: {
+        enabled: boolean;
+        options?: Record<string, unknown>;
+    };
+}
+declare function init(cfg: AutotelConfig): void;
+
+/**
+ * Span processor that copies baggage entries to span attributes
+ *
+ * This makes baggage visible in trace UIs without manual attribute setting.
+ * Enabled via init({ baggage: true }) or init({ baggage: 'custom-prefix' })
+ */
+
+interface BaggageSpanProcessorOptions {
+    /**
+     * Prefix for baggage attributes
+     * @default 'baggage.'
+     */
+    prefix?: string;
+}
+/**
+ * Span processor that automatically copies baggage entries to span attributes
+ *
+ * This makes baggage visible in trace UIs (Jaeger, Grafana, DataDog, etc.)
+ * without manually calling ctx.setAttribute() for each baggage entry.
+ *
+ * @example Enable in init()
+ * ```typescript
+ * init({
+ *   service: 'my-app',
+ *   baggage: true // Uses default 'baggage.' prefix
+ * });
+ *
+ * // Now baggage automatically appears as span attributes
+ * await withBaggage({
+ *   baggage: { 'tenant.id': 't1', 'user.id': 'u1' },
+ *   fn: async () => {
+ *     // Span has baggage.tenant.id and baggage.user.id attributes!
+ *   }
+ * });
+ * ```
+ *
+ * @example Custom prefix
+ * ```typescript
+ * init({
+ *   service: 'my-app',
+ *   baggage: 'ctx' // Uses 'ctx.' prefix
+ * });
+ * // Creates attributes: ctx.tenant.id, ctx.user.id
+ * ```
+ */
+declare class BaggageSpanProcessor implements SpanProcessor {
+    private readonly prefix;
+    constructor(options?: BaggageSpanProcessorOptions);
+    onStart(span: Span, parentContext: Context): void;
+    onEnd(_span: ReadableSpan): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
+
+/**
+ * Operation context tracking using AsyncLocalStorage
+ *
+ * This module provides a way to track operation names across async boundaries
+ * so they can be automatically captured in events events.
+ *
+ * We cannot read span attributes from OpenTelemetry's API (it's write-only),
+ * so we maintain our own async context storage.
+ */
+/**
+ * Operation context that flows through async operations
+ */
+interface OperationContext {
+    /**
+     * The name of the current operation
+     * This is set by trace() or span() and can be read by events
+     */
+    name: string;
+}
+/**
+ * Get the current operation context (if any)
+ *
+ * @returns The current operation context, or undefined if not in an operation
+ *
+ * @example
+ * ```typescript
+ * const ctx = getOperationContext();
+ * if (ctx) {
+ *   console.log('Current operation:', ctx.name);
+ * }
+ * ```
+ */
+declare function getOperationContext(): OperationContext | undefined;
+/**
+ * Run a function within an operation context
+ *
+ * This sets the operation name for the duration of the function execution,
+ * including all async operations spawned from it.
+ *
+ * @param name - The operation name to set
+ * @param fn - The function to execute within the context
+ * @returns The result of the function
+ *
+ * @example
+ * ```typescript
+ * const result = await runInOperationContext('user.create', async () => {
+ *   // Any events.trackEvent() calls here will automatically capture
+ *   // 'operation.name': 'user.create'
+ *   await createUser();
+ *   return 'success';
+ * });
+ * ```
+ */
+declare function runInOperationContext<T>(name: string, fn: () => T): T;
+
+/**
+ * Global track() function for business events
+ *
+ * Simple, no instantiation needed, auto-attaches trace context
+ */
+
+/**
+ * Track a business events event
+ *
+ * Features:
+ * - Auto-attaches traceId and spanId if in active span
+ * - Batched sending with retry
+ * - Type-safe with optional generic
+ * - No-op if init() not called or no subscribers configured
+ *
+ * @example Basic usage
+ * ```typescript
+ * track('user.signup', { userId: '123', plan: 'pro' })
+ * ```
+ *
+ * @example With type safety
+ * ```typescript
+ * interface EventDatas {
+ *   'user.signup': { userId: string; plan: string }
+ *   'plan.upgraded': { userId: string; revenue: number }
+ * }
+ *
+ * track<EventDatas>('user.signup', { userId: '123', plan: 'pro' })
+ * ```
+ *
+ * @example Trace correlation (automatic)
+ * ```typescript
+ * @Instrumented()
+ * class UserService {
+ *   async createUser(data: CreateUserData) {
+ *     // This track call automatically includes traceId + spanId
+ *     track('user.signup', { userId: data.id })
+ *   }
+ * }
+ * ```
+ */
+declare function track<Events extends Record<string, any> = Record<string, any>>(event: keyof Events & string, data?: Events[typeof event]): void;
+
+/**
+ * Graceful shutdown with flush and cleanup
+ */
+/**
+ * Flush all pending telemetry
+ *
+ * Flushes both events events and OpenTelemetry spans to their destinations.
+ * Includes timeout protection to prevent hanging in serverless environments.
+ *
+ * Safe to call multiple times.
+ *
+ * @param options - Optional configuration
+ * @param options.timeout - Timeout in milliseconds (default: 2000ms)
+ *
+ * @example Manual flush in serverless
+ * ```typescript
+ * import { flush } from 'autotel';
+ *
+ * export const handler = async (event) => {
+ *   // ... process event
+ *   await flush(); // Flush before function returns
+ *   return result;
+ * };
+ * ```
+ *
+ * @example With custom timeout
+ * ```typescript
+ * await flush({ timeout: 5000 }); // 5 second timeout
+ * ```
+ */
+declare function flush(options?: {
+    timeout?: number;
+}): Promise<void>;
+/**
+ * Shutdown telemetry and cleanup resources
+ *
+ * - Flushes all pending data
+ * - Shuts down OpenTelemetry SDK
+ * - Cleans up resources
+ *
+ * Call this before process exit.
+ *
+ * Always performs cleanup even if flush fails, preventing resource leaks
+ * in serverless handlers or tests.
+ *
+ * @example Express server
+ * ```typescript
+ * const server = app.listen(3000)
+ *
+ * process.on('SIGTERM', async () => {
+ *   await server.close()
+ *   await shutdown()
+ *   process.exit(0)
+ * })
+ * ```
+ */
+declare function shutdown(): Promise<void>;
+
+export { type AutotelConfig, BaggageSpanProcessor, type BaggageSpanProcessorOptions, EventSubscriber, type OperationContext, Sampler, flush, getOperationContext, init, runInOperationContext, shutdown, track };