autotel-edge 3.0.0

package/src/index.ts

@@ -0,0 +1,81 @@
+/**
+ * autotel-edge
+ *
+ * Vendor-agnostic OpenTelemetry for edge runtimes
+ * Foundation for Cloudflare Workers, Vercel Edge, Netlify Edge, Deno Deploy
+ *
+ * Bundle size: ~20KB minified (~8KB gzipped)
+ *
+ * @example Quick Start
+ * ```typescript
+ * import { trace, init } from 'autotel-edge'
+ *
+ * init({
+ *   service: { name: 'my-edge-function' },
+ *   exporter: { url: process.env.OTEL_ENDPOINT }
+ * })
+ *
+ * export const handler = trace(async (request: Request) => {
+ *   return new Response('Hello World')
+ * })
+ * ```
+ */
+
+// Core exports
+export { SpanImpl } from './core/span';
+export { WorkerTracer, withNextSpan } from './core/tracer';
+export { OTLPExporter } from './core/exporter';
+export { AsyncLocalStorageContextManager } from './core/context';
+export { WorkerTracerProvider } from './core/provider';
+export { Buffer } from './core/buffer';
+export {
+  parseConfig,
+  createInitialiser,
+  getActiveConfig,
+  setConfig,
+  type Initialiser,
+} from './core/config';
+
+// Functional API (PRIMARY - zero-boilerplate tracing)
+export {
+  trace,
+  withTracing,
+  instrument as instrumentFunctions,
+  span,
+  type traceOptions,
+  type TraceContext,
+  type InstrumentOptions,
+} from './functional';
+
+// Types
+export type {
+  Trigger,
+  EdgeConfig,
+  ResolvedEdgeConfig,
+  ServiceConfig,
+  OTLPExporterConfig,
+  ExporterConfig,
+  SamplingConfig,
+  InstrumentationOptions,
+  ResolveConfigFn,
+  ConfigurationOption,
+  PostProcessorFn,
+  TailSampleFn,
+  LocalTrace,
+  TraceFlushableSpanProcessor,
+  InitialSpanInfo,
+  HandlerInstrumentation,
+  EdgeSubscriber,
+  ReadableSpan,
+} from './types';
+
+// Re-export OpenTelemetry APIs for convenience
+export { context, propagation } from '@opentelemetry/api';
+
+// Re-export common OpenTelemetry types
+export type {
+  Span,
+  SpanContext,
+  Tracer,
+  Context,
+} from '@opentelemetry/api';

package/src/logger.ts

@@ -0,0 +1,13 @@
+/**
+ * Zero-dependency logger for edge runtimes with dynamic log level control
+ * Entry point: autotel-edge/logger
+ */
+
+export {
+  createEdgeLogger,
+  getEdgeTraceContext,
+  runWithLogLevel,
+  getActiveLogLevel,
+  type EdgeLogger,
+  type LogLevel,
+} from './api/logger';

package/src/sampling/index.test.ts

