autotel 4.1.0 → 4.2.0

package/src/trace-hybrid.test.ts

@@ -1,42 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { trace as otelTraceApi } from '@opentelemetry/api';
-import { trace } from './trace-hybrid';
-
-describe('hybrid trace', () => {
-  it('is callable like autotel trace', () => {
-    expect(typeof trace).toBe('function');
-
-    const wrapped = trace(async (x: number) => x * 2);
-    expect(typeof wrapped).toBe('function');
-  });
-
-  it('exposes the OTel TraceAPI surface', () => {
-    expect(typeof trace.getActiveSpan).toBe('function');
-    expect(typeof trace.getTracer).toBe('function');
-    expect(typeof trace.getTracerProvider).toBe('function');
-    expect(typeof trace.setSpan).toBe('function');
-    expect(typeof trace.getSpan).toBe('function');
-    expect(typeof trace.setSpanContext).toBe('function');
-    expect(typeof trace.getSpanContext).toBe('function');
-    expect(typeof trace.deleteSpan).toBe('function');
-    expect(typeof trace.wrapSpanContext).toBe('function');
-    expect(typeof trace.isSpanContextValid).toBe('function');
-    expect(typeof trace.disable).toBe('function');
-    expect(typeof trace.setGlobalTracerProvider).toBe('function');
-  });
-
-  it('forwards getActiveSpan / getTracerProvider to the OTel singleton', () => {
-    expect(trace.getActiveSpan()).toBe(otelTraceApi.getActiveSpan());
-    // Same TracerProvider singleton — guarantees getTracer goes through one
-    // place. (Tracer instances themselves may not be referentially identical
-    // because the proxy creates a new wrapper per call.)
-    expect(trace.getTracerProvider()).toBe(otelTraceApi.getTracerProvider());
-  });
-
-  it('preserves `this` for class methods (no unbound-this errors)', () => {
-    // setGlobalTracerProvider/getTracerProvider rely on `this._proxyTracerProvider`.
-    // Calling through the destructured reference must not throw.
-    const { getTracerProvider } = trace;
-    expect(() => getTracerProvider()).not.toThrow();
-  });
-});

package/src/trace-hybrid.ts

@@ -1,37 +0,0 @@
-/**
- * Hybrid `trace` export: callable like autotel's `trace(fn)`, AND exposes the
- * full `@opentelemetry/api` `TraceAPI` surface (`trace.getActiveSpan()`,
- * `trace.getTracer()`, …) so existing OTel code "just works" when imported
- * from `autotel`.
- *
- * Implementation: `Object.assign` mutates the autotel `trace` function to
- * attach the OTel TraceAPI methods. Because every reference to `trace` across
- * autotel resolves to the same function instance, this is a one-time, global
- * augmentation.
- */
-
-import { trace as otelTraceApi } from '@opentelemetry/api';
-import { trace as autotelTraceFn } from './functional';
-
-const otelMethods = {
-  // Class methods on TraceAPI — bind to the singleton.
-  setGlobalTracerProvider:
-    otelTraceApi.setGlobalTracerProvider.bind(otelTraceApi),
-  getTracerProvider: otelTraceApi.getTracerProvider.bind(otelTraceApi),
-  getTracer: otelTraceApi.getTracer.bind(otelTraceApi),
-  disable: otelTraceApi.disable.bind(otelTraceApi),
-  // Instance fields on TraceAPI — already standalone, copy by reference.
-  wrapSpanContext: otelTraceApi.wrapSpanContext,
-  isSpanContextValid: otelTraceApi.isSpanContextValid,
-  deleteSpan: otelTraceApi.deleteSpan,
-  getSpan: otelTraceApi.getSpan,
-  getActiveSpan: otelTraceApi.getActiveSpan,
-  getSpanContext: otelTraceApi.getSpanContext,
-  setSpan: otelTraceApi.setSpan,
-  setSpanContext: otelTraceApi.setSpanContext,
-};
-
-export const trace: typeof autotelTraceFn & typeof otelTraceApi = Object.assign(
-  autotelTraceFn,
-  otelMethods,
-) as typeof autotelTraceFn & typeof otelTraceApi;

package/src/tracer-provider.test.ts

