autotel 4.1.0 → 4.2.0

package/src/attributes/utils.ts

@@ -1,64 +0,0 @@
-/**
- * Attribute utility functions
- */
-
-import type { AttributeValue } from '../trace-context';
-import {
-  validateAttribute,
-  autoRedactPII,
-  defaultGuardrails,
-  checkDeprecatedAttribute,
-  type AttributePolicy,
-} from './validators';
-
-// Type for objects that have setAttributes method (spans or contexts)
-// Using a generic parameter to accommodate different AttributeValue types
-type AttributeSetter = {
-  setAttributes: (attrs: Record<string, AttributeValue>) => void;
-};
-
-export function mergeAttrs(
-  ...attrSets: Array<Record<string, unknown> | undefined>
-): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-  for (const attrSet of attrSets) {
-    if (attrSet) {
-      Object.assign(result, attrSet);
-    }
-  }
-  return result;
-}
-
-export function safeSetAttributes(
-  span: AttributeSetter,
-  attrs: Record<string, unknown>,
-  policy?: AttributePolicy,
-): void {
-  // Merge user-supplied guardrails with defaults so callers can tweak
-  // a single option without opting out of the rest
-  const mergedGuardrails = {
-    ...defaultGuardrails(),
-    ...policy?.guardrails,
-  };
-  const effectivePolicy: AttributePolicy = {
-    ...policy,
-    guardrails: mergedGuardrails,
-  };
-
-  const validated = autoRedactPII(attrs, effectivePolicy);
-
-  const sanitizedAttrs: Record<string, AttributeValue> = {};
-  for (const [key, value] of Object.entries(validated)) {
-    if (value !== undefined) {
-      // Check for deprecated attributes and log warnings
-      checkDeprecatedAttribute(key, effectivePolicy);
-      const validatedValue = validateAttribute(key, value, effectivePolicy);
-      if (validatedValue !== undefined) {
-        // Cast to AttributeValue since validateAttribute ensures valid types
-        sanitizedAttrs[key] = validatedValue as AttributeValue;
-      }
-    }
-  }
-
-  span.setAttributes(sanitizedAttrs);
-}

package/src/attributes/validators.ts

