autotel 2.1.0

package/src/circuit-breaker.ts

@@ -0,0 +1,184 @@
+/**
+ * Circuit breaker for event subscribers
+ *
+ * Prevents cascading failures by fast-failing when an (subscriber) is unhealthy.
+ * Uses the circuit breaker pattern with three states:
+ * - CLOSED: Normal operation ((subscriber) working)
+ * - OPEN: Fast-fail mode ((subscriber) down)
+ * - HALF_OPEN: Testing if (subscriber) recovered
+ */
+
+export interface CircuitBreakerConfig {
+  /** Number of failures before opening circuit (default: 5) */
+  failureThreshold: number;
+  /** Time to wait before trying again in ms (default: 30000 = 30s) */
+  resetTimeout: number;
+  /** Time window for counting failures in ms (default: 60000 = 1min) */
+  windowSize: number;
+}
+
+const DEFAULT_CONFIG: CircuitBreakerConfig = {
+  failureThreshold: 5,
+  resetTimeout: 30_000, // 30 seconds
+  windowSize: 60_000, // 1 minute
+};
+
+export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+
+export const CircuitState = {
+  CLOSED: 'CLOSED' as const, // Normal operation
+  OPEN: 'OPEN' as const, // Fast-fail mode
+  HALF_OPEN: 'HALF_OPEN' as const, // Testing recovery
+} as const;
+
+interface FailureRecord {
+  timestamp: number;
+  error: string;
+}
+
+/**
+ * Circuit breaker implementation
+ *
+ * Tracks failures and automatically opens the circuit to prevent
+ * overwhelming failing subscribers.
+ */
+export class CircuitBreaker {
+  private state: CircuitState = CircuitState.CLOSED;
+  private failures: FailureRecord[] = [];
+  private lastFailureTime: number = 0;
+  private readonly config: CircuitBreakerConfig;
+  private readonly name: string;
+
+  constructor(name: string, config?: Partial<CircuitBreakerConfig>) {
+    this.name = name;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Execute a function with circuit breaker protection
+   * Throws CircuitOpenError if circuit is open
+   */
+  async execute<T>(fn: () => Promise<T>): Promise<T> {
+    // Check if circuit is open
+    if (this.state === CircuitState.OPEN) {
+      // Check if we should transition to half-open
+      const now = Date.now();
+      if (now - this.lastFailureTime >= this.config.resetTimeout) {
+        this.state = CircuitState.HALF_OPEN;
+      } else {
+        throw new CircuitOpenError(
+          `Circuit breaker is OPEN for ${this.name}. ` +
+            `Will retry in ${Math.ceil((this.config.resetTimeout - (now - this.lastFailureTime)) / 1000)}s`,
+        );
+      }
+    }
+
+    try {
+      const result = await fn();
+
+      // Success! Close circuit if it was half-open
+      if (this.state === CircuitState.HALF_OPEN) {
+        this.reset();
+      }
+
+      return result;
+    } catch (error) {
+      this.recordFailure(error);
+      throw error;
+    }
+  }
+
+  /**
+   * Record a failure and potentially open the circuit
+   */
+  private recordFailure(error: unknown): void {
+    const now = Date.now();
+
+    // Remove old failures outside the time window
+    this.failures = this.failures.filter(
+      (f) => now - f.timestamp < this.config.windowSize,
+    );
+
+    // Record new failure
+    this.failures.push({
+      timestamp: now,
+      error: error instanceof Error ? error.message : String(error),
+    });
+
+    this.lastFailureTime = now;
+
+    // Check if we should open the circuit
+    if (this.failures.length >= this.config.failureThreshold) {
+      if (this.state === CircuitState.HALF_OPEN) {
+        // Failed during test - reopen circuit
+        this.state = CircuitState.OPEN;
+      } else if (this.state === CircuitState.CLOSED) {
+        // Too many failures - open circuit
+        this.state = CircuitState.OPEN;
+      }
+    }
+  }
+
+  /**
+   * Reset the circuit breaker (on success)
+   */
+  private reset(): void {
+    this.state = CircuitState.CLOSED;
+    this.failures = [];
+    this.lastFailureTime = 0;
+  }
+
+  /**
+   * Get current state (for monitoring)
+   */
+  getState(): CircuitState {
+    return this.state;
+  }
+
+  /**
+   * Get failure count in current window
+   */
+  getFailureCount(): number {
+    const now = Date.now();
+    // Clean up old failures
+    this.failures = this.failures.filter(
+      (f) => now - f.timestamp < this.config.windowSize,
+    );
+    return this.failures.length;
+  }
+
+  /**
+   * Get recent failures (for debugging)
+   */
+  getRecentFailures(): FailureRecord[] {
+    const now = Date.now();
+    return this.failures.filter(
+      (f) => now - f.timestamp < this.config.windowSize,
+    );
+  }
+
+  /**
+   * Manually reset the circuit breaker (for testing or manual intervention)
+   */
+  forceReset(): void {
+    this.reset();
+  }
+
+  /**
+   * Manually open the circuit (for testing or manual intervention)
+   */
+  forceOpen(): void {
+    this.state = CircuitState.OPEN;
+    this.lastFailureTime = Date.now();
+  }
+}
+
+/**
+ * Error thrown when circuit is open
+ */
+export class CircuitOpenError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CircuitOpenError';
+  }
+}