@@ -1,183 +0,0 @@
-/**
- * Tests for isolated tracer provider support
- */
-
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import {
-  setAutotelTracerProvider,
-  getAutotelTracerProvider,
-  getAutotelTracer,
-} from './tracer-provider';
-import { trace } from '@opentelemetry/api';
-import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
-
-describe('Isolated Tracer Provider', () => {
-  let customProvider: NodeTracerProvider;
-
-  beforeEach(() => {
-    // Create a custom provider for testing
-    customProvider = new NodeTracerProvider();
-  });
-
-  afterEach(() => {
-    // Clean up: reset to null after each test
-    setAutotelTracerProvider(null);
-  });
-
-  describe('setAutotelTracerProvider', () => {
-    it('should set isolated provider', () => {
-      setAutotelTracerProvider(customProvider);
-
-      const provider = getAutotelTracerProvider();
-      expect(provider).toBe(customProvider);
-    });
-
-    it('should clear isolated provider when set to null', () => {
-      setAutotelTracerProvider(customProvider);
-      setAutotelTracerProvider(null);
-
-      const provider = getAutotelTracerProvider();
-      // Should fall back to global provider
-      expect(provider).toBe(trace.getTracerProvider());
-    });
-
-    it('should allow overwriting existing isolated provider', () => {
-      const provider1 = new NodeTracerProvider();
-      const provider2 = new NodeTracerProvider();
-
-      setAutotelTracerProvider(provider1);
-      expect(getAutotelTracerProvider()).toBe(provider1);
-
-      setAutotelTracerProvider(provider2);
-      expect(getAutotelTracerProvider()).toBe(provider2);
-    });
-  });
-
-  describe('getAutotelTracerProvider', () => {
-    it('should return isolated provider when set', () => {
-      setAutotelTracerProvider(customProvider);
-
-      const provider = getAutotelTracerProvider();
-      expect(provider).toBe(customProvider);
-    });
-
-    it('should return global provider when no isolated provider is set', () => {
-      const provider = getAutotelTracerProvider();
-      expect(provider).toBe(trace.getTracerProvider());
-    });
-
-    it('should be idempotent', () => {
-      setAutotelTracerProvider(customProvider);
-
-      const provider1 = getAutotelTracerProvider();
-      const provider2 = getAutotelTracerProvider();
-
-      expect(provider1).toBe(provider2);
-    });
-  });
-
-  describe('getAutotelTracer', () => {
-    it('should return tracer from isolated provider when set', () => {
-      setAutotelTracerProvider(customProvider);
-
-      const tracer = getAutotelTracer('test-tracer');
-
-      // Verify tracer is from custom provider
-      // (We can't directly compare tracers, but we can verify it's not throwing)
-      expect(tracer).toBeDefined();
-      expect(typeof tracer.startSpan).toBe('function');
-    });
-
-    it('should return tracer from global provider when no isolated provider is set', () => {
-      const tracer = getAutotelTracer('test-tracer');
-
-      expect(tracer).toBeDefined();
-      expect(typeof tracer.startSpan).toBe('function');
-    });
-
-    it('should use default tracer name when not specified', () => {
-      setAutotelTracerProvider(customProvider);
-
-      const tracer = getAutotelTracer();
-
-      expect(tracer).toBeDefined();
-    });
-
-    it('should respect custom tracer name', () => {
-      setAutotelTracerProvider(customProvider);
-
-      const tracer = getAutotelTracer('custom-name', '1.0.0');
-
-      expect(tracer).toBeDefined();
-    });
-
-    it('should support version parameter', () => {
-      setAutotelTracerProvider(customProvider);
-
-      const tracer = getAutotelTracer('my-service', '2.0.0');
-
-      expect(tracer).toBeDefined();
-    });
-  });
-
-  describe('Integration with Autotel config', () => {
-    it('should allow isolated provider to work independently of init()', () => {
-      // Don't call init(), just set isolated provider
-      setAutotelTracerProvider(customProvider);
-
-      const tracer = getAutotelTracer('standalone');
-      expect(tracer).toBeDefined();
-
-      // Should be able to create spans
-      const span = tracer.startSpan('test-span');
-      expect(span).toBeDefined();
-      expect(typeof span.end).toBe('function');
-      span.end();
-    });
-
-    it('should persist across multiple getTracer calls', () => {
-      setAutotelTracerProvider(customProvider);
-
-      const tracer1 = getAutotelTracer('service-1');
-      const tracer2 = getAutotelTracer('service-2');
-
-      // Both should come from the same provider
-      expect(tracer1).toBeDefined();
-      expect(tracer2).toBeDefined();
-    });
-  });
-
-  describe('Global state isolation', () => {
-    it('should not affect global OTel provider', () => {
-      const globalProvider = trace.getTracerProvider();
-
-      setAutotelTracerProvider(customProvider);
-
-      // Global provider should remain unchanged
-      expect(trace.getTracerProvider()).toBe(globalProvider);
-      // But Autotel provider should be our custom one
-      expect(getAutotelTracerProvider()).toBe(customProvider);
-    });
-
-    it('should allow both global and isolated providers to coexist', () => {
-      const _globalProvider = trace.getTracerProvider();
-      setAutotelTracerProvider(customProvider);
-
-      const globalTracer = trace.getTracer('global-tracer');
-      const isolatedTracer = getAutotelTracer('isolated-tracer');
-
-      expect(globalTracer).toBeDefined();
-      expect(isolatedTracer).toBeDefined();
-
-      // Can create spans from both
-      const globalSpan = globalTracer.startSpan('global-span');
-      const isolatedSpan = isolatedTracer.startSpan('isolated-span');
-
-      expect(globalSpan).toBeDefined();
-      expect(isolatedSpan).toBeDefined();
-
-      globalSpan.end();
-      isolatedSpan.end();
-    });
-  });
-});

