autotel 2.22.0 → 2.23.0

package/dist/yaml-config.d.ts

@@ -1,4 +1,4 @@
-import { A as AutotelConfig } from './init-ByRbNTRo.js';
+import { A as AutotelConfig } from './init-_FG4IbhF.js';
 import '@opentelemetry/sdk-trace-base';
 import '@opentelemetry/sdk-node';
 import '@opentelemetry/resources';
@@ -12,6 +12,7 @@ import '@opentelemetry/sdk-logs';
 import './filtering-span-processor.js';
 import './span-name-normalizer.js';
 import './attribute-redacting-processor.js';
+import './processors.js';
 
 /**
  * YAML configuration loader for autotel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel",
-  "version": "2.22.0",
+  "version": "2.23.0",
   "description": "Write Once, Observe Anywhere",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -202,6 +202,16 @@
       "types": "./dist/test-span-collector.d.ts",
       "import": "./dist/test-span-collector.js",
       "require": "./dist/test-span-collector.cjs"
+    },
+    "./parse-error": {
+      "types": "./dist/parse-error.d.ts",
+      "import": "./dist/parse-error.js",
+      "require": "./dist/parse-error.cjs"
+    },
+    "./drain-pipeline": {
+      "types": "./dist/drain-pipeline.d.ts",
+      "import": "./dist/drain-pipeline.js",
+      "require": "./dist/drain-pipeline.cjs"
     }
   },
   "files": [

package/src/drain-pipeline.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createDrainPipeline } from './drain-pipeline';
+
+describe('createDrainPipeline', () => {
+  it('batches by size and sends to drain', async () => {
+    const batchDrain = vi.fn(async () => {});
+    const pipeline = createDrainPipeline<number>({
+      batch: { size: 2, intervalMs: 1000 },
+    });
+    const drain = pipeline(batchDrain);
+
+    drain(1);
+    drain(2);
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(batchDrain).toHaveBeenCalledTimes(1);
+    expect(batchDrain).toHaveBeenCalledWith([1, 2]);
+    expect(drain.pending).toBe(0);
+  });
+
+  it('retries failed batches and eventually succeeds', async () => {
+    let attempts = 0;
+    const batchDrain = vi.fn(async () => {
+      attempts++;
+      if (attempts < 2) throw new Error('temporary');
+    });
+
+    const pipeline = createDrainPipeline<number>({
+      batch: { size: 1, intervalMs: 1000 },
+      retry: {
+        maxAttempts: 3,
+        initialDelayMs: 1,
+        maxDelayMs: 2,
+        backoff: 'fixed',
+        jitter: false,
+      },
+    });
+    const drain = pipeline(batchDrain);
+
+    drain(42);
+    await drain.flush();
+
+    expect(batchDrain).toHaveBeenCalledTimes(2);
+    expect(drain.pending).toBe(0);
+  });
+
+  it('drops overflowed events based on policy', async () => {
+    const dropped: number[] = [];
+    const batchDrain = vi.fn(async () => {});
+    const pipeline = createDrainPipeline<number>({
+      batch: { size: 10, intervalMs: 1000 },
+      maxBufferSize: 2,
+      dropPolicy: 'oldest',
+      onDropped: (events) => dropped.push(...events),
+    });
+    const drain = pipeline(batchDrain);
+
+    drain(1);
+    drain(2);
+    drain(3); // drops 1
+
+    expect(dropped).toEqual([1]);
+    expect(drain.pending).toBe(2);
+
+    await drain.flush();
+    expect(batchDrain).toHaveBeenCalledWith([2, 3]);
+  });
+});

package/src/drain-pipeline.ts

@@ -0,0 +1,199 @@
+export interface DrainPipelineOptions<T = unknown> {
+  batch?: {
+    /** Maximum events per batch. @default 50 */
+    size?: number;
+    /** Max time an event can stay buffered before flush. @default 5000 */
+    intervalMs?: number;
+  };
+  retry?: {
+    /** Total attempts including first try. @default 3 */
+    maxAttempts?: number;
+    /** Delay strategy between attempts. @default 'exponential' */
+    backoff?: 'exponential' | 'linear' | 'fixed';
+    /** Base delay for first retry. @default 1000 */
+    initialDelayMs?: number;
+    /** Max delay cap. @default 30000 */
+    maxDelayMs?: number;
+    /** Add random jitter to delays. @default true */
+    jitter?: boolean;
+  };
+  /** Max buffered events before dropping. @default 1000 */
+  maxBufferSize?: number;
+  /** Overflow policy. @default 'oldest' */
+  dropPolicy?: 'oldest' | 'newest';
+  /** Called when events are dropped from overflow or exhausted retries. */
+  onDropped?: (events: T[], error?: Error) => void;
+}
+
+export interface PipelineDrainFn<T> {
+  (ctx: T): void;
+  /** Flush all buffered events. */
+  flush: () => Promise<void>;
+  /** Flush and stop scheduling future timer work. */
+  shutdown: () => Promise<void>;
+  readonly pending: number;
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  });
+}
+
+export function createDrainPipeline<T = unknown>(
+  options?: DrainPipelineOptions<T>,
+): (drain: (batch: T[]) => void | Promise<void>) => PipelineDrainFn<T> {
+  const batchSize = options?.batch?.size ?? 50;
+  const intervalMs = options?.batch?.intervalMs ?? 5000;
+  const maxBufferSize = options?.maxBufferSize ?? 1000;
+  const maxAttempts = options?.retry?.maxAttempts ?? 3;
+  const backoff = options?.retry?.backoff ?? 'exponential';
+  const initialDelayMs = options?.retry?.initialDelayMs ?? 1000;
+  const maxDelayMs = options?.retry?.maxDelayMs ?? 30_000;
+  const jitter = options?.retry?.jitter ?? true;
+  const dropPolicy = options?.dropPolicy ?? 'oldest';
+  const onDropped = options?.onDropped;
+
+  if (!Number.isFinite(batchSize) || batchSize <= 0) {
+    throw new Error(
+      `[autotel/drain-pipeline] batch.size must be a positive finite number, got: ${batchSize}`,
+    );
+  }
+  if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+    throw new Error(
+      `[autotel/drain-pipeline] batch.intervalMs must be a positive finite number, got: ${intervalMs}`,
+    );
+  }
+  if (!Number.isFinite(maxBufferSize) || maxBufferSize <= 0) {
+    throw new Error(
+      `[autotel/drain-pipeline] maxBufferSize must be a positive finite number, got: ${maxBufferSize}`,
+    );
+  }
+  if (!Number.isFinite(maxAttempts) || maxAttempts <= 0) {
+    throw new Error(
+      `[autotel/drain-pipeline] retry.maxAttempts must be a positive finite number, got: ${maxAttempts}`,
+    );
+  }
+
+  return (drain: (batch: T[]) => void | Promise<void>): PipelineDrainFn<T> => {
+    const buffer: T[] = [];
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let activeFlush: Promise<void> | null = null;
+    let isShutdown = false;
+
+    const clearTimer = () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    };
+
+    const computeDelay = (attempt: number): number => {
+      const base =
+        backoff === 'fixed'
+          ? initialDelayMs
+          : backoff === 'linear'
+            ? initialDelayMs * attempt
+            : initialDelayMs * 2 ** (attempt - 1);
+
+      const bounded = Math.min(base, maxDelayMs);
+      if (!jitter || bounded <= 0) return bounded;
+      const factor = 0.5 + Math.random(); // [0.5, 1.5)
+      return Math.max(0, Math.round(bounded * factor));
+    };
+
+    const sendWithRetry = async (batch: T[]): Promise<void> => {
+      let lastError: Error | undefined;
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+          await drain(batch);
+          return;
+        } catch (error) {
+          lastError = error instanceof Error ? error : new Error(String(error));
+          if (attempt < maxAttempts) {
+            await wait(computeDelay(attempt));
+          }
+        }
+      }
+      onDropped?.(batch, lastError);
+    };
+
+    const drainBuffer = async (): Promise<void> => {
+      while (buffer.length > 0) {
+        const batch = buffer.splice(0, batchSize);
+        await sendWithRetry(batch);
+      }
+    };
+
+    const scheduleFlush = () => {
+      if (isShutdown || timer || activeFlush) return;
+      timer = setTimeout(() => {
+        timer = null;
+        startFlush();
+      }, intervalMs);
+      timer.unref?.();
+    };
+
+    const startFlush = () => {
+      if (activeFlush || isShutdown) return;
+      activeFlush = drainBuffer().finally(() => {
+        activeFlush = null;
+        if (isShutdown) return;
+        if (buffer.length >= batchSize) {
+          startFlush();
+        } else if (buffer.length > 0) {
+          scheduleFlush();
+        }
+      });
+    };
+
+    const push = (ctx: T) => {
+      if (isShutdown) return;
+
+      if (buffer.length >= maxBufferSize) {
+        if (dropPolicy === 'newest') {
+          onDropped?.([ctx]);
+          return;
+        }
+        const dropped = buffer.splice(0, 1);
+        onDropped?.(dropped);
+      }
+
+      buffer.push(ctx);
+      if (buffer.length >= batchSize) {
+        clearTimer();
+        startFlush();
+      } else {
+        scheduleFlush();
+      }
+    };
+
+    const flush = async (): Promise<void> => {
+      clearTimer();
+      if (activeFlush) await activeFlush;
+
+      const snapshot = buffer.length;
+      if (snapshot <= 0) return;
+      const toFlush = buffer.splice(0, snapshot);
+      while (toFlush.length > 0) {
+        const batch = toFlush.splice(0, batchSize);
+        await sendWithRetry(batch);
+      }
+    };
+
+    const shutdown = async (): Promise<void> => {
+      isShutdown = true;
+      await flush();
+    };
+
+    const fn = push as PipelineDrainFn<T>;
+    fn.flush = flush;
+    fn.shutdown = shutdown;
+    Object.defineProperty(fn, 'pending', {
+      enumerable: true,
+      get: () => buffer.length,
+    });
+    return fn;
+  };
+}

