autotel 2.22.0 → 2.23.0

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

@@ -17,8 +17,6 @@ describe('CanonicalLogLineProcessor', () => {
 
   beforeEach(() => {
     logEntries = [];
-    // Pino-native signature: (extra, message)
-    // The processor ONLY calls with this order, so we can cast safely
     mockLogger = {
       info: vi.fn((extra, msg) => {
         logEntries.push({
@@ -63,7 +61,7 @@ describe('CanonicalLogLineProcessor', () => {
         spanId: '00f067aa0ba902b7',
         traceFlags: 1,
       }),
-      parentSpanContext: undefined, // No parent by default (root span)
+      parentSpanContext: undefined,
       attributes: {
         'user.id': 'user-123',
         'cart.total_cents': 15_999,
@@ -73,7 +71,7 @@ describe('CanonicalLogLineProcessor', () => {
       duration: [0, 1_247_000_000], // 1.247 seconds in nanoseconds
       startTime: [1_703_044_800, 0], // Unix timestamp in nanoseconds
       endTime: [1_703_044_800, 1_247_000_000],
-      kind: SpanKind.SERVER, // Default to SERVER (service entry point)
+      kind: SpanKind.SERVER,
       resource: resourceFromAttributes({
         'service.name': 'test-service',
         'service.version': '1.0.0',
@@ -100,7 +98,7 @@ describe('CanonicalLogLineProcessor', () => {
         operation: 'test.operation',
         traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
         spanId: '00f067aa0ba902b7',
-        correlationId: '4bf92f3577b34da6', // First 16 chars of traceId
+        correlationId: '4bf92f3577b34da6',
         'user.id': 'user-123',
         'cart.total_cents': 15_999,
         'http.method': 'POST',
@@ -181,14 +179,12 @@ describe('CanonicalLogLineProcessor', () => {
         logger: mockLogger,
         rootSpansOnly: true,
       });
-      // Create a span with a LOCAL parent (isRemote: false)
-      // This is a child span within the same service and should be skipped
       const span = createMockSpan({
         parentSpanContext: {
           traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
           spanId: 'local-parent-span-id',
           traceFlags: 1,
-          isRemote: false, // Local parent (same service)
+          isRemote: false,
         },
       });
 
@@ -202,20 +198,17 @@ describe('CanonicalLogLineProcessor', () => {
         logger: mockLogger,
         rootSpansOnly: true,
       });
-      // Create a span with a REMOTE parent (isRemote: true)
-      // This is a service entry point from distributed tracing
       const span = createMockSpan({
         parentSpanContext: {
           traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
           spanId: 'remote-parent-span-id',
           traceFlags: 1,
-          isRemote: true, // Remote parent (from upstream service)
+          isRemote: true,
         },
       });
 
       processor.onEnd(span);
 
-      // Should emit because this is a service entry point (remote parent)
       expect(mockLogger.info).toHaveBeenCalledTimes(1);
     });
 
@@ -224,13 +217,12 @@ describe('CanonicalLogLineProcessor', () => {
         logger: mockLogger,
         rootSpansOnly: false,
       });
-      // Even a local child span should emit when rootSpansOnly is false
       const span = createMockSpan({
         parentSpanContext: {
           traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
           spanId: 'parent-span-id',
           traceFlags: 1,
-          isRemote: false, // Local parent
+          isRemote: false,
         },
       });
 
@@ -255,10 +247,7 @@ describe('CanonicalLogLineProcessor', () => {
       expect(mockLogger.error).toHaveBeenCalledTimes(1);
       expect(logEntries[0].level).toBe('error');
       expect(logEntries[0].attrs.status_code).toBe(SpanStatusCode.ERROR);
-      // status_message might be undefined if not set
-      if (logEntries[0].attrs.status_message) {
-        expect(logEntries[0].attrs.status_message).toBe('Something went wrong');
-      }
+      expect(logEntries[0].attrs.status_message).toBe('Something went wrong');
     });
 
     it('should use info level for successful spans', () => {
@@ -272,6 +261,20 @@ describe('CanonicalLogLineProcessor', () => {
       expect(mockLogger.info).toHaveBeenCalledTimes(1);
       expect(logEntries[0].level).toBe('info');
     });
+
+    it('should use explicit autotel.log.level attribute when provided', () => {
+      const processor = new CanonicalLogLineProcessor({ logger: mockLogger });
+      const span = createMockSpan({
+        attributes: {
+          'autotel.log.level': 'warn',
+        },
+      });
+
+      processor.onEnd(span);
+
+      expect(mockLogger.warn).toHaveBeenCalledTimes(1);
+      expect(logEntries[0].level).toBe('warn');
+    });
   });
 
   describe('minLevel option', () => {
@@ -280,12 +283,10 @@ describe('CanonicalLogLineProcessor', () => {
         logger: mockLogger,
         minLevel: 'info',
       });
-      // Would need to force debug level, but for now just test the filter
       const span = createMockSpan();
 
       processor.onEnd(span);
 
-      // Should still log info level
       expect(mockLogger.info).toHaveBeenCalledTimes(1);
     });
 
@@ -295,12 +296,11 @@ describe('CanonicalLogLineProcessor', () => {
         minLevel: 'warn',
       });
       const span = createMockSpan({
-        status: { code: SpanStatusCode.OK }, // Would be info level
+        status: { code: SpanStatusCode.OK },
       });
 
       processor.onEnd(span);
 
-      // Info is below warn, so should be skipped
       expect(mockLogger.info).not.toHaveBeenCalled();
     });
   });
@@ -322,6 +322,65 @@ describe('CanonicalLogLineProcessor', () => {
     });
   });
 
+  describe('emit control hooks', () => {
+    it('should skip emit when shouldEmit returns false', () => {
+      const shouldEmit = vi.fn(() => false);
+      const processor = new CanonicalLogLineProcessor({
+        logger: mockLogger,
+        shouldEmit,
+      });
+      const span = createMockSpan();
+
+      processor.onEnd(span);
+
+      expect(shouldEmit).toHaveBeenCalledTimes(1);
+      expect(mockLogger.info).not.toHaveBeenCalled();
+    });
+
+    it('should call drain after emit with canonical event context', async () => {
+      const drain = vi.fn(async () => {});
+      const processor = new CanonicalLogLineProcessor({
+        logger: mockLogger,
+        drain,
+      });
+      const span = createMockSpan();
+
+      processor.onEnd(span);
+      await new Promise((resolve) => setImmediate(resolve));
+
+      expect(mockLogger.info).toHaveBeenCalledTimes(1);
+      expect(drain).toHaveBeenCalledTimes(1);
+      expect(drain.mock.calls[0][0]).toMatchObject({
+        level: 'info',
+        message: expect.stringContaining('test.operation'),
+        event: expect.objectContaining({
+          operation: 'test.operation',
+          traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
+        }),
+      });
+    });
+
+    it('should not keep below-threshold HTTP status when keep.status is configured', () => {
+      const processor = new CanonicalLogLineProcessor({
+        logger: mockLogger,
+        keep: [{ status: 500 }],
+      });
+      const span = createMockSpan({
+        status: { code: SpanStatusCode.ERROR },
+        attributes: {
+          'http.response.status_code': 404,
+        },
+      });
+
+      processor.onEnd(span);
+
+      expect(mockLogger.error).not.toHaveBeenCalled();
+      expect(mockLogger.info).not.toHaveBeenCalled();
+      expect(mockLogger.warn).not.toHaveBeenCalled();
+      expect(mockLogger.debug).not.toHaveBeenCalled();
+    });
+  });
+
   describe('OTel Logs API fallback', () => {
     it('should use OTel Logs API when no logger provided', () => {
       // Mock the logs API
@@ -373,7 +432,6 @@ describe('CanonicalLogLineProcessor', () => {
 
       expect(mockLogger.info).toHaveBeenCalledTimes(1);
       const call = logEntries[0];
-      // Should include all 100 attributes plus core fields
       expect(Object.keys(call.attrs).length).toBeGreaterThan(100);
     });
 
@@ -438,7 +496,6 @@ describe('CanonicalLogLineProcessor', () => {
   describe('attribute collision prevention', () => {
     it('should not allow span attributes to overwrite core metadata', () => {
       const processor = new CanonicalLogLineProcessor({ logger: mockLogger });
-      // Create a span with attributes that match core metadata field names
       const span = createMockSpan({
         attributes: {
           traceId: 'malicious-trace-id',
@@ -454,7 +511,6 @@ describe('CanonicalLogLineProcessor', () => {
       processor.onEnd(span);
 
       const call = logEntries[0];
-      // Core metadata should NOT be overwritten by span attributes
       expect(call.attrs.traceId).toBe('4bf92f3577b34da6a3ce929d0e0e4736');
       expect(call.attrs.spanId).toBe('00f067aa0ba902b7');
       expect(call.attrs.operation).toBe('test.operation');

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

@@ -29,6 +29,7 @@ import type {
 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
@@ -38,6 +39,22 @@ export type AttributeRedactorFn = (
   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;
@@ -55,6 +72,25 @@ export interface CanonicalLogLineOptions {
    * 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;
 }
 
 /**
@@ -121,6 +157,10 @@ export class CanonicalLogLineProcessor implements SpanProcessor {
   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;
 
@@ -132,25 +172,55 @@ export class CanonicalLogLineProcessor implements SpanProcessor {
       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');
 
-    // Lazy-load OTel logger if no custom logger provided
-    // We can't initialize it here because logs API might not be ready
     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 - we only care about span end
+    // No-op
   }
 
   onEnd(span: ReadableSpan): void {
-    // Skip if rootSpansOnly and this span has a LOCAL parent (same service)
-    // We still emit for spans with REMOTE parents (from distributed tracing)
-    // because those are the entry points ("roots") for THIS service.
-    // Check if parent is remote (from another service via traceparent/b3 headers)
-    // If isRemote is true, this span is a service entry point and should emit
-    // If isRemote is false/undefined, this is a local child span and should be skipped
     if (
       this.rootSpansOnly &&
       span.parentSpanContext?.spanId &&
@@ -159,44 +229,55 @@ export class CanonicalLogLineProcessor implements SpanProcessor {
       return;
     }
 
-    // Determine log level from span status
     const level = this.getLogLevel(span);
     if (!this.shouldLog(level)) {
       return;
     }
 
-    // Build canonical log line with ALL span attributes
     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));
+    }
 
-    // Emit via logger or OTel Logs API
     if (this.logger) {
-      this.emitViaLogger(level, span, canonicalLogLine);
+      this.emitViaLogger(level, message, canonicalLogLine);
     } else if (this.getOTelLogger) {
       const otelLogger = this.getOTelLogger();
-      this.emitViaOTel(level, span, canonicalLogLine, otelLogger);
+      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> {
-    // Convert duration from [seconds, nanoseconds] to milliseconds
-    // duration[0] is seconds, duration[1] is nanoseconds (fractional part)
     const durationMs = span.duration[0] * 1000 + span.duration[1] / 1_000_000;
-
-    // Convert start time from [seconds, nanoseconds] to ISO string
-    // startTime[0] is seconds, startTime[1] is nanoseconds (fractional part)
     const timestamp = new Date(
       span.startTime[0] * 1000 + span.startTime[1] / 1_000_000,
     ).toISOString();
 
-    // Start with span attributes (potentially redacted)
-    // We add these FIRST so core metadata fields below can't be overwritten
+    // Span attributes first so core metadata fields below take precedence
     const canonicalLogLine: Record<string, unknown> = {};
-
-    // Apply redaction to span attributes if redactor is configured
     const attributes = this.redactAttributes(span.attributes);
     Object.assign(canonicalLogLine, attributes);
 
-    // Include resource attributes (service-level context), also redacted
     if (this.includeResourceAttributes) {
       const resourceAttrs = this.redactAttributes(
         span.resource.attributes as Attributes,
@@ -204,13 +285,12 @@ export class CanonicalLogLineProcessor implements SpanProcessor {
       Object.assign(canonicalLogLine, resourceAttrs);
     }
 
-    // Set core metadata fields LAST to prevent span attributes from overwriting them
-    // (e.g., if a span has an attribute named "traceId" or "timestamp")
     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;
@@ -218,12 +298,8 @@ export class CanonicalLogLineProcessor implements SpanProcessor {
     return canonicalLogLine;
   }
 
-  /**
-   * Apply attribute redaction if a redactor is configured
-   */
   private redactAttributes(attributes: Attributes): Record<string, unknown> {
     if (!this.attributeRedactor) {
-      // No redaction configured, return as-is
       return { ...attributes };
     }
 
@@ -238,22 +314,18 @@ export class CanonicalLogLineProcessor implements SpanProcessor {
 
   private emitViaLogger(
     level: 'debug' | 'info' | 'warn' | 'error',
-    span: ReadableSpan,
+    message: string,
     canonicalLogLine: Record<string, unknown>,
   ): void {
-    const message = this.messageFormat(span);
-    // Pino-compatible signature: (extra, message)
     this.logger![level](canonicalLogLine, message);
   }
 
   private emitViaOTel(
     level: 'debug' | 'info' | 'warn' | 'error',
-    span: ReadableSpan,
+    message: string,
     canonicalLogLine: Record<string, unknown>,
     otelLogger: ReturnType<typeof logs.getLogger>,
   ): void {
-    const message = this.messageFormat(span);
-    // Convert unknown values to strings for OTel Logs API compatibility
     const otelAttributes: Record<string, string | number | boolean> = {};
     for (const [key, value] of Object.entries(canonicalLogLine)) {
       if (
@@ -275,11 +347,17 @@ export class CanonicalLogLineProcessor implements SpanProcessor {
   }
 
   private getLogLevel(span: ReadableSpan): 'debug' | 'info' | 'warn' | 'error' {
-    // ERROR status code is 2
-    if (span.status.code === 2) return 'error';
+    const explicitLevel = span.attributes['autotel.log.level'];
+    if (
+      explicitLevel === 'debug' ||
+      explicitLevel === 'info' ||
+      explicitLevel === 'warn' ||
+      explicitLevel === 'error'
+    ) {
+      return explicitLevel;
+    }
 
-    // Could check for slow spans, etc. in the future
-    // For now, default to info
+    if (span.status.code === 2) return 'error';
     return 'info';
   }
 
@@ -298,11 +376,21 @@ export class CanonicalLogLineProcessor implements SpanProcessor {
     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 - logging is fire-and-forget
+    // No-op
   }
 
   async shutdown(): Promise<void> {
-    // No-op - logging is fire-and-forget
+    // No-op
   }
 }

package/src/request-logger.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRequestLogger } from './request-logger';
+import type { TraceContext } from './trace-context';
+
+function createMockContext(): TraceContext {
+  return {
+    traceId: 'trace-id',
+    spanId: 'span-id',
+    correlationId: 'corr-id',
+    setAttribute: vi.fn(),
+    setAttributes: vi.fn(),
+    setStatus: vi.fn(),
+    recordException: vi.fn(),
+    addEvent: vi.fn(),
+    addLink: vi.fn(),
+    addLinks: vi.fn(),
+    updateName: vi.fn(),
+    isRecording: vi.fn(() => true),
+    getBaggage: vi.fn(),
+    setBaggage: vi.fn(),
+    deleteBaggage: vi.fn(),
+    getAllBaggage: vi.fn(() => new Map()),
+  } as unknown as TraceContext;
+}
+
+describe('getRequestLogger', () => {
+  it('sets flattened fields onto active span context', () => {
+    const ctx = createMockContext();
+    const log = getRequestLogger(ctx);
+
+    log.set({
+      user: { id: 'u1', plan: 'pro' },
+      attempts: 3,
+      success: true,
+    });
+
+    expect(ctx.setAttributes).toHaveBeenCalledWith({
+      'user.id': 'u1',
+      'user.plan': 'pro',
+      attempts: 3,
+      success: true,
+    });
+  });
+
+  it('adds warning events and sets warning level marker', () => {
+    const ctx = createMockContext();
+    const log = getRequestLogger(ctx);
+
+    log.warn('slow request', {
+      http: { route: '/checkout' },
+      duration_ms: 1350,
+    });
+
+    expect(ctx.addEvent).toHaveBeenCalledWith('log.warn', {
+      message: 'slow request',
+      'http.route': '/checkout',
+      duration_ms: 1350,
+    });
+    expect(ctx.setAttribute).toHaveBeenCalledWith('autotel.log.level', 'warn');
+  });
+
+  it('records and annotates errors with structured diagnostics', () => {
+    const ctx = createMockContext();
+    const log = getRequestLogger(ctx);
+
+    log.error(new Error('payment processor unavailable'), {
+      step: 'payment',
+    });
+
+    expect(ctx.recordException).toHaveBeenCalled();
+    expect(ctx.addEvent).toHaveBeenCalledWith('log.error', {
+      message: 'payment processor unavailable',
+      step: 'payment',
+    });
+    expect(ctx.setAttributes).toHaveBeenCalledWith(
+      expect.objectContaining({
+        'error.message': 'payment processor unavailable',
+      }),
+    );
+  });
+
+  it('returns accumulated context via getContext()', () => {
+    const ctx = createMockContext();
+    const log = getRequestLogger(ctx);
+
+    log.set({ user: { id: 'u1' } });
+    log.info('step', { checkout: { step: 'payment' } });
+
+    expect(log.getContext()).toEqual({
+      user: { id: 'u1' },
+      checkout: { step: 'payment' },
+    });
+  });
+
+  it('emitNow records manual event and returns snapshot', async () => {
+    const ctx = createMockContext();
+    const onEmit = vi.fn(async () => {});
+    const log = getRequestLogger(ctx, { onEmit });
+
+    log.set({ user: { id: 'u1' } });
+    const snapshot = log.emitNow({ stage: 'preflight' });
+
+    expect(snapshot).toMatchObject({
+      traceId: 'trace-id',
+      spanId: 'span-id',
+      correlationId: 'corr-id',
+      context: {
+        user: { id: 'u1' },
+        stage: 'preflight',
+      },
+      timestamp: expect.any(String),
+    });
+    expect(ctx.addEvent).toHaveBeenCalledWith(
+      'log.emit.manual',
+      expect.objectContaining({
+        'user.id': 'u1',
+        stage: 'preflight',
+      }),
+    );
+
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(onEmit).toHaveBeenCalledWith(snapshot);
+  });
+});