autotel 4.1.0 → 4.2.0

package/src/config.ts

@@ -1,172 +0,0 @@
-/**
- * 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;
-
-/**
- * Runtime configuration for OpenTelemetry instrumentation
- *
- * This configures the tracer and meter used by autotel's functional API.
- * Use `configure()` to set custom tracer/meter instances.
- */
-export interface RuntimeConfig {
-  /**
-   * 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<RuntimeConfig> = {
-    tracerName: 'app',
-    meterName: 'app',
-    tracer: getAutotelTracer('app'),
-    meter: metrics.getMeter('app'),
-  };
-
-  /**
-   * Get feature flags
-   */
-  get featureFlags() {
-    return FEATURE_FLAGS;
-  }
-
-  /**
-   * Update global configuration
-   */
-  configure(options: RuntimeConfig): 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<RuntimeConfig> {
-    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: RuntimeConfig): void {
-  globalConfig.configure(options);
-}
-
-/**
- * Get current configuration (internal use)
- */
-export function getConfig(): Required<RuntimeConfig> & {
-  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/correlated-events.test.ts

@@ -1,151 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import {
-  emitCorrelatedEvent,
-  type CorrelatedEventTarget,
-} from './correlated-events';
-
-function makeTarget(opts: { withAddEvent: boolean }): {
-  target: CorrelatedEventTarget;
-  setAttribute: ReturnType<typeof vi.fn>;
-  setAttributes: ReturnType<typeof vi.fn>;
-  addEvent: ReturnType<typeof vi.fn> | undefined;
-} {
-  const setAttribute = vi.fn();
-  const setAttributes = vi.fn();
-  const addEvent = opts.withAddEvent ? vi.fn() : undefined;
-  const target: CorrelatedEventTarget = addEvent
-    ? { setAttribute, setAttributes, addEvent }
-    : { setAttribute, setAttributes };
-  return { target, setAttribute, setAttributes, addEvent };
-}
-
-describe('emitCorrelatedEvent', () => {
-  describe('addEvent path', () => {
-    it('forwards to addEvent when present and skips the attribute fallback', () => {
-      const { target, setAttribute, setAttributes, addEvent } = makeTarget({
-        withAddEvent: true,
-      });
-
-      emitCorrelatedEvent(target, 'gen_ai.prompt.sent', {
-        'gen_ai.system': 'openai',
-      });
-
-      expect(addEvent).toHaveBeenCalledTimes(1);
-      expect(addEvent).toHaveBeenCalledWith('gen_ai.prompt.sent', {
-        'gen_ai.system': 'openai',
-      });
-      expect(setAttribute).not.toHaveBeenCalled();
-      expect(setAttributes).not.toHaveBeenCalled();
-    });
-
-    it('sanitizes the event name before forwarding', () => {
-      const { target, addEvent } = makeTarget({ withAddEvent: true });
-
-      emitCorrelatedEvent(target, 'gen ai/prompt sent!', {});
-
-      expect(addEvent).toHaveBeenCalledWith('gen_ai_prompt_sent_', {});
-    });
-
-    it('preserves `this` when calling addEvent (works for prototype methods)', () => {
-      const captured: { self: unknown; args: unknown[] } = {
-        self: null,
-        args: [],
-      };
-      const target = {
-        setAttribute: vi.fn(),
-        setAttributes: vi.fn(),
-        addEvent(this: unknown, ...args: unknown[]) {
-          captured.self = this;
-          captured.args = args;
-        },
-      };
-
-      emitCorrelatedEvent(target, 'evt', { k: 'v' });
-
-      expect(captured.self).toBe(target);
-      expect(captured.args).toEqual(['evt', { k: 'v' }]);
-    });
-  });
-
-  describe('attribute fallback', () => {
-    it('writes flat, sequence-prefixed attributes when addEvent is missing', () => {
-      const { target, setAttributes } = makeTarget({ withAddEvent: false });
-
-      emitCorrelatedEvent(target, 'workflow.started', {
-        'workflow.id': 'wf-1',
-      });
-
-      expect(setAttributes).toHaveBeenCalledTimes(1);
-      const written = setAttributes.mock.calls[0]![0] as Record<
-        string,
-        unknown
-      >;
-
-      expect(written['autotel.event.1.workflow.started.name']).toBe(
-        'workflow.started',
-      );
-      expect(typeof written['autotel.event.1.workflow.started.ts']).toBe(
-        'string',
-      );
-      expect(written['autotel.event.1.workflow.started.workflow.id']).toBe(
-        'wf-1',
-      );
-    });
-
-    it('does not overwrite earlier events when the same name fires twice', () => {
-      const { target, setAttributes } = makeTarget({ withAddEvent: false });
-
-      emitCorrelatedEvent(target, 'step_retry', { 'workflow.step.attempt': 1 });
-      emitCorrelatedEvent(target, 'step_retry', { 'workflow.step.attempt': 2 });
-
-      expect(setAttributes).toHaveBeenCalledTimes(2);
-      const first = setAttributes.mock.calls[0]![0] as Record<string, unknown>;
-      const second = setAttributes.mock.calls[1]![0] as Record<string, unknown>;
-
-      expect(first['autotel.event.1.step_retry.workflow.step.attempt']).toBe(1);
-      expect(second['autotel.event.2.step_retry.workflow.step.attempt']).toBe(
-        2,
-      );
-
-      // Different keys: second call cannot overwrite the first when both
-      // attribute sets are merged on the same span.
-      expect(
-        Object.keys(first).every((k) => !Object.keys(second).includes(k)),
-      ).toBe(true);
-    });
-
-    it('sanitizes attribute keys in the fallback path', () => {
-      const { target, setAttributes } = makeTarget({ withAddEvent: false });
-
-      emitCorrelatedEvent(target, 'evt', { 'has spaces/and-bad!': 1 });
-
-      const written = setAttributes.mock.calls[0]![0] as Record<
-        string,
-        unknown
-      >;
-      const key = Object.keys(written).find((k) =>
-        k.endsWith('has_spaces_and-bad_'),
-      );
-      expect(key).toBeDefined();
-      expect(written[key!]).toBe(1);
-    });
-
-    it('keeps separate sequences for separate targets', () => {
-      const a = makeTarget({ withAddEvent: false });
-      const b = makeTarget({ withAddEvent: false });
-
-      emitCorrelatedEvent(a.target, 'evt', {});
-      emitCorrelatedEvent(b.target, 'evt', {});
-
-      const aKeys = Object.keys(
-        a.setAttributes.mock.calls[0]![0] as Record<string, unknown>,
-      );
-      const bKeys = Object.keys(
-        b.setAttributes.mock.calls[0]![0] as Record<string, unknown>,
-      );
-
-      expect(aKeys.some((k) => k.startsWith('autotel.event.1.'))).toBe(true);
-      expect(bKeys.some((k) => k.startsWith('autotel.event.1.'))).toBe(true);
-    });
-  });
-});

package/src/correlated-events.ts

@@ -1,47 +0,0 @@
-import type { AttributeValue } from './trace-context';
-
-export interface CorrelatedEventTarget {
-  setAttribute(key: string, value: AttributeValue): unknown;
-  setAttributes(attrs: Record<string, AttributeValue>): unknown;
-  addEvent?(name: string, attrs?: Record<string, AttributeValue>): unknown;
-}
-
-// OTel attribute keys are dot-namespaced flat strings; we keep `.`/`-`/`_` and
-// drop everything else so user-supplied event names can't break attribute keys.
-function sanitizeEventKey(input: string): string {
-  return input.replaceAll(/[^a-zA-Z0-9_.-]/g, '_');
-}
-
-// Per-target sequence so the fallback path can encode multiple events with the
-// same name without one overwriting the previous (attributes are
-// last-write-wins; events are not). Today the addEvent path is always taken;
-// this keeps the fallback correct if/when the runtime stops binding addEvent.
-const sequenceByTarget = new WeakMap<object, number>();
-
-function nextSequence(target: object): number {
-  const n = (sequenceByTarget.get(target) ?? 0) + 1;
-  sequenceByTarget.set(target, n);
-  return n;
-}
-
-export function emitCorrelatedEvent(
-  ctx: CorrelatedEventTarget,
-  name: string,
-  attrs: Record<string, AttributeValue> = {},
-): void {
-  const eventName = sanitizeEventKey(name);
-  if (typeof ctx.addEvent === 'function') {
-    ctx.addEvent.call(ctx, eventName, attrs);
-    return;
-  }
-  const seq = nextSequence(ctx);
-  const prefix = `autotel.event.${seq}.${eventName}`;
-  const flattened: Record<string, AttributeValue> = {
-    [`${prefix}.name`]: eventName,
-    [`${prefix}.ts`]: new Date().toISOString(),
-  };
-  for (const [k, v] of Object.entries(attrs)) {
-    flattened[`${prefix}.${sanitizeEventKey(k)}`] = v;
-  }
-  ctx.setAttributes(flattened);
-}

package/src/correlation-id.test.ts

@@ -1,163 +0,0 @@
-/**
- * Tests for correlation ID generation and propagation
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-import {
-  generateCorrelationId,
-  getCorrelationId,
-  getOrCreateCorrelationId,
-  runWithCorrelationId,
-  getCorrelationStorage,
-} from './correlation-id';
-
-describe('Correlation ID', () => {
-  beforeEach(() => {
-    // Clear the async local storage before each test
-    // Run with undefined context to clear - safer than enterWith with type assertion
-    getCorrelationStorage().disable();
-  });
-
-  describe('generateCorrelationId', () => {
-    it('should generate 16 hex character ID', () => {
-      const id = generateCorrelationId();
-      expect(id).toHaveLength(16);
-      expect(/^[0-9a-f]{16}$/.test(id)).toBe(true);
-    });
-
-    it('should generate unique IDs', () => {
-      const ids = new Set<string>();
-      for (let i = 0; i < 100; i++) {
-        ids.add(generateCorrelationId());
-      }
-      // All 100 IDs should be unique
-      expect(ids.size).toBe(100);
-    });
-
-    it('should generate URL-safe IDs (hex only)', () => {
-      for (let i = 0; i < 50; i++) {
-        const id = generateCorrelationId();
-        // Should only contain hex characters
-        expect(/^[0-9a-f]+$/.test(id)).toBe(true);
-        // Should be URL-safe (no special characters)
-        expect(encodeURIComponent(id)).toBe(id);
-      }
-    });
-  });
-
-  describe('getCorrelationId', () => {
-    it('should return undefined when no correlation ID is set', () => {
-      const id = getCorrelationId();
-      expect(id).toBeUndefined();
-    });
-  });
-
-  describe('runWithCorrelationId', () => {
-    it('should set correlation ID within callback', () => {
-      const testId = 'test123456789012';
-
-      runWithCorrelationId(testId, () => {
-        expect(getCorrelationId()).toBe(testId);
-      });
-    });
-
-    it('should return callback result', () => {
-      const result = runWithCorrelationId('abc123def4567890', () => {
-        return 'test-result';
-      });
-
-      expect(result).toBe('test-result');
-    });
-
-    it('should isolate correlation ID to callback scope', () => {
-      expect(getCorrelationId()).toBeUndefined();
-
-      runWithCorrelationId('scoped-id-12345678', () => {
-        expect(getCorrelationId()).toBe('scoped-id-12345678');
-      });
-
-      // After callback, should be back to undefined
-      expect(getCorrelationId()).toBeUndefined();
-    });
-
-    it('should support nested runWithCorrelationId calls', () => {
-      runWithCorrelationId('outer-id-1234567', () => {
-        expect(getCorrelationId()).toBe('outer-id-1234567');
-
-        runWithCorrelationId('inner-id-7654321', () => {
-          expect(getCorrelationId()).toBe('inner-id-7654321');
-        });
-
-        // After inner callback, should be back to outer
-        expect(getCorrelationId()).toBe('outer-id-1234567');
-      });
-    });
-
-    it('should work with async callbacks', async () => {
-      const result = await runWithCorrelationId('async-id-123456', async () => {
-        // Simulate async work
-        await new Promise((resolve) => setTimeout(resolve, 10));
-        return getCorrelationId();
-      });
-
-      expect(result).toBe('async-id-123456');
-    });
-  });
-
-  describe('getOrCreateCorrelationId', () => {
-    it('should return existing correlation ID if set', () => {
-      const existingId = 'existing-id-1234';
-
-      runWithCorrelationId(existingId, () => {
-        const id = getOrCreateCorrelationId();
-        expect(id).toBe(existingId);
-      });
-    });
-
-    it('should generate new ID if not set', () => {
-      // No correlation ID set
-      const id = getOrCreateCorrelationId();
-
-      expect(id).toBeDefined();
-      expect(id).toHaveLength(16);
-      expect(/^[0-9a-f]{16}$/.test(id)).toBe(true);
-    });
-
-    it('should return same ID on repeated calls within same context', () => {
-      runWithCorrelationId('stable-id-123456', () => {
-        const id1 = getOrCreateCorrelationId();
-        const id2 = getOrCreateCorrelationId();
-        expect(id1).toBe(id2);
-      });
-    });
-  });
-
-  describe('format specification', () => {
-    it('should be exactly 16 characters (64 bits)', () => {
-      for (let i = 0; i < 20; i++) {
-        const id = generateCorrelationId();
-        expect(id.length).toBe(16);
-      }
-    });
-
-    it('should be crypto-random (not time-based)', () => {
-      // Generate two IDs in quick succession
-      const id1 = generateCorrelationId();
-      const id2 = generateCorrelationId();
-
-      // If time-based, first chars would likely be similar
-      // With crypto-random, they should be completely different
-      expect(id1).not.toBe(id2);
-
-      // Check that the IDs don't have a predictable pattern
-      // (This is a statistical test - very unlikely to fail with crypto-random)
-      const firstChars = [];
-      for (let i = 0; i < 10; i++) {
-        firstChars.push(generateCorrelationId()[0]);
-      }
-      // With crypto-random, we shouldn't see all the same first character
-      const uniqueFirstChars = new Set(firstChars);
-      expect(uniqueFirstChars.size).toBeGreaterThan(1);
-    });
-  });
-});