package/src/flatten-attributes.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { toAttributeValue, flattenToAttributes } from './flatten-attributes';
+
+describe('toAttributeValue', () => {
+  it('returns primitives as-is', () => {
+    expect(toAttributeValue('hello')).toBe('hello');
+    expect(toAttributeValue(42)).toBe(42);
+    expect(toAttributeValue(true)).toBe(true);
+  });
+
+  it('returns homogeneous arrays as-is', () => {
+    expect(toAttributeValue(['a', 'b'])).toEqual(['a', 'b']);
+    expect(toAttributeValue([1, 2])).toEqual([1, 2]);
+    expect(toAttributeValue([true, false])).toEqual([true, false]);
+  });
+
+  it('serialises mixed arrays to JSON', () => {
+    expect(toAttributeValue([1, 'a'])).toBe('[1,"a"]');
+  });
+
+  it('converts Date to ISO string', () => {
+    const d = new Date('2025-01-01T00:00:00Z');
+    expect(toAttributeValue(d)).toBe('2025-01-01T00:00:00.000Z');
+  });
+
+  it('converts Error to its message', () => {
+    expect(toAttributeValue(new Error('boom'))).toBe('boom');
+  });
+
+  it('returns undefined for plain objects', () => {
+    expect(toAttributeValue({ a: 1 })).toBeUndefined();
+  });
+});
+
+describe('flattenToAttributes', () => {
+  it('flattens nested objects with dot-notation keys', () => {
+    expect(
+      flattenToAttributes({ user: { id: 'u1', plan: 'pro' }, count: 3 }),
+    ).toEqual({
+      'user.id': 'u1',
+      'user.plan': 'pro',
+      count: 3,
+    });
+  });
+
+  it('uses prefix when provided', () => {
+    expect(flattenToAttributes({ key: 'val' }, 'error.details')).toEqual({
+      'error.details.key': 'val',
+    });
+  });
+
+  it('skips null and undefined values', () => {
+    expect(
+      flattenToAttributes({ a: 1, b: null, c: undefined, d: 'ok' }),
+    ).toEqual({ a: 1, d: 'ok' });
+  });
+
+  it('handles circular references without stack overflow', () => {
+    const obj: Record<string, unknown> = { name: 'root' };
+    obj.self = obj;
+
+    const result = flattenToAttributes(obj);
+    expect(result).toEqual({
+      name: 'root',
+      'self.name': 'root',
+      'self.self': '<circular-reference>',
+    });
+  });
+
+  it('serialises non-plain objects to JSON', () => {
+    const result = flattenToAttributes({
+      date: new Date('2025-01-01T00:00:00Z'),
+    });
+    expect(result).toEqual({ date: '2025-01-01T00:00:00.000Z' });
+  });
+});