package/src/config.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { configure, getConfig, resetConfig } from './config';
+
+describe('configure()', () => {
+  beforeEach(() => {
+    resetConfig();
+  });
+
+  it('should set custom tracer name', () => {
+    configure({
+      tracerName: 'my-custom-tracer',
+    });
+
+    const config = getConfig();
+    expect(config.tracerName).toBe('my-custom-tracer');
+  });
+
+  it('should set custom meter name', () => {
+    configure({
+      meterName: 'my-custom-meter',
+    });
+
+    const config = getConfig();
+    expect(config.meterName).toBe('my-custom-meter');
+  });
+
+  it('should allow custom tracer instance', () => {
+    const mockTracer = {
+      startActiveSpan: vi.fn(),
+      startSpan: vi.fn(),
+    };
+
+    configure({
+      tracer: mockTracer as any,
+    });
+
+    const config = getConfig();
+    expect(config.tracer).toBe(mockTracer);
+  });
+
+  it('should allow custom meter instance', () => {
+    const mockMeter = {
+      createCounter: vi.fn(),
+      createHistogram: vi.fn(),
+      createUpDownCounter: vi.fn(),
+      createObservableGauge: vi.fn(),
+      createObservableCounter: vi.fn(),
+      createObservableUpDownCounter: vi.fn(),
+    };
+
+    configure({
+      meter: mockMeter as any,
+    });
+
+    const config = getConfig();
+    expect(config.meter).toBe(mockMeter);
+  });
+
+  it('should merge configurations', () => {
+    configure({
+      tracerName: 'tracer-1',
+    });
+
+    configure({
+      meterName: 'meter-1',
+    });
+
+    const config = getConfig();
+    expect(config.tracerName).toBe('tracer-1');
+    expect(config.meterName).toBe('meter-1');
+  });
+
+  it('should reset to defaults', () => {
+    configure({
+      tracerName: 'custom-tracer',
+      meterName: 'custom-meter',
+    });
+
+    resetConfig();
+
+    const config = getConfig();
+    expect(config.tracerName).toBe('app');
+    expect(config.meterName).toBe('app');
+  });
+
+  it('should expose feature flags', () => {
+    const config = getConfig();
+    expect(config.featureFlags).toBeDefined();
+    expect(typeof config.featureFlags.ENABLE_TRACING).toBe('boolean');
+    expect(typeof config.featureFlags.ENABLE_METRICS_BY_DEFAULT).toBe(
+      'boolean',
+    );
+  });
+});

package/src/config.ts