package/src/tracer-provider.ts

@@ -1,266 +0,0 @@
-/**
- * Isolated tracer provider support for Autotel
- *
- * Allows Autotel to use a separate TracerProvider instance, avoiding conflicts
- * with other OpenTelemetry instrumentation in the application.
- *
- * **Use Case:** Library authors who want to use Autotel without interfering
- * with the application's global OpenTelemetry setup.
- *
- * **Limitation:** While this isolates span processing and export, OpenTelemetry
- * context (trace IDs, parent spans) is still shared globally. Spans created with
- * the isolated provider may inherit trace context from global spans.
- */
-
-import { trace } from '@opentelemetry/api';
-import type { TracerProvider } from '@opentelemetry/api';
-
-/**
- * Symbol for storing isolated tracer provider in global scope
- * Using Symbol.for() ensures the same symbol across module boundaries
- */
-const AUTOTEL_GLOBAL_SYMBOL = Symbol.for('autotel');
-
-/**
- * Global state for Autotel
- */
-type AutotelGlobalState = {
-  isolatedTracerProvider: TracerProvider | null;
-};
-
-/**
- * Create initial state
- */
-function createState(): AutotelGlobalState {
-  return {
-    isolatedTracerProvider: null,
-  };
-}
-
-/**
- * Extend globalThis to include our symbol
- */
-interface GlobalThis {
-  [AUTOTEL_GLOBAL_SYMBOL]?: AutotelGlobalState;
-}
-
-/**
- * Get the global state, creating it if it doesn't exist
- * Handles edge cases like missing globalThis
- */
-function getGlobalState(): AutotelGlobalState {
-  const initialState = createState();
-
-  try {
-    const g = globalThis as typeof globalThis & GlobalThis;
-
-    if (typeof g !== 'object' || g === null) {
-      console.warn(
-        '[autotel] globalThis is not available, using fallback state',
-      );
-      return initialState;
-    }
-
-    if (!g[AUTOTEL_GLOBAL_SYMBOL]) {
-      Object.defineProperty(g, AUTOTEL_GLOBAL_SYMBOL, {
-        value: initialState,
-        writable: false, // Lock the slot (not the contents)
-        configurable: false,
-        enumerable: false,
-      });
-    }
-
-    return g[AUTOTEL_GLOBAL_SYMBOL]!;
-  } catch (error) {
-    if (error instanceof Error) {
-      console.error(
-        `[autotel] Failed to access global state: ${error.message}`,
-      );
-    } else {
-      console.error(
-        `[autotel] Failed to access global state: ${String(error)}`,
-      );
-    }
-
-    return initialState;
-  }
-}
-
-/**
- * Sets an isolated TracerProvider for Autotel tracing operations.
- *
- * This allows Autotel to use its own TracerProvider instance, separate from
- * the global OpenTelemetry TracerProvider. This is useful for avoiding conflicts
- * with other OpenTelemetry instrumentation in the application.
- *
- * **Limitation: Span Context Sharing**
- *
- * While this function isolates span processing and export, it does NOT provide
- * complete trace isolation. OpenTelemetry context (trace IDs, parent spans) is
- * still shared between the global and isolated providers. This means:
- *
- * - Spans created with the isolated provider inherit trace IDs from global spans
- * - Spans created with the isolated provider inherit parent relationships from global spans
- * - This can result in spans from different providers being part of the same logical trace
- *
- * **Why this happens:**
- * OpenTelemetry uses a global context propagation mechanism that operates at the
- * JavaScript runtime level, independent of individual TracerProvider instances.
- * The context (containing trace ID, span ID) flows through async boundaries and
- * is inherited by all spans created within that context, regardless of which
- * TracerProvider creates them.
- *
- * **When to use this:**
- * - Library code that ships with embedded Autotel
- * - SDKs that want observability without requiring users to set up OpenTelemetry
- * - Applications that need separate span processing for different subsystems
- * - Testing scenarios where you want to isolate trace collection
- *
- * @param provider - The TracerProvider instance to use, or null to clear the isolated provider
- *
- * @example Library with embedded Autotel
- * ```typescript
- * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
- * import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'
- * import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
- * import { setAutolem
-
-etryTracerProvider } from 'autotel/tracer-provider'
- *
- * // Create provider with span processors in constructor
- * const exporter = new OTLPTraceExporter({
- *   url: 'https://your-backend.com/v1/traces'
- * })
- *
- * const provider = new NodeTracerProvider()
- * provider.addSpanProcessor(new BatchSpanProcessor(exporter))
- *
- * // Set as Autotel's isolated provider (doesn't call provider.register())
- * setAutotelTracerProvider(provider)
- *
- * // Now all Autotel trace() calls use this provider
- * // But won't interfere with the application's global OpenTelemetry setup
- * ```
- *
- * @example Testing with isolated provider
- * ```typescript
- * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
- * import { InMemorySpanExporter } from '@opentelemetry/sdk-trace-base'
- * import { setAutotelTracerProvider } from 'autotel/tracer-provider'
- *
- * // Test setup
- * const exporter = new InMemorySpanExporter()
- * const provider = new NodeTracerProvider()
- * provider.addSpanProcessor(new SimpleSpanProcessor(exporter))
- *
- * setAutotelTracerProvider(provider)
- *
- * // Run tests...
- * const spans = exporter.getFinishedSpans()
- *
- * // Cleanup
- * setAutotelTracerProvider(null)
- * ```
- *
- * @example Multiple subsystems with different exporters
- * ```typescript
- * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
- * import { setAutotelTracerProvider } from 'autotel/tracer-provider'
- *
- * // Payment subsystem - send to payment team's backend
- * const paymentProvider = new NodeTracerProvider()
- * paymentProvider.addSpanProcessor(new BatchSpanProcessor(
- *   new OTLPTraceExporter({ url: 'https://payment-team-backend.com/v1/traces' })
- * ))
- *
- * // In payment module initialization
- * setAutotelTracerProvider(paymentProvider)
- * ```
- *
- * @public
- */
-export function setAutotelTracerProvider(
-  provider: TracerProvider | null,
-): void {
-  getGlobalState().isolatedTracerProvider = provider;
-}
-
-/**
- * Gets the TracerProvider for Autotel tracing operations.
- *
- * Returns the isolated TracerProvider if one has been set via setAutotelTracerProvider(),
- * otherwise falls back to the global OpenTelemetry TracerProvider.
- *
- * This function is used internally by Autotel's trace functions. Most users
- * will not need to call this directly.
- *
- * @returns The TracerProvider instance to use for Autotel tracing
- *
- * @example Getting the current provider
- * ```typescript
- * import { getAutotelTracerProvider } from 'autotel/tracer-provider'
- *
- * const provider = getAutotelTracerProvider()
- * const tracer = provider.getTracer('my-service', '1.0.0')
- * ```
- *
- * @example Checking if isolated provider is active
- * ```typescript
- * import { getAutotelTracerProvider, setAutotelTracerProvider } from 'autotel/tracer-provider'
- * import { trace } from '@opentelemetry/api'
- *
- * const currentProvider = getAutotelTracerProvider()
- * const globalProvider = trace.getTracerProvider()
- *
- * if (currentProvider === globalProvider) {
- *   console.log('Using global provider')
- * } else {
- *   console.log('Using isolated provider')
- * }
- * ```
- *
- * @public
- */
-export function getAutotelTracerProvider(): TracerProvider {
-  const { isolatedTracerProvider } = getGlobalState();
-
-  if (isolatedTracerProvider) return isolatedTracerProvider;
-
-  return trace.getTracerProvider();
-}
-
-/**
- * Gets the OpenTelemetry tracer instance for Autotel.
- *
- * This function returns a tracer specifically configured for Autotel
- * with the correct tracer name and version. Used internally by all
- * Autotel tracing functions to ensure consistent trace creation.
- *
- * Uses the isolated provider if set, otherwise uses the global provider.
- *
- * @param name - Tracer name (default: 'autotel')
- * @param version - Optional version string
- * @returns The Autotel OpenTelemetry tracer instance
- *
- * @example Basic usage
- * ```typescript
- * import { getAutotelTracer } from 'autotel/tracer-provider'
- *
- * const tracer = getAutotelTracer()
- * const span = tracer.startSpan('my-operation')
- * // ... use span
- * span.end()
- * ```
- *
- * @example Custom tracer name
- * ```typescript
- * import { getAutotelTracer } from 'autotel/tracer-provider'
- *
- * const tracer = getAutotelTracer('my-library', '2.1.0')
- * ```
- *
- * @public
- */
-export function getAutotelTracer(name = 'autotel', version?: string) {
-  return getAutotelTracerProvider().getTracer(name, version);
-}