package/src/flatten-attributes.ts

@@ -0,0 +1,80 @@
+import type { AttributeValue } from './trace-context';
+
+/**
+ * Convert an unknown value to an OTel-compatible AttributeValue.
+ * Returns undefined when the value cannot be represented.
+ */
+export function toAttributeValue(value: unknown): AttributeValue | undefined {
+  if (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (
+      value.every((v) => typeof v === 'string') ||
+      value.every((v) => typeof v === 'number') ||
+      value.every((v) => typeof v === 'boolean')
+    ) {
+      return value as AttributeValue;
+    }
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return '<serialization-failed>';
+    }
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (value instanceof Error) {
+    return value.message;
+  }
+  return undefined;
+}
+
+/**
+ * Recursively flatten a nested object into dot-notation OTel attributes.
+ * Includes circular reference protection via WeakSet.
+ */
+export function flattenToAttributes(
+  fields: Record<string, unknown>,
+  prefix = '',
+): Record<string, AttributeValue> {
+  const out: Record<string, AttributeValue> = {};
+  const seen = new WeakSet<object>();
+
+  function flatten(obj: Record<string, unknown>, currentPrefix: string): void {
+    for (const [key, value] of Object.entries(obj)) {
+      if (value == null) continue;
+      const nextKey = currentPrefix ? `${currentPrefix}.${key}` : key;
+
+      const attr = toAttributeValue(value);
+      if (attr !== undefined) {
+        out[nextKey] = attr;
+        continue;
+      }
+
+      if (typeof value === 'object' && value.constructor === Object) {
+        if (seen.has(value)) {
+          out[nextKey] = '<circular-reference>';
+          continue;
+        }
+        seen.add(value);
+        flatten(value as Record<string, unknown>, nextKey);
+        continue;
+      }
+
+      try {
+        out[nextKey] = JSON.stringify(value);
+      } catch {
+        out[nextKey] = '<serialization-failed>';
+      }
+    }
+  }
+
+  flatten(fields, prefix);
+  return out;
+}