@@ -0,0 +1,297 @@
+import { describe, it, expect } from 'vitest';
+import {
+  createAdaptiveTailSampler,
+  createRandomTailSampler,
+  createErrorOnlyTailSampler,
+  createSlowOnlyTailSampler,
+  combineTailSamplers,
+  SamplingPresets,
+  type LocalTrace,
+} from './index';
+import { SpanStatusCode } from '@opentelemetry/api';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+
+// Helper to create a mock span
+function createMockSpan(overrides: Partial<ReadableSpan> = {}): ReadableSpan {
+  const now = Date.now();
+  return {
+    name: 'test-span',
+    spanContext: () => ({
+      traceId: 'test-trace-id',
+      spanId: 'test-span-id',
+      traceFlags: 1,
+    }),
+    startTime: [Math.floor(now / 1000), (now % 1000) * 1_000_000],
+    endTime: [Math.floor(now / 1000), (now % 1000) * 1_000_000],
+    status: { code: SpanStatusCode.UNSET },
+    attributes: {},
+    links: [],
+    events: [],
+    duration: [0, 0],
+    ended: true,
+    resource: {} as any,
+    instrumentationLibrary: { name: 'test', version: '1.0.0' },
+    droppedAttributesCount: 0,
+    droppedEventsCount: 0,
+    droppedLinksCount: 0,
+    kind: 0,
+    parentSpanId: undefined,
+    ...overrides,
+  } as ReadableSpan;
+}
+
+// Helper to create a LocalTrace
+function createLocalTrace(
+  traceId: string,
+  spanOverrides: Partial<ReadableSpan> = {},
+): LocalTrace {
+  return {
+    traceId,
+    localRootSpan: createMockSpan(spanOverrides),
+    spans: [createMockSpan(spanOverrides)],
+  };
+}
+
+describe('Sampling Strategies', () => {
+  describe('createAdaptiveTailSampler', () => {
+    it('should sample based on baseline rate for normal requests', () => {
+      const sampler = createAdaptiveTailSampler({ baselineSampleRate: 0.5 });
+
+      // Create multiple traces and check sampling distribution
+      const traces = Array.from({ length: 100 }, (_, i) =>
+        createLocalTrace(`trace-${i}`, { status: { code: SpanStatusCode.UNSET } }),
+      );
+
+      const sampled = traces.filter((trace) => sampler(trace));
+
+      // Should be roughly 50% sampled (allow some variance)
+      expect(sampled.length).toBeGreaterThan(30);
+      expect(sampled.length).toBeLessThan(70);
+    });
+
+    it('should always sample errors when alwaysSampleErrors is true', () => {
+      const sampler = createAdaptiveTailSampler({
+        baselineSampleRate: 0,
+        alwaysSampleErrors: true,
+      });
+
+      const errorTrace = createLocalTrace('error-trace', {
+        status: { code: SpanStatusCode.ERROR, message: 'Test error' },
+      });
+
+      expect(sampler(errorTrace)).toBe(true);
+    });
+
+    it('should not sample errors when alwaysSampleErrors is false', () => {
+      const sampler = createAdaptiveTailSampler({
+        baselineSampleRate: 0,
+        alwaysSampleErrors: false,
+      });
+
+      const errorTrace = createLocalTrace('error-trace', {
+        status: { code: SpanStatusCode.ERROR, message: 'Test error' },
+      });
+
+      expect(sampler(errorTrace)).toBe(false);
+    });
+
+    it('should always sample slow requests when alwaysSampleSlow is true', () => {
+      const now = Date.now();
+      const sampler = createAdaptiveTailSampler({
+        baselineSampleRate: 0,
+        slowThresholdMs: 1000,
+        alwaysSampleSlow: true,
+      });
+
+      const slowTrace = createLocalTrace('slow-trace', {
+        startTime: [Math.floor(now / 1000), (now % 1000) * 1_000_000],
+        endTime: [Math.floor((now + 2000) / 1000), ((now + 2000) % 1000) * 1_000_000],
+      });
+
+      expect(sampler(slowTrace)).toBe(true);
+    });
+
+    it('should not sample slow requests when alwaysSampleSlow is false', () => {
+      const now = Date.now();
+      const sampler = createAdaptiveTailSampler({
+        baselineSampleRate: 0,
+        slowThresholdMs: 1000,
+        alwaysSampleSlow: false,
+      });
+
+      const slowTrace = createLocalTrace('slow-trace', {
+        startTime: [Math.floor(now / 1000), (now % 1000) * 1_000_000],
+        endTime: [Math.floor((now + 2000) / 1000), ((now + 2000) % 1000) * 1_000_000],
+      });
+
+      expect(sampler(slowTrace)).toBe(false);
+    });
+
+    it('should maintain consistent baseline decision for same trace', () => {
+      const sampler = createAdaptiveTailSampler({ baselineSampleRate: 0.5 });
+
+      const trace1 = createLocalTrace('consistent-trace');
+      const decision1 = sampler(trace1);
+
+      // Create new trace with same ID
+      const trace2 = createLocalTrace('consistent-trace');
+      const decision2 = sampler(trace2);
+
+      expect(decision1).toBe(decision2);
+    });
+  });
+
+  describe('createRandomTailSampler', () => {
+    it('should sample at specified rate', () => {
+      const sampler = createRandomTailSampler(0.5);
+
+      const traces = Array.from({ length: 100 }, (_, i) =>
+        createLocalTrace(`trace-${i}`),
+      );
+
+      const sampled = traces.filter((trace) => sampler(trace));
+
+      // Should be roughly 50% sampled
+      expect(sampled.length).toBeGreaterThan(30);
+      expect(sampled.length).toBeLessThan(70);
+    });
+
+    it('should never sample when rate is 0', () => {
+      const sampler = createRandomTailSampler(0);
+
+      const traces = Array.from({ length: 100 }, (_, i) =>
+        createLocalTrace(`trace-${i}`),
+      );
+
+      const sampled = traces.filter((trace) => sampler(trace));
+
+      expect(sampled.length).toBe(0);
+    });
+
+    it('should always sample when rate is 1', () => {
+      const sampler = createRandomTailSampler(1);
+
+      const traces = Array.from({ length: 100 }, (_, i) =>
+        createLocalTrace(`trace-${i}`),
+      );
+
+      const sampled = traces.filter((trace) => sampler(trace));
+
+      expect(sampled.length).toBe(100);
+    });
+  });
+
+  describe('createErrorOnlyTailSampler', () => {
+    it('should only sample errors', () => {
+      const sampler = createErrorOnlyTailSampler();
+
+      const errorTrace = createLocalTrace('error-trace', {
+        status: { code: SpanStatusCode.ERROR },
+      });
+      const okTrace = createLocalTrace('ok-trace', {
+        status: { code: SpanStatusCode.OK },
+      });
+      const unsetTrace = createLocalTrace('unset-trace', {
+        status: { code: SpanStatusCode.UNSET },
+      });
+
+      expect(sampler(errorTrace)).toBe(true);
+      expect(sampler(okTrace)).toBe(false);
+      expect(sampler(unsetTrace)).toBe(false);
+    });
+  });
+
+  describe('createSlowOnlyTailSampler', () => {
+    it('should only sample slow requests', () => {
+      const now = Date.now();
+      const sampler = createSlowOnlyTailSampler(1000);
+
+      const fastTrace = createLocalTrace('fast-trace', {
+        startTime: [Math.floor(now / 1000), (now % 1000) * 1_000_000],
+        endTime: [Math.floor((now + 500) / 1000), ((now + 500) % 1000) * 1_000_000],
+      });
+
+      const slowTrace = createLocalTrace('slow-trace', {
+        startTime: [Math.floor(now / 1000), (now % 1000) * 1_000_000],
+        endTime: [Math.floor((now + 2000) / 1000), ((now + 2000) % 1000) * 1_000_000],
+      });
+
+      expect(sampler(fastTrace)).toBe(false);
+      expect(sampler(slowTrace)).toBe(true);
+    });
+  });
+
+  describe('combineTailSamplers', () => {
+    it('should sample if any sampler returns true (OR logic)', () => {
+      const errorSampler = createErrorOnlyTailSampler();
+      const slowSampler = createSlowOnlyTailSampler(1000);
+      const combined = combineTailSamplers(errorSampler, slowSampler);
+
+      const now = Date.now();
+
+      // Error but fast - should sample
+      const errorTrace = createLocalTrace('error-trace', {
+        status: { code: SpanStatusCode.ERROR },
+        startTime: [Math.floor(now / 1000), (now % 1000) * 1_000_000],
+        endTime: [Math.floor((now + 500) / 1000), ((now + 500) % 1000) * 1_000_000],
+      });
+
+      // OK but slow - should sample
+      const slowTrace = createLocalTrace('slow-trace', {
+        status: { code: SpanStatusCode.OK },
+        startTime: [Math.floor(now / 1000), (now % 1000) * 1_000_000],
+        endTime: [Math.floor((now + 2000) / 1000), ((now + 2000) % 1000) * 1_000_000],
+      });
+
+      // OK and fast - should not sample
+      const normalTrace = createLocalTrace('normal-trace', {
+        status: { code: SpanStatusCode.OK },
+        startTime: [Math.floor(now / 1000), (now % 1000) * 1_000_000],
+        endTime: [Math.floor((now + 500) / 1000), ((now + 500) % 1000) * 1_000_000],
+      });
+
+      expect(combined(errorTrace)).toBe(true);
+      expect(combined(slowTrace)).toBe(true);
+      expect(combined(normalTrace)).toBe(false);
+    });
+  });
+
+  describe('SamplingPresets', () => {
+    it('should have production preset', () => {
+      const sampler = SamplingPresets.production();
+      expect(typeof sampler).toBe('function');
+    });
+
+    it('should have highTraffic preset', () => {
+      const sampler = SamplingPresets.highTraffic();
+      expect(typeof sampler).toBe('function');
+    });
+
+    it('should have debugging preset', () => {
+      const sampler = SamplingPresets.debugging();
+      expect(typeof sampler).toBe('function');
+    });
+
+    it('should have development preset', () => {
+      const sampler = SamplingPresets.development();
+      expect(typeof sampler).toBe('function');
+    });
+
+    it('production preset should capture errors and slow requests', () => {
+      const sampler = SamplingPresets.production();
+      const now = Date.now();
+
+      const errorTrace = createLocalTrace('error-trace', {
+        status: { code: SpanStatusCode.ERROR },
+      });
+
+      const slowTrace = createLocalTrace('slow-trace', {
+        startTime: [Math.floor(now / 1000), (now % 1000) * 1_000_000],
+        endTime: [Math.floor((now + 2000) / 1000), ((now + 2000) % 1000) * 1_000_000],
+      });
+
+      expect(sampler(errorTrace)).toBe(true);
+      expect(sampler(slowTrace)).toBe(true);
+    });
+  });
+});