@@ -0,0 +1,169 @@
+/**
+ * Global configuration for OpenTelemetry decorators
+ *
+ * Allows users to inject custom loggers, tracers, and meters
+ * while maintaining sensible defaults.
+ */
+
+import { trace, metrics, type Tracer, type Meter } from '@opentelemetry/api';
+import { getAutotelTracer } from './tracer-provider';
+
+export type { ILogger } from './logger';
+
+/**
+ * Environment-based feature flags for performance optimization
+ *
+ * Disables expensive features in development while maintaining
+ * full observability in production.
+ */
+const IS_PRODUCTION = process.env.NODE_ENV === 'production';
+const IS_DEV = process.env.NODE_ENV === 'development';
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const IS_TEST = process.env.NODE_ENV === 'test';
+
+export const FEATURE_FLAGS = {
+  /** Enable full auto-instrumentation (expensive, production only) */
+  ENABLE_AUTO_INSTRUMENTATION:
+    IS_PRODUCTION && process.env.autotel_AUTO_INSTRUMENT !== 'false',
+
+  /** Enable verbose logging (development only) */
+  ENABLE_VERBOSE_LOGGING: IS_DEV || process.env.autotel_VERBOSE === 'true',
+
+  /** Enable metrics collection (production only) */
+  ENABLE_METRICS_BY_DEFAULT:
+    IS_PRODUCTION && process.env.autotel_METRICS !== 'false',
+
+  /** Enable async resource detection (production only) */
+  ENABLE_RESOURCE_DETECTION:
+    IS_PRODUCTION && process.env.autotel_RESOURCE_DETECTION === 'true',
+
+  /** Enable tracing in all environments (can be disabled via autotel_TRACING=false) */
+  ENABLE_TRACING: process.env.autotel_TRACING !== 'false',
+
+  /** Enable log redaction for sensitive fields (can be disabled via autotel_REDACTION=false) */
+  ENABLE_REDACTION: process.env.autotel_REDACTION !== 'false',
+} as const;
+
+/**
+ * Global configuration options
+ */
+export interface InstrumentationConfig {
+  /**
+   * Tracer name for OpenTelemetry
+   * @default 'app'
+   */
+  tracerName?: string;
+
+  /**
+   * Meter name for OpenTelemetry metrics
+   * @default 'app'
+   */
+  meterName?: string;
+
+  /**
+   * Custom tracer instance (for advanced use cases like Datadog direct)
+   * @default trace.getTracer(tracerName)
+   */
+  tracer?: Tracer;
+
+  /**
+   * Custom meter instance
+   * @default metrics.getMeter(meterName)
+   */
+  meter?: Meter;
+}
+
+/**
+ * Internal configuration state
+ */
+class Config {
+  private config: Required<InstrumentationConfig> = {
+    tracerName: 'app',
+    meterName: 'app',
+    tracer: getAutotelTracer('app'),
+    meter: metrics.getMeter('app'),
+  };
+
+  /**
+   * Get feature flags
+   */
+  get featureFlags() {
+    return FEATURE_FLAGS;
+  }
+
+  /**
+   * Update global configuration
+   */
+  configure(options: InstrumentationConfig): void {
+    if (options.tracerName) {
+      this.config.tracerName = options.tracerName;
+      this.config.tracer = getAutotelTracer(options.tracerName);
+    }
+    if (options.meterName) {
+      this.config.meterName = options.meterName;
+      this.config.meter = metrics.getMeter(options.meterName);
+    }
+    if (options.tracer) {
+      this.config.tracer = options.tracer;
+    }
+    if (options.meter) {
+      this.config.meter = options.meter;
+    }
+  }
+
+  /**
+   * Get current configuration
+   */
+  get(): Required<InstrumentationConfig> {
+    return this.config;
+  }
+
+  /**
+   * Reset to defaults (mainly for testing)
+   */
+  reset(): void {
+    this.config = {
+      tracerName: 'app',
+      meterName: 'app',
+      tracer: trace.getTracer('app'),
+      meter: metrics.getMeter('app'),
+    };
+  }
+}
+
+const globalConfig = new Config();
+
+/**
+ * Configure global instrumentation behavior
+ *
+ * @example
+ * ```typescript
+ * import { configure } from 'autotel/config'
+ *
+ * configure({
+ *   tracerName: 'my-app'
+ * })
+ * ```
+ */
+export function configure(options: InstrumentationConfig): void {
+  globalConfig.configure(options);
+}
+
+/**
+ * Get current configuration (internal use)
+ */
+export function getConfig(): Required<InstrumentationConfig> & {
+  featureFlags: typeof FEATURE_FLAGS;
+} {
+  return {
+    ...globalConfig.get(),
+    featureFlags: FEATURE_FLAGS,
+  };
+}
+
+/**
+ * Reset configuration to defaults (internal use - mainly for testing)
+ */
+export function resetConfig(): void {
+  globalConfig.reset();
+}

