autotel 2.22.0 → 2.23.1

package/src/enrichers.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, it } from 'vitest';
+import { userAgent, geo, requestSize } from './enrichers';
+
+describe('enrichers', () => {
+  describe('userAgent', () => {
+    it('parses Chrome on macOS', () => {
+      const result = userAgent({
+        'user-agent':
+          'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+      });
+
+      expect(result).toMatchObject({
+        'user_agent.browser': 'Chrome 120.0.0.0',
+        'user_agent.os': 'macOS 10.15.7',
+        'user_agent.device': 'desktop',
+      });
+      expect(result?.['user_agent.raw']).toBeDefined();
+    });
+
+    it('parses Firefox on Windows', () => {
+      const result = userAgent({
+        'user-agent':
+          'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0',
+      });
+
+      expect(result).toMatchObject({
+        'user_agent.browser': 'Firefox 121.0',
+        'user_agent.os': 'Windows 10.0',
+        'user_agent.device': 'desktop',
+      });
+    });
+
+    it('detects mobile device', () => {
+      const result = userAgent({
+        'user-agent':
+          'Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Mobile/15E148 Safari/604.1',
+      });
+
+      expect(result?.['user_agent.device']).toBe('mobile');
+      expect(result?.['user_agent.os']).toBe('iOS 17.2');
+    });
+
+    it('detects bot', () => {
+      const result = userAgent({
+        'user-agent': 'Googlebot/2.1 (+http://www.google.com/bot.html)',
+      });
+
+      expect(result?.['user_agent.device']).toBe('bot');
+    });
+
+    it('returns undefined when no user-agent header', () => {
+      expect(userAgent({})).toBeUndefined();
+    });
+
+    it('accepts mixed-case User-Agent header names', () => {
+      const result = userAgent({
+        'User-Agent':
+          'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0',
+      });
+
+      expect(result).toMatchObject({
+        'user_agent.browser': 'Firefox 121.0',
+        'user_agent.os': 'Windows 10.0',
+      });
+    });
+  });
+
+  describe('geo', () => {
+    it('extracts Vercel geo headers', () => {
+      const result = geo({
+        'x-vercel-ip-country': 'US',
+        'x-vercel-ip-country-region': 'CA',
+        'x-vercel-ip-city': 'San%20Francisco',
+        'x-vercel-ip-latitude': '37.7749',
+        'x-vercel-ip-longitude': '-122.4194',
+      });
+
+      expect(result).toEqual({
+        'geo.country': 'US',
+        'geo.region': 'CA',
+        'geo.city': 'San Francisco',
+        'geo.latitude': '37.7749',
+        'geo.longitude': '-122.4194',
+      });
+    });
+
+    it('extracts Cloudflare country header', () => {
+      const result = geo({ 'cf-ipcountry': 'GB' });
+
+      expect(result).toEqual({ 'geo.country': 'GB' });
+    });
+
+    it('does not throw on malformed encoded city values', () => {
+      expect(() =>
+        geo({
+          'x-vercel-ip-country': 'US',
+          'x-vercel-ip-city': '%E0%A4%A',
+        }),
+      ).not.toThrow();
+    });
+
+    it('returns undefined when no geo headers', () => {
+      expect(geo({})).toBeUndefined();
+    });
+
+    it('returns longitude when it is the only geo signal', () => {
+      const result = geo({ 'x-vercel-ip-longitude': '-0.1276' });
+
+      expect(result).toEqual({ 'geo.longitude': '-0.1276' });
+    });
+  });
+
+  describe('requestSize', () => {
+    it('extracts request and response sizes', () => {
+      const result = requestSize(
+        { 'content-length': '1024' },
+        { 'content-length': '2048' },
+      );
+
+      expect(result).toEqual({
+        'http.request.body.size': 1024,
+        'http.response.body.size': 2048,
+      });
+    });
+
+    it('handles request-only size', () => {
+      const result = requestSize({ 'content-length': '512' });
+
+      expect(result).toEqual({ 'http.request.body.size': 512 });
+    });
+
+    it('returns undefined when no content-length headers', () => {
+      expect(requestSize({}, {})).toBeUndefined();
+    });
+
+    it('ignores non-numeric content-length', () => {
+      expect(requestSize({ 'content-length': 'abc' })).toBeUndefined();
+    });
+
+    it('ignores invalid numeric content-length values', () => {
+      expect(requestSize({ 'content-length': '-1' })).toBeUndefined();
+      expect(requestSize({ 'content-length': '12.5' })).toBeUndefined();
+    });
+
+    it('ignores non-digit numeric formats for content-length', () => {
+      expect(requestSize({ 'content-length': '1e3' })).toBeUndefined();
+      expect(requestSize({ 'content-length': '+10' })).toBeUndefined();
+    });
+  });
+});

package/src/enrichers.ts

@@ -0,0 +1,145 @@
+type Headers = Record<string, string | string[] | undefined>;
+
+function get(headers: Headers, key: string): string | undefined {
+  const lower = key.toLowerCase();
+  for (const [k, v] of Object.entries(headers)) {
+    if (k.toLowerCase() === lower) {
+      return Array.isArray(v) ? v[0] : v;
+    }
+  }
+  return undefined;
+}
+
+// --- User Agent ---
+
+export interface UserAgentAttributes {
+  'user_agent.raw': string;
+  'user_agent.browser'?: string;
+  'user_agent.os'?: string;
+  'user_agent.device'?: string;
+}
+
+const BROWSER_RE = /(Firefox|OPR|Edg|Chrome|Safari|MSIE|Trident)[\s/]?([\d.]*)/;
+const OS_RE =
+  /(Windows NT|Mac OS X|Linux|Android|iPhone OS|iPad|CrOS)[\s]?([\d._]*)/;
+
+function parseBrowser(ua: string): string | undefined {
+  const m = BROWSER_RE.exec(ua);
+  if (!m) return undefined;
+  const name =
+    m[1] === 'OPR'
+      ? 'Opera'
+      : m[1] === 'Edg'
+        ? 'Edge'
+        : m[1] === 'Trident'
+          ? 'IE'
+          : m[1];
+  return m[2] ? `${name} ${m[2]}` : name;
+}
+
+function parseOS(ua: string): string | undefined {
+  const m = OS_RE.exec(ua);
+  if (!m) return undefined;
+  const name =
+    m[1] === 'iPhone OS'
+      ? 'iOS'
+      : m[1] === 'Windows NT'
+        ? 'Windows'
+        : m[1] === 'Mac OS X'
+          ? 'macOS'
+          : m[1];
+  const ver = m[2]?.replaceAll('_', '.') || undefined;
+  return ver ? `${name} ${ver}` : name;
+}
+
+function parseDevice(ua: string): string | undefined {
+  if (/Mobi|Android.*Mobile|iPhone/.test(ua)) return 'mobile';
+  if (/iPad|Android(?!.*Mobile)|Tablet/.test(ua)) return 'tablet';
+  if (/Bot|Crawler|Spider|Lighthouse/i.test(ua)) return 'bot';
+  return 'desktop';
+}
+
+export function userAgent(headers: Headers): UserAgentAttributes | undefined {
+  const raw = get(headers, 'user-agent');
+  if (!raw) return undefined;
+
+  const attrs: UserAgentAttributes = { 'user_agent.raw': raw };
+  const browser = parseBrowser(raw);
+  if (browser) attrs['user_agent.browser'] = browser;
+  const os = parseOS(raw);
+  if (os) attrs['user_agent.os'] = os;
+  const device = parseDevice(raw);
+  if (device) attrs['user_agent.device'] = device;
+
+  return attrs;
+}
+
+// --- Geo ---
+
+export interface GeoAttributes {
+  'geo.country'?: string;
+  'geo.region'?: string;
+  'geo.city'?: string;
+  'geo.latitude'?: string;
+  'geo.longitude'?: string;
+}
+
+export function geo(headers: Headers): GeoAttributes | undefined {
+  const country =
+    get(headers, 'x-vercel-ip-country') ?? get(headers, 'cf-ipcountry');
+  const region = get(headers, 'x-vercel-ip-country-region');
+  const city = get(headers, 'x-vercel-ip-city');
+  const latitude = get(headers, 'x-vercel-ip-latitude');
+  const longitude = get(headers, 'x-vercel-ip-longitude');
+
+  if (!country && !region && !city && !latitude && !longitude) return undefined;
+
+  const attrs: GeoAttributes = {};
+  if (country) attrs['geo.country'] = country;
+  if (region) attrs['geo.region'] = region;
+  if (city) {
+    try {
+      attrs['geo.city'] = decodeURIComponent(city);
+    } catch {
+      attrs['geo.city'] = city;
+    }
+  }
+  if (latitude) attrs['geo.latitude'] = latitude;
+  if (longitude) attrs['geo.longitude'] = longitude;
+
+  return attrs;
+}
+
+// --- Request Size ---
+
+export interface RequestSizeAttributes {
+  'http.request.body.size'?: number;
+  'http.response.body.size'?: number;
+}
+
+const DIGITS_RE = /^\d+$/;
+
+function parseContentLength(value: string | undefined): number | undefined {
+  if (!value || !DIGITS_RE.test(value)) return undefined;
+  return Number(value);
+}
+
+export function requestSize(
+  requestHeaders: Headers,
+  responseHeaders?: Headers,
+): RequestSizeAttributes | undefined {
+  const reqLen = get(requestHeaders, 'content-length');
+  const resLen = responseHeaders
+    ? get(responseHeaders, 'content-length')
+    : undefined;
+
+  if (!reqLen && !resLen) return undefined;
+
+  const attrs: RequestSizeAttributes = {};
+  const reqBytes = parseContentLength(reqLen);
+  if (reqBytes !== undefined) attrs['http.request.body.size'] = reqBytes;
+  const resBytes = parseContentLength(resLen);
+  if (resBytes !== undefined) attrs['http.response.body.size'] = resBytes;
+
+  return Object.keys(attrs).length > 0 ? attrs : undefined;
+}

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,40 @@ export {
 // Graceful shutdown
 export { flush, shutdown } from './shutdown';
 
+// Request logger
+export {
+  getRequestLogger,
+  runWithRequestContext,
+  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));
   }

package/src/package-manifest.test.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = resolve(here, '../package.json');
+
+interface PackageJson {
+  bin?: Record<string, string>;
+  dependencies?: Record<string, string>;
+}
+
+describe('package manifest', () => {
+  it('declares runtime deps required by published bin scripts', () => {
+    const pkg = JSON.parse(
+      readFileSync(packageJsonPath, 'utf8'),
+    ) as PackageJson;
+
+    if (pkg.bin?.intent) {
+      expect(pkg.dependencies?.['@tanstack/intent']).toBeDefined();
+    }
+  });
+});