package/src/sampling/index.ts

@@ -0,0 +1,276 @@
+/**
+ * Sampling strategies for autotel-edge
+ *
+ * Provides intelligent sampling to reduce telemetry costs while capturing critical data.
+ *
+ * Key strategies:
+ * - Always trace errors and slow requests (critical for debugging)
+ * - Adaptive sampling based on load
+ * - Baseline random sampling for normal traffic
+ *
+ * @example
+ * ```typescript
+ * import { createAdaptiveTailSampler } from 'autotel-edge/sampling'
+ *
+ * export default instrument(handler, {
+ *   sampling: {
+ *     tailSampler: createAdaptiveTailSampler({
+ *       baselineSampleRate: 0.1,  // 10% of normal requests
+ *       slowThresholdMs: 1000,     // Requests > 1s are "slow"
+ *     })
+ *   }
+ * })
+ * ```
+ */
+
+import type { TailSampleFn, LocalTrace } from '../types';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+
+export interface AdaptiveSamplerOptions {
+  /**
+   * Baseline sample rate for normal (successful, fast) requests
+   * @default 0.1 (10%)
+   */
+  baselineSampleRate?: number;
+
+  /**
+   * Threshold in milliseconds for "slow" requests
+   * Requests taking longer than this will always be trace
+   * @default 1000ms
+   */
+  slowThresholdMs?: number;
+
+  /**
+   * Always trace error spans
+   * @default true
+   */
+  alwaysSampleErrors?: boolean;
+
+  /**
+   * Always trace slow spans
+   * @default true
+   */
+  alwaysSampleSlow?: boolean;
+}
+
+/**
+ * Create an adaptive tail sampler
+ *
+ * This sampler ensures you never miss critical issues while keeping costs down:
+ * - Always traces errors (status code = ERROR)
+ * - Always traces slow requests (duration >= slowThresholdMs)
+ * - Uses baseline sample rate for successful fast requests
+ *
+ * **Recommended for production use.**
+ *
+ * @example
+ * ```typescript
+ * const tailSampler = createAdaptiveTailSampler({
+ *   baselineSampleRate: 0.1,    // 10% of normal requests
+ *   slowThresholdMs: 1000,       // Requests > 1s are "slow"
+ *   alwaysSampleErrors: true,    // Always trace errors
+ *   alwaysSampleSlow: true       // Always trace slow requests
+ * })
+ * ```
+ */
+export function createAdaptiveTailSampler(
+  options: AdaptiveSamplerOptions = {},
+): TailSampleFn {
+  const baselineSampleRate = options.baselineSampleRate ?? 0.1;
+  const slowThresholdMs = options.slowThresholdMs ?? 1000;
+  const alwaysSampleErrors = options.alwaysSampleErrors ?? true;
+  const alwaysSampleSlow = options.alwaysSampleSlow ?? true;
+
+  if (baselineSampleRate < 0 || baselineSampleRate > 1) {
+    throw new Error('Baseline sample rate must be between 0 and 1');
+  }
+
+  // Store baseline decisions using trace ID
+  const baselineDecisions = new Map<string, boolean>();
+
+  return (traceInfo: LocalTrace): boolean => {
+    const { traceId, localRootSpan } = traceInfo;
+
+    // Get or create baseline decision for this trace
+    if (!baselineDecisions.has(traceId)) {
+      baselineDecisions.set(traceId, Math.random() < baselineSampleRate);
+    }
+    const baselineDecision = baselineDecisions.get(traceId)!;
+
+    // Always keep errors (SpanStatusCode.ERROR = 2)
+    if (alwaysSampleErrors && localRootSpan.status.code === 2) {
+      return true;
+    }
+
+    // Always keep slow requests
+    if (alwaysSampleSlow) {
+      const duration = getDurationMs(localRootSpan);
+      if (duration >= slowThresholdMs) {
+        return true;
+      }
+    }
+
+    // Otherwise, use baseline decision
+    return baselineDecision;
+  };
+}
+
+/**
+ * Create a simple random tail sampler
+ *
+ * Samples a fixed percentage of all traces regardless of outcome.
+ *
+ * @example
+ * ```typescript
+ * const tailSampler = createRandomTailSampler(0.1) // 10% of all requests
+ * ```
+ */
+export function createRandomTailSampler(sampleRate: number): TailSampleFn {
+  if (sampleRate < 0 || sampleRate > 1) {
+    throw new Error('Sample rate must be between 0 and 1');
+  }
+
+  const decisions = new Map<string, boolean>();
+
+  return (traceInfo: LocalTrace): boolean => {
+    const { traceId } = traceInfo;
+
+    if (!decisions.has(traceId)) {
+      decisions.set(traceId, Math.random() < sampleRate);
+    }
+
+    return decisions.get(traceId)!;
+  };
+}
+
+/**
+ * Create a tail sampler that keeps all errors
+ *
+ * Useful for debugging - captures all failures while dropping successful requests.
+ *
+ * @example
+ * ```typescript
+ * const tailSampler = createErrorOnlyTailSampler()
+ * ```
+ */
+export function createErrorOnlyTailSampler(): TailSampleFn {
+  return (traceInfo: LocalTrace): boolean => {
+    // SpanStatusCode.ERROR = 2
+    return traceInfo.localRootSpan.status.code === 2;
+  };
+}
+
+/**
+ * Create a tail sampler that keeps slow requests
+ *
+ * Useful for performance debugging - captures slow requests while dropping fast ones.
+ *
+ * @example
+ * ```typescript
+ * const tailSampler = createSlowOnlyTailSampler(1000) // Keep requests > 1s
+ * ```
+ */
+export function createSlowOnlyTailSampler(thresholdMs: number): TailSampleFn {
+  return (traceInfo: LocalTrace): boolean => {
+    const duration = getDurationMs(traceInfo.localRootSpan);
+    return duration >= thresholdMs;
+  };
+}
+
+/**
+ * Combine multiple tail samplers with OR logic
+ *
+ * Keeps a trace if ANY sampler returns true.
+ *
+ * @example
+ * ```typescript
+ * const tailSampler = combineTailSamplers(
+ *   createErrorOnlyTailSampler(),
+ *   createSlowOnlyTailSampler(1000),
+ *   createRandomTailSampler(0.01)  // 1% baseline
+ * )
+ * ```
+ */
+export function combineTailSamplers(...samplers: TailSampleFn[]): TailSampleFn {
+  if (samplers.length === 0) {
+    throw new Error('combineTailSamplers requires at least one sampler');
+  }
+
+  return (traceInfo: LocalTrace): boolean => {
+    return samplers.some((sampler) => sampler(traceInfo));
+  };
+}
+
+/**
+ * Create a tail sampler based on custom predicate
+ *
+ * @example
+ * ```typescript
+ * // Keep traces with specific attributes
+ * const tailSampler = createCustomTailSampler((trace) => {
+ *   const attrs = trace.localRootSpan.attributes
+ *   return attrs['user.id'] === 'vip_123'
+ * })
+ * ```
+ */
+export function createCustomTailSampler(
+  predicate: (traceInfo: LocalTrace) => boolean,
+): TailSampleFn {
+  return predicate;
+}
+
+/**
+ * Helper: Get span duration in milliseconds
+ */
+function getDurationMs(span: ReadableSpan): number {
+  const start = span.startTime[0] * 1000 + span.startTime[1] / 1_000_000;
+  const end = span.endTime[0] * 1000 + span.endTime[1] / 1_000_000;
+  return end - start;
+}
+
+/**
+ * Common presets for quick setup
+ */
+export const SamplingPresets = {
+  /**
+   * Production: 10% baseline, all errors, all slow (>1s)
+   * Recommended for most production workloads
+   */
+  production: (): TailSampleFn =>
+    createAdaptiveTailSampler({
+      baselineSampleRate: 0.1,
+      slowThresholdMs: 1000,
+    }),
+
+  /**
+   * High-traffic: 1% baseline, all errors, all slow (>2s)
+   * For high-volume services where cost is a concern
+   */
+  highTraffic: (): TailSampleFn =>
+    createAdaptiveTailSampler({
+      baselineSampleRate: 0.01,
+      slowThresholdMs: 2000,
+    }),
+
+  /**
+   * Debugging: All errors, all slow (>500ms), 50% baseline
+   * For active debugging sessions
+   */
+  debugging: (): TailSampleFn =>
+    createAdaptiveTailSampler({
+      baselineSampleRate: 0.5,
+      slowThresholdMs: 500,
+    }),
+
+  /**
+   * Development: 100% sampling
+   * For local development and testing
+   */
+  development: (): TailSampleFn => () => true,
+
+  /**
+   * Errors only: Capture all failures, drop all successes
+   * For error-focused monitoring
+   */
+  errorsOnly: (): TailSampleFn => createErrorOnlyTailSampler(),
+};

package/src/sampling.ts

@@ -0,0 +1,6 @@
+/**
+ * Sampling strategies for edge runtimes
+ * Entry point: autotel-edge/sampling
+ */
+
+export * from './sampling/index';

package/src/testing/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Testing utilities for autotel-edge
+ *
+ * This module provides testing helpers for edge runtime environments.
+ * Currently minimal - can be extended with utilities from autotel package as needed.
+ */
+
+// Empty export to make this a valid module
+export {};

package/src/testing.ts

@@ -0,0 +1,6 @@
+/**
+ * Testing utilities for edge runtimes
+ * Entry point: autotel-edge/testing
+ */
+
+export type * from './testing/index';