@@ -1,266 +0,0 @@
-/**
- * Attribute validation, PII detection, and guardrails
- * Provides safe-by-default attribute handling with configurable policies
- */
-
-import { REDACTOR_PATTERNS } from '../attribute-redacting-processor';
-
-export interface AttributeGuardrails {
-  /** How to handle PII in attributes */
-  pii?: 'allow' | 'redact' | 'hash' | 'block';
-
-  /** Maximum length for attribute values */
-  maxLength?: number;
-
-  /** Validate enum values against known values */
-  validateEnum?: boolean;
-
-  /** Log warnings for deprecated attributes instead of throwing */
-  warnDeprecated?: boolean;
-
-  /** Custom deprecation warnings */
-  deprecatedWarnings?: Record<string, string>;
-}
-
-export interface AttributePolicy {
-  guardrails?: AttributeGuardrails;
-  /** Custom deprecation warnings for specific attributes */
-  deprecatedWarnings?: Record<string, string>;
-}
-
-const DEPRECATED_ATTRIBUTES = {
-  'enduser.id': 'user.id',
-  'enduser.role': 'user.roles',
-  'enduser.scope': undefined,
-  'http.method': 'http.request.method',
-  'http.host': 'server.address',
-  'http.status_code': 'http.response.status_code',
-  'http.target': 'url.path',
-  'http.url': 'url.full',
-  'http.user_agent': 'user_agent.original',
-  'http.flavor': 'network.protocol.name',
-  'http.scheme': 'url.scheme',
-  'http.server_name': 'server.address',
-  'db.name': 'db.namespace',
-  'db.operation': 'db.operation.name',
-  'db.statement': 'db.query.text',
-  'db.system': 'db.system.name',
-  'db.collection': 'db.collection.name',
-  'db.instance.id': undefined,
-  'db.jdbc.driver_classname': undefined,
-  'db.mssql.instance_name': 'mssql.instance.name',
-  'db.sql.table': 'db.collection.name',
-  'http.client_ip': 'client.address',
-  'user_agent.original': 'user_agent.original',
-} as const;
-
-const HTTP_METHODS = new Set([
-  'GET',
-  'POST',
-  'PUT',
-  'DELETE',
-  'PATCH',
-  'HEAD',
-  'OPTIONS',
-  'TRACE',
-  'QUERY',
-  '_OTHER',
-]);
-
-export function validateAttribute(
-  key: string,
-  value: unknown,
-  policy: AttributePolicy = {},
-): unknown {
-  const { guardrails = {} } = policy;
-
-  if (value === undefined || value === null) {
-    return undefined;
-  }
-
-  // For non-string values that don't need transformation, preserve the original type
-  if (typeof value !== 'string') {
-    // PII checks only apply to strings
-    // maxLength only applies to strings
-    // validateEnum only applies to strings
-    return value;
-  }
-
-  const stringValue = value;
-
-  if (guardrails.pii) {
-    const piiResult = applyPIIPolicy(key, stringValue, guardrails.pii);
-    if (piiResult !== stringValue) {
-      return piiResult;
-    }
-  }
-
-  if (guardrails.maxLength && stringValue.length > guardrails.maxLength) {
-    return truncateValue(key, stringValue, guardrails.maxLength);
-  }
-
-  if (guardrails.validateEnum && HTTP_METHODS.has(stringValue)) {
-    const normalizedMethod = normalizeHTTPMethod(stringValue);
-    if (normalizedMethod !== stringValue) {
-      return normalizedMethod;
-    }
-  }
-
-  return stringValue;
-}
-
-function applyPIIPolicy(
-  key: string,
-  value: string,
-  pii: AttributeGuardrails['pii'],
-): string {
-  if (pii === 'allow') {
-    return value;
-  }
-
-  if (pii === 'redact') {
-    return redactIfPII(key, value);
-  }
-
-  if (pii === 'hash') {
-    return hashIfPII(key, value);
-  }
-
-  if (pii === 'block' && isPIIKey(key)) {
-    throw new Error(
-      `PII attribute "${key}" is blocked by guardrails. Use pii: "allow" to enable it.`,
-    );
-  }
-
-  return value;
-}
-
-function isPIIKey(key: string): boolean {
-  const piiKeyPatterns = [
-    'email',
-    'phone',
-    'ssn',
-    'credit_card',
-    'password',
-    'secret',
-    'token',
-    'api_key',
-    'authorization',
-  ];
-  const lowerKey = key.toLowerCase();
-  return piiKeyPatterns.some((pattern) => lowerKey.includes(pattern));
-}
-
-function redactIfPII(key: string, value: string): string {
-  if (isPIIKey(key)) {
-    // REDACTOR_PATTERNS values are RegExp patterns
-    for (const [, pattern] of Object.entries(REDACTOR_PATTERNS)) {
-      if (pattern instanceof RegExp && pattern.test(value)) {
-        return '[REDACTED]';
-      }
-    }
-    // If no pattern matched but key is PII, still redact
-    return '[REDACTED]';
-  }
-  return value;
-}
-
-function hashIfPII(key: string, value: string): string {
-  if (!isPIIKey(key)) {
-    return value;
-  }
-
-  // Use a simple but consistent hash that produces 32-char hex
-  // FNV-1a hash variant producing 128-bit output (32 hex chars)
-  const FNV_PRIME = 0x01_00_01_93;
-  const FNV_OFFSET = 0x81_1c_9d_c5;
-
-  // Generate 4 32-bit hashes to produce 32 hex chars
-  const hashes: number[] = [];
-  for (let round = 0; round < 4; round++) {
-    let hash = FNV_OFFSET;
-    for (let i = 0; i < value.length; i++) {
-      hash ^= (value.codePointAt(i) ?? 0) + round;
-      hash = Math.imul(hash, FNV_PRIME);
-    }
-    hashes.push(hash >>> 0); // Convert to unsigned
-  }
-
-  return `hash_${hashes.map((h) => h.toString(16).padStart(8, '0')).join('')}`;
-}
-
-function truncateValue(key: string, value: string, maxLength: number): string {
-  if (value.length <= maxLength) {
-    return value;
-  }
-  return value.slice(0, maxLength - 3) + '...';
-}
-
-function normalizeHTTPMethod(method: string): string {
-  const upper = method.toUpperCase();
-  if (HTTP_METHODS.has(upper)) {
-    return upper;
-  }
-  return upper;
-}
-
-export function checkDeprecatedAttribute(
-  key: string,
-  policy: AttributePolicy = {},
-): string | null {
-  const { guardrails = {}, deprecatedWarnings = {} } = policy;
-  const { warnDeprecated = true } = guardrails;
-
-  if (!warnDeprecated) {
-    return null;
-  }
-
-  // Check if the key exists in the deprecated attributes map
-  const isDeprecated = key in DEPRECATED_ATTRIBUTES;
-  if (isDeprecated) {
-    const replacement =
-      DEPRECATED_ATTRIBUTES[key as keyof typeof DEPRECATED_ATTRIBUTES];
-    if (replacement === undefined) {
-      // Deprecated with no replacement (e.g., enduser.scope)
-      console.warn(
-        `[autotel/attributes] Attribute "${key}" is deprecated and has no replacement. ` +
-          `Remove or find a replacement in OpenTelemetry semantic conventions.`,
-      );
-    } else {
-      // Deprecated with a known replacement
-      console.warn(
-        `[autotel/attributes] Attribute "${key}" is deprecated. Use "${replacement}" instead.`,
-      );
-    }
-  }
-
-  if (deprecatedWarnings[key]) {
-    console.warn(`[autotel/attributes] ${deprecatedWarnings[key]}`);
-  }
-
-  const replacement =
-    DEPRECATED_ATTRIBUTES[key as keyof typeof DEPRECATED_ATTRIBUTES];
-  return replacement ?? null;
-}
-
-export function autoRedactPII(
-  attributes: Record<string, unknown>,
-  policy: AttributePolicy = {},
-): Record<string, unknown> {
-  const { guardrails = { pii: 'redact' } } = policy;
-
-  const redacted: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(attributes)) {
-    redacted[key] = validateAttribute(key, value, { guardrails });
-  }
-  return redacted;
-}
-
-export function defaultGuardrails(): AttributeGuardrails {
-  return {
-    pii: 'redact',
-    maxLength: 255,
-    validateEnum: true,
-    warnDeprecated: true,
-  };
-}

