autotel 4.1.0 → 4.2.0

package/src/span-name-normalizer.test.ts

@@ -1,377 +0,0 @@
-/**
- * Tests for SpanNameNormalizingProcessor
- */
-
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import {
-  SpanNameNormalizingProcessor,
-  NORMALIZER_PATTERNS,
-  NORMALIZER_PRESETS,
-  type SpanNameNormalizerFn,
-} from './span-name-normalizer';
-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;
-  }
-}
-
-/**
- * Create a mock Span with updateName capability
- */
-function createMockSpan(initialName: string): Span {
-  const span = {
-    _name: initialName,
-    updateName: vi.fn(function (this: { _name: string }, newName: string) {
-      this._name = newName;
-    }),
-    spanContext: () => ({
-      traceId: 'trace123',
-      spanId: 'span123',
-      traceFlags: 1,
-    }),
-  };
-
-  // Define name as a getter to return current _name
-  Object.defineProperty(span, 'name', {
-    get() {
-      return span._name;
-    },
-    enumerable: true,
-  });
-
-  return span as unknown as Span;
-}
-
-describe('SpanNameNormalizingProcessor', () => {
-  let mockProcessor: MockSpanProcessor;
-
-  beforeEach(() => {
-    mockProcessor = new MockSpanProcessor();
-  });
-
-  describe('custom normalizer function', () => {
-    it('should normalize span names using custom function', () => {
-      const normalizer: SpanNameNormalizerFn = (name) =>
-        name.replaceAll(/\/[0-9]+/g, '/:id');
-      const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-        normalizer,
-      });
-
-      const span = createMockSpan('GET /users/123/posts/456');
-      processor.onStart(span, {} as Context);
-
-      expect(span.updateName).toHaveBeenCalledWith('GET /users/:id/posts/:id');
-    });
-
-    it('should not call updateName if name unchanged', () => {
-      const normalizer: SpanNameNormalizerFn = (name) => name; // No change
-      const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-        normalizer,
-      });
-
-      const span = createMockSpan('createUser');
-      processor.onStart(span, {} as Context);
-
-      expect(span.updateName).not.toHaveBeenCalled();
-    });
-
-    it('should forward span to wrapped processor', () => {
-      const normalizer: SpanNameNormalizerFn = (name) => name;
-      const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-        normalizer,
-      });
-
-      const span = createMockSpan('test');
-      const context = {} as Context;
-      processor.onStart(span, context);
-
-      expect(mockProcessor.startedSpans).toHaveLength(1);
-    });
-  });
-
-  describe('built-in presets', () => {
-    describe('rest-api preset', () => {
-      it('should normalize numeric IDs', () => {
-        const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-          normalizer: 'rest-api',
-        });
-
-        const span = createMockSpan('GET /users/123');
-        processor.onStart(span, {} as Context);
-
-        expect(span.updateName).toHaveBeenCalledWith('GET /users/:id');
-      });
-
-      it('should normalize UUIDs', () => {
-        const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-          normalizer: 'rest-api',
-        });
-
-        const span = createMockSpan(
-          'GET /items/550e8400-e29b-41d4-a716-446655440000',
-        );
-        processor.onStart(span, {} as Context);
-
-        expect(span.updateName).toHaveBeenCalledWith('GET /items/:uuid');
-      });
-
-      it('should normalize MongoDB ObjectIds', () => {
-        const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-          normalizer: 'rest-api',
-        });
-
-        const span = createMockSpan('GET /docs/507f1f77bcf86cd799439011');
-        processor.onStart(span, {} as Context);
-
-        expect(span.updateName).toHaveBeenCalledWith('GET /docs/:objectId');
-      });
-
-      it('should normalize ISO dates', () => {
-        const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-          normalizer: 'rest-api',
-        });
-
-        const span = createMockSpan('GET /logs/2024-01-15');
-        processor.onStart(span, {} as Context);
-
-        expect(span.updateName).toHaveBeenCalledWith('GET /logs/:date');
-      });
-
-      it('should normalize timestamps', () => {
-        const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-          normalizer: 'rest-api',
-        });
-
-        const span = createMockSpan('GET /events/1705334400');
-        processor.onStart(span, {} as Context);
-
-        expect(span.updateName).toHaveBeenCalledWith('GET /events/:timestamp');
-      });
-
-      it('should normalize emails', () => {
-        const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-          normalizer: 'rest-api',
-        });
-
-        const span = createMockSpan('GET /users/john@example.com');
-        processor.onStart(span, {} as Context);
-
-        expect(span.updateName).toHaveBeenCalledWith('GET /users/:email');
-      });
-
-      it('should handle multiple dynamic segments', () => {
-        const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-          normalizer: 'rest-api',
-        });
-
-        const span = createMockSpan('GET /users/123/posts/456/comments/789');
-        processor.onStart(span, {} as Context);
-
-        expect(span.updateName).toHaveBeenCalledWith(
-          'GET /users/:id/posts/:id/comments/:id',
-        );
-      });
-    });
-
-    describe('minimal preset', () => {
-      it('should only normalize numeric IDs and UUIDs', () => {
-        const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-          normalizer: 'minimal',
-        });
-
-        const span = createMockSpan('GET /users/123');
-        processor.onStart(span, {} as Context);
-
-        expect(span.updateName).toHaveBeenCalledWith('GET /users/:id');
-      });
-
-      it('should not normalize ObjectIds (only rest-api does)', () => {
-        const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-          normalizer: 'minimal',
-        });
-
-        // ObjectId is 24 hex chars - minimal doesn't handle this
-        const span = createMockSpan('GET /docs/507f1f77bcf86cd799439011');
-        processor.onStart(span, {} as Context);
-
-        // Minimal only does numeric IDs and UUIDs, not ObjectIds
-        expect(span.updateName).not.toHaveBeenCalled();
-      });
-    });
-
-    describe('graphql preset', () => {
-      it('should normalize UUIDs in paths', () => {
-        const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-          normalizer: 'graphql',
-        });
-
-        const span = createMockSpan(
-          'POST /graphql/550e8400-e29b-41d4-a716-446655440000',
-        );
-        processor.onStart(span, {} as Context);
-
-        expect(span.updateName).toHaveBeenCalledWith('POST /graphql/:uuid');
-      });
-
-      it('should normalize path-style IDs in GraphQL endpoints', () => {
-        const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-          normalizer: 'graphql',
-        });
-
-        const span = createMockSpan('POST /graphql/users/123');
-        processor.onStart(span, {} as Context);
-
-        expect(span.updateName).toHaveBeenCalledWith('POST /graphql/users/:id');
-      });
-
-      it('should not modify pure operation names without IDs', () => {
-        const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-          normalizer: 'graphql',
-        });
-
-        const span = createMockSpan('query GetUserById');
-        processor.onStart(span, {} as Context);
-
-        // No change expected since there are no path segments to normalize
-        expect(span.updateName).not.toHaveBeenCalled();
-      });
-    });
-  });
-
-  describe('error handling', () => {
-    it('should keep original name if normalizer throws (fail-open)', () => {
-      const normalizer: SpanNameNormalizerFn = () => {
-        throw new Error('Normalizer error');
-      };
-      const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-        normalizer,
-      });
-
-      const span = createMockSpan('GET /users/123');
-      processor.onStart(span, {} as Context);
-
-      // Should not throw and should not call updateName
-      expect(span.updateName).not.toHaveBeenCalled();
-      expect(mockProcessor.startedSpans).toHaveLength(1);
-    });
-
-    it('should throw for unknown preset', () => {
-      expect(() => {
-        new SpanNameNormalizingProcessor(mockProcessor, {
-          normalizer: 'unknown-preset' as 'rest-api',
-        });
-      }).toThrow('Unknown span name normalizer preset');
-    });
-  });
-
-  describe('lifecycle methods', () => {
-    it('should forward onEnd to wrapped processor', () => {
-      const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-        normalizer: 'rest-api',
-      });
-
-      const span = { name: 'test' } as ReadableSpan;
-      processor.onEnd(span);
-
-      expect(mockProcessor.endedSpans).toHaveLength(1);
-    });
-
-    it('should forward forceFlush to wrapped processor', async () => {
-      const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-        normalizer: 'rest-api',
-      });
-
-      await processor.forceFlush();
-
-      expect(mockProcessor.flushed).toBe(true);
-    });
-
-    it('should forward shutdown to wrapped processor', async () => {
-      const processor = new SpanNameNormalizingProcessor(mockProcessor, {
-        normalizer: 'rest-api',
-      });
-
-      await processor.shutdown();
-
-      expect(mockProcessor.shutdownCalled).toBe(true);
-    });
-  });
-});
-
-describe('NORMALIZER_PATTERNS', () => {
-  it('should export regex patterns for advanced users', () => {
-    expect(NORMALIZER_PATTERNS.numericId).toBeInstanceOf(RegExp);
-    expect(NORMALIZER_PATTERNS.uuid).toBeInstanceOf(RegExp);
-    expect(NORMALIZER_PATTERNS.objectId).toBeInstanceOf(RegExp);
-    expect(NORMALIZER_PATTERNS.isoDate).toBeInstanceOf(RegExp);
-    expect(NORMALIZER_PATTERNS.timestamp).toBeInstanceOf(RegExp);
-    expect(NORMALIZER_PATTERNS.email).toBeInstanceOf(RegExp);
-  });
-
-  describe('pattern matching', () => {
-    it('numericId should match numeric path segments', () => {
-      expect('/users/123'.replace(NORMALIZER_PATTERNS.numericId, '/:id')).toBe(
-        '/users/:id',
-      );
-      expect(
-        '/users/123/posts'.replace(NORMALIZER_PATTERNS.numericId, '/:id'),
-      ).toBe('/users/:id/posts');
-    });
-
-    it('uuid should match standard UUIDs', () => {
-      const uuid = '550e8400-e29b-41d4-a716-446655440000';
-      expect(`/items/${uuid}`.replace(NORMALIZER_PATTERNS.uuid, '/:uuid')).toBe(
-        '/items/:uuid',
-      );
-    });
-
-    it('objectId should match MongoDB ObjectIds', () => {
-      expect(
-        '/docs/507f1f77bcf86cd799439011'.replace(
-          NORMALIZER_PATTERNS.objectId,
-          '/:objectId',
-        ),
-      ).toBe('/docs/:objectId');
-    });
-  });
-});
-
-describe('NORMALIZER_PRESETS', () => {
-  it('should export preset functions for advanced users', () => {
-    expect(typeof NORMALIZER_PRESETS['rest-api']).toBe('function');
-    expect(typeof NORMALIZER_PRESETS['graphql']).toBe('function');
-    expect(typeof NORMALIZER_PRESETS['minimal']).toBe('function');
-  });
-
-  it('presets should be usable directly', () => {
-    const result = NORMALIZER_PRESETS['rest-api']('GET /users/123/posts/456');
-    expect(result).toBe('GET /users/:id/posts/:id');
-  });
-});