package/src/track.test.ts

@@ -1,154 +0,0 @@
-/**
- * Tests for track() function
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { trace } from '@opentelemetry/api';
-import { track, getEventQueue } from './track';
-import { init, getLogger } from './init';
-
-type TrackedEvent = {
-  name: string;
-  attributes?: Record<string, unknown>;
-};
-
-// Mock adapter for testing
-class MockAdapter {
-  public events: TrackedEvent[] = [];
-
-  async trackEvent(
-    name: string,
-    attributes?: Record<string, unknown>,
-  ): Promise<void> {
-    this.events.push({ name, attributes });
-  }
-
-  async trackFunnelStep(): Promise<void> {}
-  async trackOutcome(): Promise<void> {}
-  async trackValue(): Promise<void> {}
-}
-
-describe('track() function', () => {
-  let mockAdapter: MockAdapter;
-  let loggerWarnSpy: ReturnType<typeof vi.spyOn> | null = null;
-
-  beforeEach(() => {
-    vi.resetModules();
-    mockAdapter = new MockAdapter();
-  });
-
-  afterEach(() => {
-    if (loggerWarnSpy) {
-      loggerWarnSpy.mockRestore();
-    }
-  });
-
-  describe('Initialization checks', () => {
-    it('should warn in dev if track() called before init()', () => {
-      process.env.NODE_ENV = 'development';
-
-      // Spy on logger after it's initialized (it uses default silent logger initially)
-      loggerWarnSpy = vi.spyOn(getLogger(), 'warn');
-
-      track('test.event', { foo: 'bar' });
-
-      expect(loggerWarnSpy).toHaveBeenCalledWith(
-        {},
-        expect.stringContaining('track() used before init()'),
-      );
-    });
-
-    it('should not throw in production if track() called before init()', () => {
-      process.env.NODE_ENV = 'production';
-
-      expect(() => {
-        track('test.event', { foo: 'bar' });
-      }).not.toThrow();
-    });
-
-    it('should be no-op if no adapters configured', () => {
-      init({ service: 'test-app' }); // No adapters
-
-      expect(() => {
-        track('test.event', { foo: 'bar' });
-      }).not.toThrow();
-
-      const queue = getEventQueue();
-      expect(queue).toBeNull();
-    });
-  });
-
-  describe('Event tracking', () => {
-    beforeEach(() => {
-      init({
-        service: 'test-app',
-        subscribers: [mockAdapter],
-      });
-    });
-
-    it('should enqueue events', () => {
-      track('user.signup', { userId: '123', plan: 'pro' });
-
-      const queue = getEventQueue();
-      expect(queue).not.toBeNull();
-      expect(queue?.size()).toBeGreaterThan(0);
-    });
-
-    it('should track event name and attributes', () => {
-      track('user.signup', { userId: '123', plan: 'pro' });
-
-      // Queue batches events, so we need to flush
-      // In real usage, this would be automatic
-    });
-  });
-
-  describe('Trace correlation', () => {
-    beforeEach(() => {
-      init({
-        service: 'test-app',
-        subscribers: [mockAdapter],
-      });
-    });
-
-    it('should auto-attach traceId and spanId when in active span', () => {
-      const tracer = trace.getTracer('test');
-
-      tracer.startActiveSpan('test-span', (span) => {
-        track('user.signup', { userId: '123' });
-
-        // Verify event was enqueued with trace context
-        const queue = getEventQueue();
-        expect(queue).not.toBeNull();
-
-        span.end();
-      });
-    });
-
-    it('should not fail if no active span', () => {
-      expect(() => {
-        track('user.signup', { userId: '123' });
-      }).not.toThrow();
-    });
-  });
-
-  describe('Type safety', () => {
-    beforeEach(() => {
-      init({
-        service: 'test-app',
-        subscribers: [mockAdapter],
-      });
-    });
-
-    it('should accept typed events', () => {
-      interface Events {
-        'user.signup': { userId: string; plan: string };
-      }
-
-      // Type-safe call (TypeScript would catch errors here)
-      track<Events>('user.signup', { userId: '123', plan: 'pro' });
-
-      const queue = getEventQueue();
-      expect(queue!.size()).toBeGreaterThan(0);
-    });
-  });
-});