autotel 4.1.0 → 4.2.1

package/src/processors/canonical-log-line-processor.ts

@@ -1,396 +0,0 @@
-/**
- * Canonical Log Line Processor
- *
- * Automatically emits spans as canonical log lines (wide events) when they end.
- * Implements canonical log line" pattern: one comprehensive
- * event per request with all context.
- *
- * When a span ends, this processor creates a log record with ALL span attributes,
- * making the span itself the canonical log line that can be queried like structured data.
- *
- * @example
- * ```typescript
- * import { init } from 'autotel';
- *
- * init({
- *   service: 'my-app',
- *   canonicalLogLines: {
- *     enabled: true,
- *     rootSpansOnly: true, // One canonical log line per request
- *   },
- * });
- * ```
- */
-
-import type {
-  SpanProcessor,
-  ReadableSpan,
-} from '@opentelemetry/sdk-trace-base';
-import type { Attributes, AttributeValue } from '@opentelemetry/api';
-import { logs, SeverityNumber } from '@opentelemetry/api-logs';
-import type { Logger } from '../logger';
-import { formatPrettyLogLine, formatDuration } from '../pretty-log-formatter';
-
-/**
- * Function to redact sensitive attribute values
- */
-export type AttributeRedactorFn = (
-  key: string,
-  value: AttributeValue,
-) => AttributeValue;
-
-export interface CanonicalLogLineEvent {
-  span: ReadableSpan;
-  level: 'debug' | 'info' | 'warn' | 'error';
-  message: string;
-  event: Record<string, unknown>;
-}
-
-export interface KeepCondition {
-  /** Keep events where HTTP status >= this value. */
-  status?: number;
-  /** Keep events where duration_ms >= this value. */
-  durationMs?: number;
-  /** Keep events matching this path pattern (simple prefix match). */
-  path?: string;
-}
-
-export interface CanonicalLogLineOptions {
-  /** Logger to use for emitting canonical log lines (defaults to OTel Logs API) */
-  logger?: Logger;
-  /** Only emit canonical log lines for root spans (default: false) */
-  rootSpansOnly?: boolean;
-  /** Minimum log level for canonical log lines (default: 'info') */
-  minLevel?: 'debug' | 'info' | 'warn' | 'error';
-  /** Custom message format (default: uses span name) */
-  messageFormat?: (span: ReadableSpan) => string;
-  /** Whether to include resource attributes (default: true) */
-  includeResourceAttributes?: boolean;
-  /**
-   * Attribute redactor function to apply before logging.
-   * This ensures sensitive data is redacted in canonical log lines,
-   * matching the behavior of attributeRedactor in init().
-   */
-  attributeRedactor?: AttributeRedactorFn;
-  /** Predicate to decide whether to emit (runs after event is built). */
-  shouldEmit?: (ctx: CanonicalLogLineEvent) => boolean;
-  /**
-   * Declarative tail sampling conditions (OR logic). If any condition matches,
-   * the event is kept. Ignored when `shouldEmit` is provided.
-   *
-   * @example
-   * keep: [{ status: 500 }, { durationMs: 1000 }]
-   */
-  keep?: KeepCondition[];
-  /** Callback invoked after emit for custom fan-out. */
-  drain?: (ctx: CanonicalLogLineEvent) => void | Promise<void>;
-  /** Handler for drain failures. */
-  onDrainError?: (error: unknown, ctx: CanonicalLogLineEvent) => void;
-  /**
-   * Pretty-print canonical log lines to console in a tree format.
-   * Defaults to true when NODE_ENV is 'development'.
-   */
-  pretty?: boolean;
-}
-
-/**
- * Span processor that automatically emits spans as canonical log lines
- *
- * When a span ends, this processor creates a log record with ALL span attributes.
- * This implements the "canonical log line" pattern: one comprehensive event
- * per request with all context, queryable as structured data.
- *
- * **Key Benefits:**
- * - One log line per request with all context (wide event)
- * - High-cardinality, high-dimensionality data for powerful queries
- * - Automatic - no manual logging needed
- * - Works with any logger or OTel Logs API
- *
- * @example Basic usage
- * ```typescript
- * import { init } from 'autotel';
- *
- * init({
- *   service: 'checkout-api',
- *   canonicalLogLines: {
- *     enabled: true,
- *     rootSpansOnly: true, // One canonical log line per request
- *   },
- * });
- * ```
- *
- * @example With custom logger
- * ```typescript
- * import pino from 'pino';
- * import { init } from 'autotel';
- *
- * const logger = pino();
- * init({
- *   service: 'my-app',
- *   logger,
- *   canonicalLogLines: {
- *     enabled: true,
- *     logger, // Use Pino for canonical log lines
- *     rootSpansOnly: true,
- *   },
- * });
- * ```
- *
- * @example Custom message format
- * ```typescript
- * init({
- *   service: 'my-app',
- *   canonicalLogLines: {
- *     enabled: true,
- *     messageFormat: (span) => {
- *       const status = span.status.code === 2 ? 'ERROR' : 'SUCCESS';
- *       return `${span.name} [${status}]`;
- *     },
- *   },
- * });
- * ```
- */
-export class CanonicalLogLineProcessor implements SpanProcessor {
-  private logger?: Logger;
-  private rootSpansOnly: boolean;
-  private minLevel: 'debug' | 'info' | 'warn' | 'error';
-  private messageFormat: (span: ReadableSpan) => string;
-  private includeResourceAttributes: boolean;
-  private attributeRedactor?: AttributeRedactorFn;
-  private shouldEmit?: (ctx: CanonicalLogLineEvent) => boolean;
-  private drain?: (ctx: CanonicalLogLineEvent) => void | Promise<void>;
-  private onDrainError?: (error: unknown, ctx: CanonicalLogLineEvent) => void;
-  private pretty: boolean;
-  private getOTelLogger: (() => ReturnType<typeof logs.getLogger>) | null =
-    null;
-
-  constructor(options: CanonicalLogLineOptions = {}) {
-    this.logger = options.logger;
-    this.rootSpansOnly = options.rootSpansOnly ?? false;
-    this.minLevel = options.minLevel ?? 'info';
-    this.messageFormat =
-      options.messageFormat ?? ((span) => `[${span.name}] Request completed`);
-    this.includeResourceAttributes = options.includeResourceAttributes ?? true;
-    this.attributeRedactor = options.attributeRedactor;
-    this.shouldEmit =
-      options.shouldEmit ?? this.buildKeepPredicate(options.keep);
-    this.drain = options.drain;
-    this.onDrainError = options.onDrainError;
-    this.pretty =
-      options.pretty ??
-      (typeof process !== 'undefined' &&
-        process.env.NODE_ENV === 'development');
-
-    if (!this.logger) {
-      this.getOTelLogger = () => logs.getLogger('autotel.canonical-log-line');
-    }
-  }
-
-  private buildKeepPredicate(
-    keep?: KeepCondition[],
-  ): ((ctx: CanonicalLogLineEvent) => boolean) | undefined {
-    if (!keep || keep.length === 0) return undefined;
-
-    return (ctx: CanonicalLogLineEvent) => {
-      return keep.some((condition) => {
-        if (condition.status !== undefined) {
-          const httpStatus = Number(
-            ctx.event['http.response.status_code'] ?? 0,
-          );
-          if (httpStatus >= condition.status) return true;
-        }
-        if (
-          condition.durationMs !== undefined &&
-          Number(ctx.event.duration_ms ?? 0) >= condition.durationMs
-        ) {
-          return true;
-        }
-        if (condition.path !== undefined) {
-          const route = String(
-            ctx.event['http.route'] ?? ctx.event['url.path'] ?? '',
-          );
-          if (route.startsWith(condition.path)) return true;
-        }
-        return false;
-      });
-    };
-  }
-
-  onStart(): void {
-    // No-op
-  }
-
-  onEnd(span: ReadableSpan): void {
-    if (
-      this.rootSpansOnly &&
-      span.parentSpanContext?.spanId &&
-      !span.parentSpanContext.isRemote
-    ) {
-      return;
-    }
-
-    const level = this.getLogLevel(span);
-    if (!this.shouldLog(level)) {
-      return;
-    }
-
-    const canonicalLogLine = this.buildCanonicalLogLine(span);
-    const message = this.messageFormat(span);
-    const eventContext: CanonicalLogLineEvent = {
-      span,
-      level,
-      message,
-      event: canonicalLogLine,
-    };
-
-    if (this.shouldEmit && !this.shouldEmit(eventContext)) return;
-
-    if (this.pretty) {
-      console.log(formatPrettyLogLine(eventContext));
-    }
-
-    if (this.logger) {
-      this.emitViaLogger(level, message, canonicalLogLine);
-    } else if (this.getOTelLogger) {
-      const otelLogger = this.getOTelLogger();
-      this.emitViaOTel(level, message, canonicalLogLine, otelLogger);
-    }
-
-    if (this.drain) {
-      Promise.resolve(this.drain(eventContext)).catch((error) => {
-        if (this.onDrainError) {
-          this.onDrainError(error, eventContext);
-          return;
-        }
-        this.reportInternalWarning('canonicalLogLines.drain failed', error);
-      });
-    }
-  }
-
-  private buildCanonicalLogLine(span: ReadableSpan): Record<string, unknown> {
-    const durationMs = span.duration[0] * 1000 + span.duration[1] / 1_000_000;
-    const timestamp = new Date(
-      span.startTime[0] * 1000 + span.startTime[1] / 1_000_000,
-    ).toISOString();
-
-    // Span attributes first so core metadata fields below take precedence
-    const canonicalLogLine: Record<string, unknown> = {};
-    const attributes = this.redactAttributes(span.attributes);
-    Object.assign(canonicalLogLine, attributes);
-
-    if (this.includeResourceAttributes) {
-      const resourceAttrs = this.redactAttributes(
-        span.resource.attributes as Attributes,
-      );
-      Object.assign(canonicalLogLine, resourceAttrs);
-    }
-
-    canonicalLogLine.operation = span.name;
-    canonicalLogLine.traceId = span.spanContext().traceId;
-    canonicalLogLine.spanId = span.spanContext().spanId;
-    canonicalLogLine.correlationId = span.spanContext().traceId.slice(0, 16);
-    canonicalLogLine.duration_ms = Math.round(durationMs * 100) / 100;
-    canonicalLogLine.duration = formatDuration(durationMs);
-    canonicalLogLine.status_code = span.status.code;
-    canonicalLogLine.status_message = span.status.message || undefined;
-    canonicalLogLine.timestamp = timestamp;
-
-    return canonicalLogLine;
-  }
-
-  private redactAttributes(attributes: Attributes): Record<string, unknown> {
-    if (!this.attributeRedactor) {
-      return { ...attributes };
-    }
-
-    const redacted: Record<string, unknown> = {};
-    for (const [key, value] of Object.entries(attributes)) {
-      if (value !== undefined) {
-        redacted[key] = this.attributeRedactor(key, value);
-      }
-    }
-    return redacted;
-  }
-
-  private emitViaLogger(
-    level: 'debug' | 'info' | 'warn' | 'error',
-    message: string,
-    canonicalLogLine: Record<string, unknown>,
-  ): void {
-    this.logger![level](canonicalLogLine, message);
-  }
-
-  private emitViaOTel(
-    level: 'debug' | 'info' | 'warn' | 'error',
-    message: string,
-    canonicalLogLine: Record<string, unknown>,
-    otelLogger: ReturnType<typeof logs.getLogger>,
-  ): void {
-    const otelAttributes: Record<string, string | number | boolean> = {};
-    for (const [key, value] of Object.entries(canonicalLogLine)) {
-      if (
-        typeof value === 'string' ||
-        typeof value === 'number' ||
-        typeof value === 'boolean'
-      ) {
-        otelAttributes[key] = value;
-      } else if (value !== null && value !== undefined) {
-        otelAttributes[key] = String(value);
-      }
-    }
-    otelLogger.emit({
-      severityNumber: this.getSeverityNumber(level),
-      severityText: level.toUpperCase(),
-      body: message,
-      attributes: otelAttributes,
-    });
-  }
-
-  private getLogLevel(span: ReadableSpan): 'debug' | 'info' | 'warn' | 'error' {
-    const explicitLevel = span.attributes['autotel.log.level'];
-    if (
-      explicitLevel === 'debug' ||
-      explicitLevel === 'info' ||
-      explicitLevel === 'warn' ||
-      explicitLevel === 'error'
-    ) {
-      return explicitLevel;
-    }
-
-    if (span.status.code === 2) return 'error';
-    return 'info';
-  }
-
-  private shouldLog(level: string): boolean {
-    const levels = ['debug', 'info', 'warn', 'error'];
-    return levels.indexOf(level) >= levels.indexOf(this.minLevel);
-  }
-
-  private getSeverityNumber(level: string): SeverityNumber {
-    const mapping: Record<string, SeverityNumber> = {
-      debug: SeverityNumber.DEBUG,
-      info: SeverityNumber.INFO,
-      warn: SeverityNumber.WARN,
-      error: SeverityNumber.ERROR,
-    };
-    return mapping[level] ?? SeverityNumber.INFO;
-  }
-
-  private reportInternalWarning(message: string, error: unknown): void {
-    const err =
-      error instanceof Error ? error.message : String(error ?? 'unknown error');
-    if (this.logger) {
-      this.logger.warn({ error: err }, `[autotel] ${message}`);
-      return;
-    }
-    console.warn(`[autotel] ${message}: ${err}`);
-  }
-
-  async forceFlush(): Promise<void> {
-    // No-op
-  }
-
-  async shutdown(): Promise<void> {
-    // No-op
-  }
-}