package/src/functional.test.ts

@@ -173,6 +173,69 @@ describe('Functional API', () => {
       });
     });
 
+    describe('zero-arg factory pattern (no ctx parameter)', () => {
+      it('should detect zero-arg sync factory and execute inner function', () => {
+        const collector = createTraceCollector();
+
+        const addOne = trace(() => (i: number) => {
+          return i + 1;
+        });
+
+        const result = addOne(1);
+
+        expect(result).toBe(2);
+        expect(result).not.toBeInstanceOf(Promise);
+
+        const spans = collector.getSpans();
+        expect(spans).toHaveLength(1);
+      });
+
+      it('should detect zero-arg async factory and execute inner function', async () => {
+        const collector = createTraceCollector();
+
+        const fetchData = trace(() => async (query: string) => {
+          return query.toUpperCase();
+        });
+
+        const result = await fetchData('test');
+
+        expect(result).toBe('TEST');
+
+        const spans = collector.getSpans();
+        expect(spans).toHaveLength(1);
+      });
+
+      it('should work with named zero-arg factory', () => {
+        const collector = createTraceCollector();
+
+        const addOne = trace('addOne', () => (i: number) => {
+          return i + 1;
+        });
+
+        const result = addOne(1);
+
+        expect(result).toBe(2);
+
+        const spans = collector.getSpans();
+        expect(spans).toHaveLength(1);
+        expect(spans[0]!.name).toBe('addOne');
+      });
+
+      it('should handle multiple zero-arg factories combined', () => {
+        const collector = createTraceCollector();
+
+        const addOne = trace('addOne', () => (i: number) => i + 1);
+        const addTwo = trace('addTwo', () => (i: number) => i + 2);
+
+        const result = addOne(1) + addTwo(1);
+
+        expect(result).toBe(5);
+
+        const spans = collector.getSpans();
+        expect(spans).toHaveLength(2);
+      });
+    });
+
     describe('overload 2: trace(name, fn)', () => {
       it('should use custom name', async () => {
         const collector = createTraceCollector();

package/src/functional.ts

@@ -168,6 +168,14 @@ function looksLikeTraceFactory(fn: GenericFunction): boolean {
   }
 
   if (fn.length === 0) {
+    if (!isAsyncFunction(fn)) {
+      try {
+        const result = fn();
+        return typeof result === 'function';
+      } catch {
+        return false;
+      }
+    }
     return false;
   }
 
@@ -2361,14 +2369,14 @@ export function withBaggage<T = unknown>(
         }
         return value;
       },
-      (err) => {
+      (error) => {
         // Restore original context before rejecting
         if (previousStored) {
           return ctxStorage.run(previousStored, () => {
-            throw err;
+            throw error;
           });
         }
-        throw err;
+        throw error;
       },
     );
   }

package/src/index.ts

@@ -110,6 +110,39 @@ export {
 // Graceful shutdown
 export { flush, shutdown } from './shutdown';
 
+// Request logger
+export {
+  getRequestLogger,
+  type RequestLogger,
+  type RequestLogSnapshot,
+  type RequestLoggerOptions,
+} from './request-logger';
+
+// Structured errors
+export {
+  createStructuredError,
+  getStructuredErrorAttributes,
+  recordStructuredError,
+  type StructuredError,
+  type StructuredErrorInput,
+} from './structured-error';
+
+// parseError
+export { parseError, type ParsedError } from './parse-error';
+
+// Attribute flattening
+export { toAttributeValue, flattenToAttributes } from './flatten-attributes';
+
+// Drain pipeline
+export {
+  createDrainPipeline,
+  type DrainPipelineOptions,
+  type PipelineDrainFn,
+} from './drain-pipeline';
+
+// Pretty log formatting
+export { formatDuration } from './pretty-log-formatter';
+
 // Re-export sampling strategies
 export {
   type Sampler,

package/src/init.ts

@@ -976,6 +976,23 @@ export interface AutotelConfig {
     ) => string;
     /** Whether to include resource attributes (default: true) */
     includeResourceAttributes?: boolean;
+    /** Predicate to decide whether to emit (runs after event is built). */
+    shouldEmit?: CanonicalLogLineOptions['shouldEmit'];
+    /**
+     * Declarative tail sampling conditions (OR logic).
+     * Ignored when `shouldEmit` is provided.
+     * @example keep: [{ status: 500 }, { durationMs: 1000 }]
+     */
+    keep?: CanonicalLogLineOptions['keep'];
+    /** Callback invoked after emit for custom fan-out. */
+    drain?: CanonicalLogLineOptions['drain'];
+    /** Handler for drain failures. */
+    onDrainError?: CanonicalLogLineOptions['onDrainError'];
+    /**
+     * Pretty-print canonical log lines to console.
+     * Defaults to true when NODE_ENV is 'development'.
+     */
+    pretty?: boolean;
   };
 }
 
@@ -1247,6 +1264,11 @@ export function init(cfg: AutotelConfig): void {
       messageFormat: mergedConfig.canonicalLogLines.messageFormat,
       includeResourceAttributes:
         mergedConfig.canonicalLogLines.includeResourceAttributes,
+      shouldEmit: mergedConfig.canonicalLogLines.shouldEmit,
+      keep: mergedConfig.canonicalLogLines.keep,
+      drain: mergedConfig.canonicalLogLines.drain,
+      onDrainError: mergedConfig.canonicalLogLines.onDrainError,
+      pretty: mergedConfig.canonicalLogLines.pretty,
     };
     spanProcessors.push(new CanonicalLogLineProcessor(canonicalOptions));
   }