autotel 4.0.0 → 4.2.0

package/src/events-config.ts

@@ -1,235 +0,0 @@
-/**
- * Events configuration types for trace context, correlation IDs, and enrichment
- *
- * @example Basic usage
- * ```typescript
- * import { init } from 'autotel';
- *
- * init({
- *   service: 'my-app',
- *   events: {
- *     includeTraceContext: true,
- *     traceUrl: (ctx) => `https://grafana.internal/explore?traceId=${ctx.traceId}`
- *   }
- * });
- * ```
- */
-
-/**
- * Context passed to the traceUrl function for generating clickable trace URLs
- */
-export interface TraceUrlContext {
-  /** Trace ID (32 hex chars) - may be undefined outside a trace */
-  traceId?: string;
-  /** Span ID (16 hex chars) - may be undefined outside a trace */
-  spanId?: string;
-  /** Correlation ID (always present, 16 hex chars) */
-  correlationId: string;
-  /** Service name from init config */
-  serviceName: string;
-  /** Environment from init config */
-  environment?: string;
-}
-
-/**
- * Per-key transform options for baggage enrichment
- */
-export type BaggageTransform = 'plain' | 'hash' | ((value: string) => string);
-
-/**
- * Baggage enrichment configuration with guardrails
- */
-export interface EnrichFromBaggageConfig {
-  /**
-   * Allowlist of baggage keys to include in events
-   * Supports exact matches and patterns (e.g., 'tenant.*')
-   */
-  allow: string[];
-
-  /**
-   * Optional denylist of baggage keys to exclude
-   * Takes precedence over allow list
-   */
-  deny?: string[];
-
-  /**
-   * Optional prefix to add to all enriched keys
-   * @example 'ctx.' results in 'ctx.tenant.id'
-   */
-  prefix?: string;
-
-  /**
-   * Maximum number of keys to include (default: 10)
-   * Prevents payload bloat from excessive baggage
-   */
-  maxKeys?: number;
-
-  /**
-   * Maximum total bytes for enriched values (default: 1024)
-   * Prevents payload bloat from large baggage values
-   */
-  maxBytes?: number;
-
-  /**
-   * Per-key transform options
-   * - 'plain': Include value as-is
-   * - 'hash': Hash the value (for PII protection)
-   * - function: Custom transform function
-   *
-   * @example
-   * ```typescript
-   * transform: {
-   *   'user.id': 'hash',      // Hash user ID for privacy
-   *   'tenant.id': 'plain',   // Include tenant ID as-is
-   *   'session.id': (v) => v.slice(0, 8) // Custom truncation
-   * }
-   * ```
-   */
-  transform?: Record<string, BaggageTransform>;
-}
-
-/**
- * Events configuration for trace context and enrichment
- */
-export interface EventsConfig {
-  /**
-   * Include trace context in events (default: false)
-   *
-   * When enabled, events automatically include:
-   * - autotel.trace_id (32 hex chars)
-   * - autotel.span_id (16 hex chars)
-   * - autotel.trace_flags (2 hex chars)
-   * - autotel.trace_state (raw tracestate string, if present)
-   * - autotel.correlation_id (always present, 16 hex chars)
-   *
-   * Subscribers map these to platform-specific names:
-   * - PostHog: $trace_id, $span_id
-   * - Mixpanel: trace_id, span_id
-   */
-  includeTraceContext?: boolean;
-
-  /**
-   * Include full array of linked trace IDs for batch/fan-in scenarios (default: false)
-   *
-   * When false (default), batch/fan-in events include:
-   * - autotel.linked_trace_id_count: Number of linked parents
-   * - autotel.linked_trace_id_hash: Stable hash of sorted IDs (keeps payload lean)
-   *
-   * When true, events also include:
-   * - autotel.linked_trace_ids: Full array of linked trace IDs
-   */
-  includeLinkedTraceIds?: boolean;
-
-  /**
-   * Generate clickable trace URL from context
-   *
-   * @param ctx - Trace context with traceId, spanId, correlationId, serviceName, environment
-   * @returns URL string or undefined to skip
-   *
-   * @example Grafana Tempo
-   * ```typescript
-   * traceUrl: (ctx) => ctx.traceId
-   *   ? `https://grafana.internal/explore?traceId=${ctx.traceId}`
-   *   : undefined
-   * ```
-   *
-   * @example Datadog
-   * ```typescript
-   * traceUrl: (ctx) => ctx.traceId
-   *   ? `https://app.datadoghq.com/apm/traces?traceId=${ctx.traceId}`
-   *   : undefined
-   * ```
-   *
-   * @example Jaeger
-   * ```typescript
-   * traceUrl: (ctx) => ctx.traceId
-   *   ? `https://jaeger.internal/trace/${ctx.traceId}`
-   *   : undefined
-   * ```
-   */
-  traceUrl?: (ctx: TraceUrlContext) => string | undefined;
-
-  /**
-   * Auto-enrich events from baggage with guardrails
-   *
-   * Automatically includes baggage entries in events without manual code.
-   * Apply allow/deny lists and per-key transforms for PII protection.
-   *
-   * @example Basic allowlist
-   * ```typescript
-   * enrichFromBaggage: {
-   *   allow: ['tenant.id', 'user.id', 'request.id']
-   * }
-   * // Events include: tenant.id, user.id, request.id from baggage
-   * ```
-   *
-   * @example With prefix and transforms
-   * ```typescript
-   * enrichFromBaggage: {
-   *   allow: ['tenant.id', 'user.id', 'user.email'],
-   *   deny: ['user.ssn'],
-   *   prefix: 'ctx.',
-   *   transform: {
-   *     'user.id': 'hash',
-   *     'user.email': 'hash'
-   *   }
-   * }
-   * // Events include: ctx.tenant.id, ctx.user.id (hashed), ctx.user.email (hashed)
-   * ```
-   */
-  enrichFromBaggage?: EnrichFromBaggageConfig;
-}
-
-/**
- * Autotel context object attached to event envelopes
- *
- * This structured object is attached to events and subscribers
- * decide how to map/flatten for their platform.
- */
-export interface AutotelEventContext {
-  /** Trace ID (32 hex chars) - present when inside a trace */
-  trace_id?: string;
-  /** Span ID (16 hex chars) - present when inside a span */
-  span_id?: string;
-  /** Trace flags (2 hex chars, e.g., '01' for sampled) */
-  trace_flags?: string;
-  /** Raw tracestate string - present if tracestate exists */
-  trace_state?: string;
-  /** Clickable trace URL - present if traceUrl config is set */
-  trace_url?: string;
-  /** Correlation ID (always present, 16 hex chars) */
-  correlation_id: string;
-  /** Number of linked parent traces (batch/fan-in scenarios) */
-  linked_trace_id_count?: number;
-  /** Stable hash of linked trace IDs (default for batch/fan-in) */
-  linked_trace_id_hash?: string;
-  /** Full array of linked trace IDs (only if includeLinkedTraceIds: true) */
-  linked_trace_ids?: string[];
-}
-
-/**
- * Hash a string value for PII protection
- *
- * Uses a simple, fast hash function suitable for correlation.
- * NOT cryptographically secure - use for PII masking, not security.
- */
-export function hashValue(value: string): string {
-  let hash = 0;
-  for (let i = 0; i < value.length; i++) {
-    const char = value.charCodeAt(i);
-    hash = (hash << 5) - hash + char;
-    hash = hash & hash; // Convert to 32-bit integer
-  }
-  // Convert to positive hex string
-  return (hash >>> 0).toString(16).padStart(8, '0');
-}
-
-/**
- * Create a stable hash of an array of trace IDs
- *
- * Sorts the array first to ensure deterministic output regardless of order.
- */
-export function hashLinkedTraceIds(traceIds: string[]): string {
-  const sorted = [...traceIds].sort();
-  return hashValue(sorted.join(','));
-}