package/src/processors.ts

@@ -1,152 +0,0 @@
-/**
- * OpenTelemetry Span Processors
- *
- * Re-exports commonly-needed OpenTelemetry span processors for custom configurations.
- *
- * These processors 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 when you need custom span processing logic beyond what `init()` provides.
- *
- * @example Simple processor (synchronous, for 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),
- * })
- * ```
- *
- * @example Batch processor (async batching, for production)
- * ```typescript
- * import { init } from 'autotel'
- * import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
- * import { BatchSpanProcessor } from 'autotel/processors'
- *
- * const exporter = new OTLPTraceExporter({ url: 'http://collector:4318/v1/traces' })
- * init({
- *   service: 'my-app',
- *   spanProcessor: new BatchSpanProcessor(exporter, {
- *     maxQueueSize: 2048,
- *     scheduledDelayMillis: 5000,
- *     exportTimeoutMillis: 30000,
- *     maxExportBatchSize: 512,
- *   }),
- * })
- * ```
- *
- * Note: Most users don't need to use processors directly - `init()` configures
- * BatchSpanProcessor by default. Use these when you need custom processing logic.
- *
- * @module autotel/processors
- * @see {@link https://opentelemetry.io/docs/specs/otel/trace/sdk/#span-processor | OTel Span Processor Spec}
- */
-
-export {
-  /**
-   * Simple span processor - processes spans synchronously.
-   *
-   * Perfect for:
-   * - Unit testing (synchronous span export)
-   * - Development (immediate span visibility)
-   * - Debugging (no batching delays)
-   *
-   * How it works:
-   * - Spans are exported immediately when they end
-   * - No batching or queuing
-   * - Blocking (export happens on the same thread)
-   *
-   * Warning: Not recommended for production - use BatchSpanProcessor instead.
-   * SimpleSpanProcessor can impact performance in high-throughput scenarios.
-   *
-   * @example
-   * ```typescript
-   * import { SimpleSpanProcessor } from 'autotel/processors'
-   * import { ConsoleSpanExporter } from 'autotel/exporters'
-   *
-   * const processor = new SimpleSpanProcessor(new ConsoleSpanExporter())
-   * ```
-   */
-  SimpleSpanProcessor,
-
-  /**
-   * Batch span processor - batches spans before exporting.
-   *
-   * Perfect for:
-   * - Production use (efficient, non-blocking)
-   * - High-throughput applications
-   * - Custom export configurations
-   *
-   * How it works:
-   * - Spans are queued in memory
-   * - Exported in batches at regular intervals
-   * - Non-blocking (export happens on background thread)
-   * - Configurable batch size, delay, queue size
-   *
-   * This is the default processor used by `init()`.
-   *
-   * @example Custom configuration
-   * ```typescript
-   * import { BatchSpanProcessor } from 'autotel/processors'
-   *
-   * const processor = new BatchSpanProcessor(exporter, {
-   *   maxQueueSize: 4096,           // Max spans in queue
-   *   scheduledDelayMillis: 10000,  // Export every 10s
-   *   exportTimeoutMillis: 30000,   // 30s export timeout
-   *   maxExportBatchSize: 1024,     // Max 1024 spans per batch
-   * })
-   * ```
-   */
-  BatchSpanProcessor,
-} from '@opentelemetry/sdk-trace-base';
-
-export {
-  /**
-   * Canonical log line processor - automatically emits spans as wide events
-   *
-   * When a span ends, this processor creates a log record with ALL span attributes.
-   * This implements the "canonical log line" pattern: one comprehensive event
-   * per request with all context, queryable as structured data.
-   *
-   * **Key Benefits:**
-   * - One log line per request with all context (wide event)
-   * - High-cardinality, high-dimensionality data for powerful queries
-   * - Automatic - no manual logging needed
-   * - Works with any logger or OTel Logs API
-   *
-   * @example Basic usage
-   * ```typescript
-   * import { init } from 'autotel';
-   *
-   * init({
-   *   service: 'checkout-api',
-   *   canonicalLogLines: {
-   *     enabled: true,
-   *     rootSpansOnly: true, // One canonical log line per request
-   *   },
-   * });
-   * ```
-   *
-   * @example With custom logger
-   * ```typescript
-   * import pino from 'pino';
-   * const logger = pino();
-   * init({
-   *   service: 'my-app',
-   *   logger,
-   *   canonicalLogLines: {
-   *     enabled: true,
-   *     logger, // Use Pino for canonical log lines
-   *     rootSpansOnly: true,
-   *   },
-   * });
-   * ```
-   */
-  CanonicalLogLineProcessor,
-  type CanonicalLogLineOptions,
-} from './processors/canonical-log-line-processor';