package/src/attributes.test.ts

@@ -1,292 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createTraceCollector, TraceCollector } from './testing';
-import { trace, TraceContext } from './functional';
-import {
-  attrs,
-  setUser,
-  identify,
-  httpServer,
-  mergeAttrs,
-  safeSetAttributes,
-  transaction,
-} from './attributes';
-
-describe('attributes', () => {
-  let collector: TraceCollector;
-
-  beforeEach(() => {
-    collector = createTraceCollector();
-  });
-
-  describe('Pattern A: Key builders', () => {
-    it('should create user.id attribute', async () => {
-      const testFn = trace((ctx: TraceContext) => async () => {
-        ctx.setAttributes(attrs.user.id('user-123'));
-      });
-
-      await testFn();
-
-      const spans = collector.getSpans();
-      expect(spans).toHaveLength(1);
-      expect(spans[0]!.attributes).toMatchObject({
-        'user.id': 'user-123',
-      });
-    });
-
-    it('should create http.request.method attribute', async () => {
-      const testFn = trace((ctx: TraceContext) => async () => {
-        ctx.setAttributes(attrs.http.request.method('GET'));
-      });
-
-      await testFn();
-
-      const spans = collector.getSpans();
-      expect(spans).toHaveLength(1);
-      expect(spans[0]!.attributes).toMatchObject({
-        'http.request.method': 'GET',
-      });
-    });
-
-    it('should create multiple attributes from key builders', async () => {
-      const testFn = trace((ctx: TraceContext) => async () => {
-        ctx.setAttributes(
-          mergeAttrs(
-            attrs.user.id('user-123'),
-            attrs.http.request.method('GET'),
-            attrs.session.id('session-456'),
-          ),
-        );
-      });
-
-      await testFn();
-
-      const spans = collector.getSpans();
-      expect(spans).toHaveLength(1);
-      expect(spans[0]!.attributes).toMatchObject({
-        'user.id': 'user-123',
-        'http.request.method': 'GET',
-        'session.id': 'session-456',
-      });
-    });
-  });
-
-  describe('Pattern B: Object builders', () => {
-    it('should create user attributes from object', async () => {
-      const testFn = trace((ctx: TraceContext) => async () => {
-        const userAttrs = attrs.user.data({
-          id: 'user-123',
-          email: 'test@example.com',
-        });
-        ctx.setAttributes(userAttrs);
-      });
-
-      await testFn();
-
-      const spans = collector.getSpans();
-      expect(spans).toHaveLength(1);
-      expect(spans[0]!.attributes).toMatchObject({
-        'user.id': 'user-123',
-        'user.email': 'test@example.com',
-      });
-    });
-
-    it('should create HTTP server attributes from object', async () => {
-      const testFn = trace((ctx: TraceContext) => async () => {
-        const httpAttrs = attrs.http.server({
-          method: 'POST',
-          route: '/users/:id',
-          statusCode: 200,
-        });
-        ctx.setAttributes(httpAttrs);
-      });
-
-      await testFn();
-
-      const spans = collector.getSpans();
-      expect(spans).toHaveLength(1);
-      expect(spans[0]!.attributes).toMatchObject({
-        'http.request.method': 'POST',
-        'http.route': '/users/:id',
-        'http.response.status_code': 200,
-      });
-    });
-  });
-
-  describe('Attachers: attachers', () => {
-    it('setUser should set user attributes on span (PII redacted by default)', async () => {
-      const testFn = trace((ctx: TraceContext) => async () => {
-        setUser(ctx, { id: 'user-123', email: 'test@example.com' });
-      });
-
-      await testFn();
-
-      const spans = collector.getSpans();
-      expect(spans).toHaveLength(1);
-      expect(spans[0]!.attributes).toMatchObject({
-        'user.id': 'user-123',
-        'user.email': '[REDACTED]', // PII is redacted by default
-      });
-    });
-
-    it('httpServer should set HTTP attributes and update span name', async () => {
-      const testFn = trace((ctx: TraceContext) => async () => {
-        httpServer(ctx, {
-          method: 'GET',
-          route: '/api/users',
-          statusCode: 200,
-        });
-      });
-
-      await testFn();
-
-      const spans = collector.getSpans();
-      expect(spans).toHaveLength(1);
-      expect(spans[0]!.attributes).toMatchObject({
-        'http.request.method': 'GET',
-        'http.route': '/api/users',
-        'http.response.status_code': 200,
-      });
-      expect(spans[0]!.name).toBe('HTTP GET /api/users');
-    });
-
-    it('identify should bundle user, session, and device attributes', async () => {
-      const testFn = trace((ctx: TraceContext) => async () => {
-        identify(ctx, {
-          user: { id: 'user-123', name: 'John Doe' },
-          session: { id: 'session-456' },
-          device: { id: 'device-789', manufacturer: 'Apple' },
-        });
-      });
-
-      await testFn();
-
-      const spans = collector.getSpans();
-      expect(spans).toHaveLength(1);
-      expect(spans[0]!.attributes).toMatchObject({
-        'user.id': 'user-123',
-        'user.name': 'John Doe',
-        'session.id': 'session-456',
-        'device.id': 'device-789',
-        'device.manufacturer': 'Apple',
-      });
-    });
-  });
-
-  describe('Domains: domains', () => {
-    it('transaction should bundle request attributes', async () => {
-      const testFn = trace((ctx: TraceContext) => async () => {
-        transaction(ctx, {
-          method: 'GET',
-          route: '/api/users',
-          statusCode: 200,
-          clientIp: '192.168.1.1',
-        });
-      });
-
-      await testFn();
-
-      const spans = collector.getSpans();
-      expect(spans).toHaveLength(1);
-      expect(spans[0]!.attributes).toMatchObject({
-        'http.request.method': 'GET',
-        'http.route': '/api/users',
-        'http.response.status_code': 200,
-        'network.peer.address': '192.168.1.1',
-      });
-    });
-  });
-
-  describe('Validators: validators', () => {
-    it('should redact PII attributes with default policy', async () => {
-      const testFn = trace((ctx: TraceContext) => async () => {
-        safeSetAttributes(
-          ctx,
-          attrs.user.data({ email: 'sensitive@example.com' }),
-          {
-            guardrails: { pii: 'redact' },
-          },
-        );
-      });
-
-      await testFn();
-
-      const spans = collector.getSpans();
-      expect(spans).toHaveLength(1);
-      expect(spans[0]!.attributes['user.email']).toBe('[REDACTED]');
-    });
-
-    it('should allow PII when guardrails pii is "allow"', async () => {
-      const testFn = trace((ctx: TraceContext) => async () => {
-        safeSetAttributes(
-          ctx,
-          attrs.user.data({ email: 'sensitive@example.com' }),
-          {
-            guardrails: { pii: 'allow' },
-          },
-        );
-      });
-
-      await testFn();
-
-      const spans = collector.getSpans();
-      expect(spans).toHaveLength(1);
-      expect(spans[0]!.attributes['user.email']).toBe('sensitive@example.com');
-    });
-
-    it('should hash PII when guardrails pii is "hash"', async () => {
-      const testFn = trace((ctx: TraceContext) => async () => {
-        safeSetAttributes(
-          ctx,
-          attrs.user.data({ email: 'sensitive@example.com' }),
-          {
-            guardrails: { pii: 'hash' },
-          },
-        );
-      });
-
-      await testFn();
-
-      const spans = collector.getSpans();
-      expect(spans).toHaveLength(1);
-      expect(spans[0]!.attributes['user.email']).toMatch(/^hash_[a-f0-9]+$/);
-    });
-
-    it('should log warning for deprecated attributes', async () => {
-      const consoleWarnSpy = vi.spyOn(console, 'warn');
-
-      const testFn = trace((ctx: TraceContext) => async () => {
-        // Use an actually deprecated attribute (http.method -> http.request.method)
-        safeSetAttributes(
-          ctx,
-          { 'http.method': 'GET' },
-          {
-            guardrails: { warnDeprecated: true },
-          },
-        );
-      });
-
-      await testFn();
-
-      expect(consoleWarnSpy).toHaveBeenCalledWith(
-        expect.stringContaining('deprecated'),
-      );
-      consoleWarnSpy.mockRestore();
-    });
-
-    it('should truncate values exceeding maxLength', async () => {
-      const testFn = trace((ctx: TraceContext) => async () => {
-        safeSetAttributes(ctx, attrs.user.data({ id: 'a'.repeat(300) }), {
-          guardrails: { maxLength: 255 },
-        });
-      });
-
-      await testFn();
-
-      const spans = collector.getSpans();
-      expect(spans).toHaveLength(1);
-      const userId = spans[0]!.attributes['user.id'] as string;
-      expect(userId.length).toBeLessThanOrEqual(255);
-      expect(userId).toMatch(/\.\.\.$/);
-    });
-  });
-});