package/src/exporters.ts

@@ -1,165 +0,0 @@
-/**
- * OpenTelemetry Exporters
- *
- * Re-exports commonly-needed OpenTelemetry exporters for development and debugging.
- *
- * These exporters are already included in autotel's dependencies, so re-exporting
- * them provides a "one install is all you need" developer experience without any
- * bundle size impact.
- *
- * Use these for:
- * - Development debugging (see spans in console)
- * - Progressive development (verify instrumentation works)
- * - Example applications (demonstrate tracing)
- * - Testing (capture spans for assertions)
- *
- * @example Pretty console debugging (recommended)
- * ```typescript
- * import { init } from 'autotel'
- *
- * init({
- *   service: 'my-app',
- *   debug: 'pretty',  // Colorized, hierarchical output
- * })
- * ```
- *
- * @example Pretty exporter with custom options
- * ```typescript
- * import { init } from 'autotel'
- * import { PrettyConsoleExporter } from 'autotel/exporters'
- *
- * init({
- *   service: 'my-app',
- *   spanExporters: [new PrettyConsoleExporter({
- *     colors: true,
- *     showAttributes: true,
- *     hideAttributes: ['http.user_agent'],
- *   })],
- * })
- * ```
- *
- * @example Raw console debugging
- * ```typescript
- * import { init } from 'autotel'
- * import { ConsoleSpanExporter } from 'autotel/exporters'
- *
- * init({
- *   service: 'my-app',
- *   spanExporters: [new ConsoleSpanExporter()],
- * })
- * ```
- *
- * @example In-memory testing
- * ```typescript
- * import { init } from 'autotel'
- * import { InMemorySpanExporter } from 'autotel/exporters'
- * import { SimpleSpanProcessor } from 'autotel/processors'
- *
- * const exporter = new InMemorySpanExporter()
- * init({
- *   service: 'test',
- *   spanProcessor: new SimpleSpanProcessor(exporter),
- * })
- *
- * // Run code under test
- * await myFunction()
- *
- * // Assert on collected spans
- * const spans = exporter.getFinishedSpans()
- * expect(spans).toHaveLength(1)
- * ```
- *
- * Note: For high-level testing utilities with assertion helpers, see `autotel/testing`.
- * For custom span processing, see `autotel/processors`.
- *
- * @module autotel/exporters
- * @see {@link https://opentelemetry.io/docs/specs/otel/trace/sdk/#span-exporter | OTel Span Exporter Spec}
- */
-
-export {
-  /**
-   * Console exporter - prints raw JSON spans to stdout.
-   *
-   * Perfect for:
-   * - Verbose debugging (see all span details)
-   * - Example applications (demonstrate tracing)
-   * - Quick debugging (no backend setup required)
-   *
-   * Note: For better DX, use `debug: 'pretty'` or `PrettyConsoleExporter` instead.
-   *
-   * @example
-   * ```typescript
-   * import { ConsoleSpanExporter } from 'autotel/exporters'
-   *
-   * const exporter = new ConsoleSpanExporter()
-   * ```
-   */
-  ConsoleSpanExporter,
-
-  /**
-   * In-memory exporter - stores spans in memory.
-   *
-   * Perfect for:
-   * - Unit testing (capture and assert on spans)
-   * - Integration testing (verify trace structure)
-   * - Development (inspect spans programmatically)
-   *
-   * Note: Memory will grow unbounded - clear spans periodically or use for testing only.
-   *
-   * @example
-   * ```typescript
-   * import { InMemorySpanExporter } from 'autotel/exporters'
-   *
-   * const exporter = new InMemorySpanExporter()
-   * // ... run code
-   * const spans = exporter.getFinishedSpans()
-   * exporter.reset() // Clear memory
-   * ```
-   */
-  InMemorySpanExporter,
-} from '@opentelemetry/sdk-trace-base';
-
-/**
- * Pretty console exporter - colorized, hierarchical span output.
- *
- * Perfect for:
- * - Local development (beautiful, readable output)
- * - Debugging (see trace hierarchy at a glance)
- * - Progressive development (verify spans look correct)
- *
- * Features:
- * - Colorized status (✓ green, ✗ red)
- * - Duration color coding (fast=green, medium=yellow, slow=red)
- * - Hierarchical tree view showing parent-child relationships
- * - Attribute display with truncation
- * - Error message highlighting
- *
- * Note: Not recommended for production use.
- *
- * @example Basic usage
- * ```typescript
- * import { init } from 'autotel'
- *
- * init({
- *   service: 'my-app',
- *   debug: 'pretty',  // Uses PrettyConsoleExporter
- * })
- * ```
- *
- * @example With custom options
- * ```typescript
- * import { PrettyConsoleExporter } from 'autotel/exporters'
- *
- * const exporter = new PrettyConsoleExporter({
- *   colors: true,           // Auto-detect TTY by default
- *   showAttributes: true,   // Show span attributes
- *   maxValueLength: 50,     // Truncate long values
- *   hideAttributes: ['http.user_agent'],  // Hide specific attributes
- *   showTraceId: false,     // Show trace ID header
- * })
- * ```
- */
-export {
-  PrettyConsoleExporter,
-  type PrettyConsoleExporterOptions,
-} from './pretty-console-exporter';

