autotel 2.1.0

package/src/tracer-provider.test.ts

@@ -0,0 +1,183 @@
+/**
+ * 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

@@ -0,0 +1,266 @@
+/**
+ * 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 AUTOLEMETRY_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 {
+  [AUTOLEMETRY_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[AUTOLEMETRY_GLOBAL_SYMBOL]) {
+      Object.defineProperty(g, AUTOLEMETRY_GLOBAL_SYMBOL, {
+        value: initialState,
+        writable: false, // Lock the slot (not the contents)
+        configurable: false,
+        enumerable: false,
+      });
+    }
+
+    return g[AUTOLEMETRY_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

@@ -0,0 +1,153 @@
+/**
+ * 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);
+    });
+  });
+});