package/src/auto.ts

@@ -1,67 +0,0 @@
-/**
- * Zero-config ESM instrumentation with auto-init from YAML/environment variables
- *
- * This module provides the simplest possible setup for OpenTelemetry instrumentation.
- * Just import it and everything is configured from autotel.yaml or environment variables.
- *
- * Usage with YAML config (recommended):
- * ```bash
- * # Create autotel.yaml in project root, then:
- * tsx --import autotel/auto src/index.ts
- * ```
- *
- * Usage with environment variables:
- * ```bash
- * OTEL_SERVICE_NAME=my-app tsx --import autotel/auto src/index.ts
- * ```
- *
- * No instrumentation.ts file needed!
- *
- * Configuration Priority (highest to lowest):
- * 1. YAML file (autotel.yaml or AUTOTEL_CONFIG_FILE)
- * 2. Environment variables (OTEL_*, AUTOTEL_*)
- * 3. Built-in defaults
- *
- * Environment Variables:
- * - OTEL_SERVICE_NAME: Service name (required for meaningful traces)
- * - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP collector endpoint (e.g., http://localhost:4318)
- * - OTEL_EXPORTER_OTLP_HEADERS: Auth headers (e.g., x-honeycomb-team=YOUR_KEY)
- * - AUTOTEL_INTEGRATIONS: Comma-separated list or 'true' for all (default: http,express)
- * - AUTOTEL_DEBUG: Set to 'true' to enable console span output
- * - AUTOTEL_CONFIG_FILE: Path to YAML config file (overrides autotel.yaml discovery)
- *
- * @requires Node.js 20.6.0 or later
- */
-
-import { register } from 'node:module';
-import { createAddHookMessageChannel } from 'import-in-the-middle';
-import { init } from './init';
-import { loadYamlConfig } from './yaml-config';
-
-// Register ESM hooks first (must happen before any instrumented modules load)
-const { registerOptions } = createAddHookMessageChannel();
-register('import-in-the-middle/hook.mjs', import.meta.url, registerOptions);
-
-// Load YAML config if present (init.ts will also load it, but we need values here)
-const yamlConfig = loadYamlConfig();
-
-// Parse auto-instrumentations from environment variable (fallback if not in YAML)
-const autoInstrumentationsEnv = process.env.AUTOTEL_INTEGRATIONS;
-const autoInstrumentations:
-  | string[]
-  | boolean
-  | Record<string, { enabled?: boolean }> =
-  autoInstrumentationsEnv === 'true'
-    ? true // Enable all auto-instrumentations
-    : autoInstrumentationsEnv
-      ? autoInstrumentationsEnv.split(',').map((s) => s.trim())
-      : (yamlConfig?.autoInstrumentations ?? ['http', 'express']); // YAML > default
-
-// Auto-initialize with YAML config merged with env var defaults
-// init() will load YAML again and merge properly, but we pass overrides here
-init({
-  service:
-    yamlConfig?.service ?? process.env.OTEL_SERVICE_NAME ?? 'unknown-service',
-  debug: yamlConfig?.debug ?? process.env.AUTOTEL_DEBUG === 'true',
-  autoInstrumentations,
-});