package/src/filtering-span-processor.test.ts

@@ -1,281 +0,0 @@
-/**
- * Tests for FilteringSpanProcessor
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-import {
-  FilteringSpanProcessor,
-  type SpanFilterPredicate,
-} from './filtering-span-processor';
-import type {
-  SpanProcessor,
-  ReadableSpan,
-} from '@opentelemetry/sdk-trace-base';
-import type { Context } from '@opentelemetry/api';
-import type { Span } from '@opentelemetry/sdk-trace-base';
-
-/**
- * Mock span processor to capture forwarded spans
- */
-class MockSpanProcessor implements SpanProcessor {
-  public startedSpans: Span[] = [];
-  public endedSpans: ReadableSpan[] = [];
-  public flushed = false;
-  public shutdownCalled = false;
-
-  onStart(span: Span): void {
-    this.startedSpans.push(span);
-  }
-
-  onEnd(span: ReadableSpan): void {
-    this.endedSpans.push(span);
-  }
-
-  async forceFlush(): Promise<void> {
-    this.flushed = true;
-  }
-
-  async shutdown(): Promise<void> {
-    this.shutdownCalled = true;
-  }
-
-  reset(): void {
-    this.startedSpans = [];
-    this.endedSpans = [];
-    this.flushed = false;
-    this.shutdownCalled = false;
-  }
-}
-
-/**
- * Create a mock ReadableSpan for testing
- */
-function createMockSpan(
-  name: string,
-  instrumentationScopeName = 'test-scope',
-  attributes: Record<string, unknown> = {},
-): ReadableSpan {
-  return {
-    name,
-    attributes,
-    instrumentationScope: {
-      name: instrumentationScopeName,
-      version: '1.0.0',
-    },
-    spanContext: () => ({
-      traceId: 'trace123',
-      spanId: 'span123',
-      traceFlags: 1,
-    }),
-    duration: [0, 1_000_000], // 1ms
-    status: { code: 0 },
-    kind: 0,
-    startTime: [0, 0],
-    endTime: [0, 1_000_000],
-    ended: true,
-    resource: {
-      attributes: {},
-      merge: () => ({}) as never,
-    },
-    droppedAttributesCount: 0,
-    droppedEventsCount: 0,
-    droppedLinksCount: 0,
-    events: [],
-    links: [],
-    parentSpanId: undefined,
-  } as unknown as ReadableSpan;
-}
-
-describe('FilteringSpanProcessor', () => {
-  let mockProcessor: MockSpanProcessor;
-
-  beforeEach(() => {
-    mockProcessor = new MockSpanProcessor();
-  });
-
-  describe('basic filtering', () => {
-    it('should forward spans that pass the filter', () => {
-      const filter: SpanFilterPredicate = (span) => span.name !== 'drop-me';
-      const filteringProcessor = new FilteringSpanProcessor(mockProcessor, {
-        filter,
-      });
-
-      const keepSpan = createMockSpan('keep-me');
-      filteringProcessor.onEnd(keepSpan);
-
-      expect(mockProcessor.endedSpans).toHaveLength(1);
-      expect(mockProcessor.endedSpans[0]).toBe(keepSpan);
-    });
-
-    it('should drop spans that fail the filter', () => {
-      const filter: SpanFilterPredicate = (span) => span.name !== 'drop-me';
-      const filteringProcessor = new FilteringSpanProcessor(mockProcessor, {
-        filter,
-      });
-
-      const dropSpan = createMockSpan('drop-me');
-      filteringProcessor.onEnd(dropSpan);
-
-      expect(mockProcessor.endedSpans).toHaveLength(0);
-    });
-
-    it('should always forward onStart (no filtering)', () => {
-      const filter: SpanFilterPredicate = () => false; // Drop everything
-      const filteringProcessor = new FilteringSpanProcessor(mockProcessor, {
-        filter,
-      });
-
-      const mockSpan = {} as Span;
-      const mockContext = {} as Context;
-      filteringProcessor.onStart(mockSpan, mockContext);
-
-      expect(mockProcessor.startedSpans).toHaveLength(1);
-      expect(mockProcessor.startedSpans[0]).toBe(mockSpan);
-    });
-  });
-
-  describe('instrumentation scope filtering (primary use case)', () => {
-    it('should filter out spans by instrumentation scope name', () => {
-      const filter: SpanFilterPredicate = (span) =>
-        span.instrumentationScope.name !== 'next.js';
-      const filteringProcessor = new FilteringSpanProcessor(mockProcessor, {
-        filter,
-      });
-
-      const nextSpan = createMockSpan('GET /api/users', 'next.js');
-      const autotelSpan = createMockSpan('createUser', 'autotel');
-
-      filteringProcessor.onEnd(nextSpan);
-      filteringProcessor.onEnd(autotelSpan);
-
-      expect(mockProcessor.endedSpans).toHaveLength(1);
-      expect(mockProcessor.endedSpans[0].instrumentationScope.name).toBe(
-        'autotel',
-      );
-    });
-
-    it('should support multiple instrumentation scope exclusions', () => {
-      const excludedScopes = new Set([
-        'next.js',
-        '@opentelemetry/instrumentation-http',
-      ]);
-      const filter: SpanFilterPredicate = (span) =>
-        !excludedScopes.has(span.instrumentationScope.name);
-      const filteringProcessor = new FilteringSpanProcessor(mockProcessor, {
-        filter,
-      });
-
-      filteringProcessor.onEnd(createMockSpan('span1', 'next.js'));
-      filteringProcessor.onEnd(
-        createMockSpan('span2', '@opentelemetry/instrumentation-http'),
-      );
-      filteringProcessor.onEnd(createMockSpan('span3', 'autotel'));
-
-      expect(mockProcessor.endedSpans).toHaveLength(1);
-      expect(mockProcessor.endedSpans[0].name).toBe('span3');
-    });
-  });
-
-  describe('error handling', () => {
-    it('should forward span if filter throws (fail-open)', () => {
-      const filter: SpanFilterPredicate = () => {
-        throw new Error('Filter error');
-      };
-      const filteringProcessor = new FilteringSpanProcessor(mockProcessor, {
-        filter,
-      });
-
-      const span = createMockSpan('test-span');
-      filteringProcessor.onEnd(span);
-
-      // Span should be forwarded despite filter error
-      expect(mockProcessor.endedSpans).toHaveLength(1);
-    });
-  });
-
-  describe('lifecycle methods', () => {
-    it('should forward forceFlush to wrapped processor', async () => {
-      const filter: SpanFilterPredicate = () => true;
-      const filteringProcessor = new FilteringSpanProcessor(mockProcessor, {
-        filter,
-      });
-
-      await filteringProcessor.forceFlush();
-
-      expect(mockProcessor.flushed).toBe(true);
-    });
-
-    it('should forward shutdown to wrapped processor', async () => {
-      const filter: SpanFilterPredicate = () => true;
-      const filteringProcessor = new FilteringSpanProcessor(mockProcessor, {
-        filter,
-      });
-
-      await filteringProcessor.shutdown();
-
-      expect(mockProcessor.shutdownCalled).toBe(true);
-    });
-  });
-
-  describe('complex filtering scenarios', () => {
-    it('should support attribute-based filtering', () => {
-      const filter: SpanFilterPredicate = (span) =>
-        span.attributes['http.route'] !== '/health';
-      const filteringProcessor = new FilteringSpanProcessor(mockProcessor, {
-        filter,
-      });
-
-      filteringProcessor.onEnd(
-        createMockSpan('GET /health', 'http', { 'http.route': '/health' }),
-      );
-      filteringProcessor.onEnd(
-        createMockSpan('GET /api/users', 'http', {
-          'http.route': '/api/users',
-        }),
-      );
-
-      expect(mockProcessor.endedSpans).toHaveLength(1);
-      expect(mockProcessor.endedSpans[0].name).toBe('GET /api/users');
-    });
-
-    it('should support span name pattern matching', () => {
-      const filter: SpanFilterPredicate = (span) =>
-        !span.name.startsWith('internal:');
-      const filteringProcessor = new FilteringSpanProcessor(mockProcessor, {
-        filter,
-      });
-
-      filteringProcessor.onEnd(createMockSpan('internal:bootstrap'));
-      filteringProcessor.onEnd(createMockSpan('internal:middleware'));
-      filteringProcessor.onEnd(createMockSpan('createUser'));
-
-      expect(mockProcessor.endedSpans).toHaveLength(1);
-      expect(mockProcessor.endedSpans[0].name).toBe('createUser');
-    });
-
-    it('should support combining multiple filter conditions', () => {
-      const filter: SpanFilterPredicate = (span) => {
-        // Drop Next.js spans
-        if (span.instrumentationScope.name === 'next.js') return false;
-        // Drop health check spans
-        if (span.name.includes('/health')) return false;
-        // Keep everything else
-        return true;
-      };
-      const filteringProcessor = new FilteringSpanProcessor(mockProcessor, {
-        filter,
-      });
-
-      filteringProcessor.onEnd(createMockSpan('GET /api/users', 'next.js'));
-      filteringProcessor.onEnd(createMockSpan('GET /health', 'http'));
-      filteringProcessor.onEnd(createMockSpan('createUser', 'autotel'));
-      filteringProcessor.onEnd(createMockSpan('GET /api/orders', 'http'));
-
-      expect(mockProcessor.endedSpans).toHaveLength(2);
-      expect(mockProcessor.endedSpans.map((s) => s.name)).toEqual([
-        'createUser',
-        'GET /api/orders',
-      ]);
-    });
-  });
-});