package/src/db.test.ts

@@ -0,0 +1,252 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  instrumentDatabase,
+  tracebQuery,
+  DB_SYSTEMS,
+  DB_OPERATIONS,
+} from './db';
+import { configure, resetConfig } from './config';
+
+describe('instrumentDatabase', () => {
+  beforeEach(() => {
+    resetConfig();
+  });
+
+  it('should instrument database methods', async () => {
+    const mockSpan = {
+      setStatus: vi.fn(),
+      setAttributes: vi.fn(),
+      setAttribute: vi.fn(),
+      end: vi.fn(),
+    };
+
+    const mockTracer = {
+      startActiveSpan: vi.fn((name, fn) => fn(mockSpan)),
+    };
+
+    configure({
+      tracer: mockTracer as any,
+    });
+
+    const repo = {
+      async findUser(id: string) {
+        return { id, name: 'Test' };
+      },
+    };
+
+    instrumentDatabase(repo, {
+      dbSystem: DB_SYSTEMS.POSTGRESQL,
+      dbName: 'testdb',
+    });
+
+    const result = await repo.findUser('123');
+
+    expect(result).toEqual({ id: '123', name: 'Test' });
+    expect(mockTracer.startActiveSpan).toHaveBeenCalledWith(
+      'postgresql.SELECT user',
+      expect.any(Function),
+    );
+    expect(mockSpan.setAttributes).toHaveBeenCalledWith(
+      expect.objectContaining({
+        'db.system': 'postgresql',
+        'db.operation': 'SELECT',
+      }),
+    );
+    expect(mockSpan.setAttribute).toHaveBeenCalledWith('db.name', 'testdb');
+    expect(mockSpan.setAttribute).toHaveBeenCalledWith('db.sql.table', 'user');
+    expect(mockSpan.end).toHaveBeenCalled();
+  });
+
+  it('should infer table names from method names', async () => {
+    const mockSpan = {
+      setStatus: vi.fn(),
+      setAttributes: vi.fn(),
+      setAttribute: vi.fn(),
+      end: vi.fn(),
+    };
+
+    const mockTracer = {
+      startActiveSpan: vi.fn((name, fn) => fn(mockSpan)),
+    };
+
+    configure({
+      tracer: mockTracer as any,
+    });
+
+    const repo = {
+      async createOrder() {
+        return {};
+      },
+      async listUsers() {
+        return [];
+      },
+      async deletePost() {
+        return true;
+      },
+    };
+
+    instrumentDatabase(repo, { dbSystem: 'postgresql' });
+
+    await repo.createOrder();
+    expect(mockTracer.startActiveSpan).toHaveBeenCalledWith(
+      'postgresql.INSERT order',
+      expect.any(Function),
+    );
+
+    await repo.listUsers();
+    expect(mockTracer.startActiveSpan).toHaveBeenCalledWith(
+      'postgresql.SELECT users',
+      expect.any(Function),
+    );
+
+    await repo.deletePost();
+    expect(mockTracer.startActiveSpan).toHaveBeenCalledWith(
+      'postgresql.DELETE post',
+      expect.any(Function),
+    );
+  });
+
+  it('should mark slow queries', async () => {
+    const mockSpan = {
+      setStatus: vi.fn(),
+      setAttributes: vi.fn(),
+      setAttribute: vi.fn(),
+      end: vi.fn(),
+    };
+
+    const mockTracer = {
+      startActiveSpan: vi.fn((name, fn) => fn(mockSpan)),
+    };
+
+    configure({
+      tracer: mockTracer as any,
+    });
+
+    const repo = {
+      async slowQuery() {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        return [];
+      },
+    };
+
+    instrumentDatabase(repo, {
+      dbSystem: 'postgresql',
+      slowQueryThresholdMs: 10, // Very low threshold for testing
+    });
+    await repo.slowQuery();
+
+    expect(mockSpan.setAttribute).toHaveBeenCalledWith('db.slow_query', true);
+    expect(mockSpan.setAttribute).toHaveBeenCalledWith(
+      'db.slow_query_threshold_ms',
+      10,
+    );
+  });
+
+  it('should track result counts for arrays', async () => {
+    const mockSpan = {
+      setStatus: vi.fn(),
+      setAttributes: vi.fn(),
+      setAttribute: vi.fn(),
+      end: vi.fn(),
+    };
+
+    const mockTracer = {
+      startActiveSpan: vi.fn((name, fn) => fn(mockSpan)),
+    };
+
+    configure({
+      tracer: mockTracer as any,
+    });
+
+    const repo = {
+      async listItems() {
+        return [1, 2, 3, 4, 5];
+      },
+    };
+
+    instrumentDatabase(repo, { dbSystem: 'postgresql' });
+    await repo.listItems();
+
+    expect(mockSpan.setAttribute).toHaveBeenCalledWith('db.result_count', 5);
+  });
+
+  it('should handle errors correctly', async () => {
+    const mockSpan = {
+      setStatus: vi.fn(),
+      setAttributes: vi.fn(),
+      setAttribute: vi.fn(),
+      recordException: vi.fn(),
+      end: vi.fn(),
+    };
+
+    const mockTracer = {
+      startActiveSpan: vi.fn((name, fn) => fn(mockSpan)),
+    };
+
+    configure({
+      tracer: mockTracer as any,
+    });
+
+    const repo = {
+      async failingQuery() {
+        throw new Error('Connection timeout');
+      },
+    };
+
+    instrumentDatabase(repo, { dbSystem: 'postgresql' });
+
+    await expect(repo.failingQuery()).rejects.toThrow('Connection timeout');
+
+    expect(mockSpan.setStatus).toHaveBeenCalledWith({
+      code: 2, // SpanStatusCode.ERROR
+      message: 'Connection timeout',
+    });
+    expect(mockSpan.end).toHaveBeenCalled();
+  });
+});
+
+describe('tracebQuery', () => {
+  beforeEach(() => {
+    resetConfig();
+  });
+
+  it('should trace database queries', async () => {
+    const mockSpan = {
+      setStatus: vi.fn(),
+      setAttributes: vi.fn(),
+      setAttribute: vi.fn(),
+      end: vi.fn(),
+    };
+
+    const mockTracer = {
+      startActiveSpan: vi.fn((name, fn) => fn(mockSpan)),
+    };
+
+    configure({
+      tracer: mockTracer as any,
+    });
+
+    const result = await tracebQuery(
+      DB_SYSTEMS.POSTGRESQL,
+      DB_OPERATIONS.SELECT,
+      async () => [{ id: 1 }],
+      {
+        'db.statement': 'SELECT * FROM users',
+      },
+    );
+
+    expect(result).toEqual([{ id: 1 }]);
+    expect(mockTracer.startActiveSpan).toHaveBeenCalledWith(
+      'postgresql.SELECT',
+      expect.any(Function),
+    );
+    expect(mockSpan.setAttributes).toHaveBeenCalledWith(
+      expect.objectContaining({
+        'db.system': 'postgresql',
+        'db.operation': 'SELECT',
+        'db.statement': 'SELECT * FROM users',
+      }),
+    );
+    expect(mockSpan.end).toHaveBeenCalled();
+  });
+});