package/src/span-name-normalizer.ts

@@ -1,213 +0,0 @@
-/**
- * Span Name Normalizer
- *
- * Normalizes span names to reduce cardinality from dynamic path segments.
- * This is critical for observability backends that charge by unique span names
- * or have cardinality limits.
- *
- * @example Basic usage with custom function
- * ```typescript
- * init({
- *   service: 'my-app',
- *   spanNameNormalizer: (name) => {
- *     return name.replace(/\/[0-9]+/g, '/:id');
- *   }
- * })
- * ```
- *
- * @example Using built-in preset
- * ```typescript
- * init({
- *   service: 'my-app',
- *   spanNameNormalizer: 'rest-api'
- * })
- * ```
- */
-
-import type {
-  SpanProcessor,
-  ReadableSpan,
-} from '@opentelemetry/sdk-trace-base';
-import type { Context } from '@opentelemetry/api';
-import type { Span } from '@opentelemetry/sdk-trace-base';
-
-/**
- * Function to normalize a span name
- * @param name - The original span name
- * @returns The normalized span name
- */
-export type SpanNameNormalizerFn = (name: string) => string;
-
-/**
- * Built-in normalizer preset names
- */
-export type SpanNameNormalizerPreset = 'rest-api' | 'graphql' | 'minimal';
-
-/**
- * Normalizer config - either a function or a preset name
- */
-export type SpanNameNormalizerConfig =
-  | SpanNameNormalizerFn
-  | SpanNameNormalizerPreset;
-
-export interface SpanNameNormalizingProcessorOptions {
-  /**
-   * Normalizer function or preset name
-   */
-  normalizer: SpanNameNormalizerConfig;
-}
-
-/**
- * Built-in normalizer patterns
- */
-const NORMALIZER_PATTERNS = {
-  // Numeric IDs: /users/123 → /users/:id
-  numericId: /\/\d+(?=\/|$)/g,
-
-  // UUIDs: /users/550e8400-e29b-41d4-a716-446655440000 → /users/:uuid
-  uuid: /\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?=\/|$)/gi,
-
-  // Short UUIDs (without dashes): /users/550e8400e29b41d4a716446655440000 → /users/:uuid
-  shortUuid: /\/[0-9a-f]{32}(?=\/|$)/gi,
-
-  // MongoDB ObjectIds: /docs/507f1f77bcf86cd799439011 → /docs/:objectId
-  objectId: /\/[0-9a-f]{24}(?=\/|$)/gi,
-
-  // Hashes (6+ hex chars): /assets/abc123def.js → /assets/:hash.js
-  hash: /\/[0-9a-f]{6,}(?=\.[a-z]+$)/gi,
-
-  // ISO dates: /logs/2024-01-15 → /logs/:date
-  isoDate: /\/\d{4}-\d{2}-\d{2}(?=\/|$)/g,
-
-  // Timestamps: /events/1705334400 → /events/:timestamp
-  timestamp: /\/1[0-9]{9}(?=\/|$)/g,
-
-  // Email-like segments: /users/john@example.com → /users/:email
-  email: /\/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}(?=\/|$)/g,
-} as const;
-
-/**
- * Built-in normalizer presets
- */
-const NORMALIZER_PRESETS: Record<
-  SpanNameNormalizerPreset,
-  SpanNameNormalizerFn
-> = {
-  /**
-   * REST API preset - normalizes common REST path patterns
-   * Handles: numeric IDs, UUIDs, ObjectIds, dates, timestamps, emails
-   */
-  'rest-api': (name: string): string => {
-    return name
-      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')
-      .replaceAll(NORMALIZER_PATTERNS.shortUuid, '/:uuid')
-      .replaceAll(NORMALIZER_PATTERNS.objectId, '/:objectId')
-      .replaceAll(NORMALIZER_PATTERNS.isoDate, '/:date')
-      .replaceAll(NORMALIZER_PATTERNS.timestamp, '/:timestamp')
-      .replaceAll(NORMALIZER_PATTERNS.email, '/:email')
-      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');
-  },
-
-  /**
-   * GraphQL preset - normalizes GraphQL operation names and paths
-   * Keeps query/mutation names but normalizes embedded IDs
-   */
-  graphql: (name: string): string => {
-    // For GraphQL, normalize both path-style and embedded IDs
-    return name
-      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')
-      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');
-  },
-
-  /**
-   * Minimal preset - only normalizes numeric IDs and UUIDs
-   */
-  minimal: (name: string): string => {
-    return name
-      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')
-      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');
-  },
-};
-
-/**
- * Resolve normalizer config to a function
- */
-function resolveNormalizer(
-  config: SpanNameNormalizerConfig,
-): SpanNameNormalizerFn {
-  if (typeof config === 'function') {
-    return config;
-  }
-
-  const preset = NORMALIZER_PRESETS[config];
-  if (!preset) {
-    throw new Error(
-      `Unknown span name normalizer preset: "${config}". ` +
-        `Available presets: ${Object.keys(NORMALIZER_PRESETS).join(', ')}`,
-    );
-  }
-
-  return preset;
-}
-
-/**
- * Span processor that normalizes span names to reduce cardinality.
- *
- * Normalization happens in onStart() when we have access to the mutable Span.
- * This allows us to call span.updateName() before the span is finalized.
- *
- * Common use cases:
- * - REST APIs: /users/123/posts/456 → /users/:id/posts/:id
- * - UUIDs: /items/550e8400-e29b-41d4-a716-446655440000 → /items/:uuid
- * - Dates: /logs/2024-01-15 → /logs/:date
- */
-export class SpanNameNormalizingProcessor implements SpanProcessor {
-  private readonly wrappedProcessor: SpanProcessor;
-  private readonly normalizer: SpanNameNormalizerFn;
-
-  constructor(
-    wrappedProcessor: SpanProcessor,
-    options: SpanNameNormalizingProcessorOptions,
-  ) {
-    this.wrappedProcessor = wrappedProcessor;
-    this.normalizer = resolveNormalizer(options.normalizer);
-  }
-
-  /**
-   * Normalize span name on start (when Span is mutable)
-   */
-  onStart(span: Span, parentContext: Context): void {
-    try {
-      const originalName = span.name;
-      const normalizedName = this.normalizer(originalName);
-
-      if (normalizedName !== originalName) {
-        span.updateName(normalizedName);
-      }
-    } catch {
-      // If normalizer throws, keep original name (fail-open)
-    }
-
-    this.wrappedProcessor.onStart(span, parentContext);
-  }
-
-  /**
-   * Pass through onEnd unchanged
-   */
-  onEnd(span: ReadableSpan): void {
-    this.wrappedProcessor.onEnd(span);
-  }
-
-  forceFlush(): Promise<void> {
-    return this.wrappedProcessor.forceFlush();
-  }
-
-  shutdown(): Promise<void> {
-    return this.wrappedProcessor.shutdown();
-  }
-}
-
-/**
- * Export built-in patterns for advanced users who want to compose their own normalizers
- */
-export { NORMALIZER_PATTERNS, NORMALIZER_PRESETS };

package/src/stable-hash.ts

@@ -1,27 +0,0 @@
-import { createHash } from 'node:crypto';
-
-/**
- * Deterministic JSON stringify with sorted object keys, so two structurally
- * equal values always produce the same string regardless of key insertion
- * order. Shared by `defineEvent` and the validation layer for stable schema
- * hashes.
- */
-export function stableStringify(value: unknown): string {
-  if (value === null || value === undefined || typeof value !== 'object') {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return '[' + value.map((v) => stableStringify(v)).join(',') + ']';
-  }
-  const obj = value as Record<string, unknown>;
-  const body = Object.keys(obj)
-    .toSorted()
-    .map((k) => JSON.stringify(k) + ':' + stableStringify(obj[k]))
-    .join(',');
-  return '{' + body + '}';
-}
-
-/** Stable sha256 of any JSON-serializable value. */
-export function hashJson(value: unknown): string {
-  return createHash('sha256').update(stableStringify(value)).digest('hex');
-}