autotel 2.26.0 → 2.26.1

package/src/attribute-redacting-processor.ts

@@ -46,6 +46,11 @@ export type AttributeRedactorFn = (
  */
 export type AttributeRedactorPreset = 'default' | 'strict' | 'pci-dss';
 
+/**
+ * Masker function type - receives the matched string and returns a masked version
+ */
+export type MaskFn = (match: string) => string;
+
 /**
  * Value pattern configuration
  */
@@ -56,8 +61,15 @@ export interface ValuePatternConfig {
   pattern: RegExp;
   /** Custom replacement (default: uses global replacement) */
   replacement?: string;
+  /** Mask function for smart partial masking (overrides replacement) */
+  mask?: MaskFn;
 }
 
+/**
+ * Built-in PII pattern names
+ */
+export type BuiltinPatternName = keyof typeof builtinPatterns;
+
 /**
  * Attribute redactor configuration
  */
@@ -68,6 +80,15 @@ export interface AttributeRedactorConfig {
   /** Patterns to match against attribute values (redacts matched portion) */
   valuePatterns?: ValuePatternConfig[];
 
+  /** Dot-notation paths to redact (e.g. 'user.password', 'payment.card') */
+  paths?: string[];
+
+  /** Built-in PII patterns to enable. `true` enables all, `false` disables all, array selects specific ones. */
+  builtins?: boolean | BuiltinPatternName[];
+
+  /** Custom RegExp patterns for string-level redaction */
+  patterns?: RegExp[];
+
   /** Default replacement string (default: '[REDACTED]') */
   replacement?: string;
 
@@ -100,14 +121,112 @@ export const REDACTOR_PATTERNS = {
     /^(password|passwd|pwd|secret|token|api[_-]?key|auth|credential|private[_-]?key|authorization)$/i,
 } as const;
 
+/**
+ * Built-in PII detection patterns with smart masking.
+ * Each builtin preserves just enough signal for debugging while scrubbing PII.
+ */
+export const builtinPatterns = {
+  /** Credit card numbers → ****1111 (PCI DSS: last 4 allowed) */
+  creditCard: {
+    pattern: /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/g,
+    mask: (m: string) => `****${m.replace(/[\s-]/g, '').slice(-4)}`,
+  },
+  /** Email addresses → a***@***.com */
+  email: {
+    pattern: /[\w.+-]+@[\w-]+\.[\w.]+/g,
+    mask: (m: string) => {
+      const at = m.indexOf('@');
+      if (at < 1) return '***@***';
+      const tld = m.slice(m.lastIndexOf('.'));
+      return `${m[0]}***@***${tld}`;
+    },
+  },
+  /** IPv4 addresses → ***.***.***.100 (last octet only) */
+  ipv4: {
+    pattern:
+      /\b(?!0\.0\.0\.0\b)(?!127\.0\.0\.1\b)\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/g,
+    mask: (m: string) => `***.***.***.${m.split('.').pop()}`,
+  },
+  /** International phone numbers → +33******78 (country code + last 2 digits) */
+  phone: {
+    pattern:
+      /(?:\+\d{1,3}[\s.-]?)?\(?\d{1,4}\)?[\s.-]?\d{2,4}[\s.-]?\d{2,4}[\s.-]?\d{2,4}\b/g,
+    mask: (m: string) => {
+      const digits = m.replace(/[^\d]/g, '');
+      const hasPlus = m.startsWith('+');
+      if (hasPlus && digits.length > 4) {
+        const ccMatch = m.match(/^\+\d{1,3}/);
+        const cc = ccMatch ? ccMatch[0] : '+';
+        return `${cc}******${digits.slice(-2)}`;
+      }
+      if (digits.length > 2) {
+        return `${'*'.repeat(digits.length - 2)}${digits.slice(-2)}`;
+      }
+      return '***';
+    },
+  },
+  /** JWT tokens → eyJ***.*** */
+  jwt: {
+    pattern: /\beyJ[\w-]*\.[\w-]*\.[\w-]*\b/g,
+    mask: () => 'eyJ***.***',
+  },
+  /** Bearer tokens → Bearer *** */
+  bearer: {
+    pattern: /\bBearer\s+[\w\-.~+/]{8,}=*/gi,
+    mask: () => 'Bearer ***',
+  },
+  /** IBAN → FR76****189 (country + check digits + last 3) */
+  iban: {
+    pattern:
+      /\b[A-Z]{2}\d{2}[\s-]?[\dA-Z]{4}[\s-]?[\dA-Z]{4}[\s-]?[\dA-Z]{4}[\s-]?[\dA-Z]{0,4}[\s-]?[\dA-Z]{0,4}[\s-]?[\dA-Z]{0,4}\b/g,
+    mask: (m: string) => {
+      const clean = m.replace(/[\s-]/g, '');
+      return `${clean.slice(0, 4)}****${clean.slice(-3)}`;
+    },
+  },
+} as const;
+
+function cloneRegex(re: RegExp): RegExp {
+  return new RegExp(re.source, re.flags);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function toRegExp(value: unknown): RegExp | undefined {
+  if (value instanceof RegExp) return value;
+  if (typeof value === 'string') return new RegExp(value, 'g');
+  if (isPlainObject(value) && typeof value.source === 'string') {
+    const flags = typeof value.flags === 'string' ? value.flags : 'g';
+    return new RegExp(value.source, flags);
+  }
+  return undefined;
+}
+
+function toRegExpArray(value: unknown): RegExp[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out: RegExp[] = [];
+  for (const item of value) {
+    const re = toRegExp(item);
+    if (re) out.push(re);
+  }
+  return out.length > 0 ? out : [];
+}
+
+function builtinToValuePattern(name: BuiltinPatternName): ValuePatternConfig {
+  const b = builtinPatterns[name];
+  return { name, pattern: cloneRegex(b.pattern), mask: b.mask };
+}
+
 /**
  * Default value patterns for the 'default' preset
  */
 const DEFAULT_VALUE_PATTERNS: ValuePatternConfig[] = [
-  { name: 'email', pattern: REDACTOR_PATTERNS.email },
-  { name: 'phone', pattern: REDACTOR_PATTERNS.phone },
+  builtinToValuePattern('email'),
+  builtinToValuePattern('phone'),
   { name: 'ssn', pattern: REDACTOR_PATTERNS.ssn },
-  { name: 'creditCard', pattern: REDACTOR_PATTERNS.creditCard },
+  builtinToValuePattern('creditCard'),
 ];
 
 /**
@@ -118,61 +237,158 @@ export const REDACTOR_PRESETS: Record<
   AttributeRedactorConfig
 > = {
   /**
-   * Default preset - covers common PII patterns
-   * Detects: emails, phone numbers, SSNs, credit cards
+   * Default preset - covers common PII patterns with smart masking
+   * Detects: emails (a***@***.com), phone numbers, SSNs, credit cards (****1111)
    * Redacts keys: password, secret, token, apiKey, auth, credential
    */
   default: {
     keyPatterns: [REDACTOR_PATTERNS.sensitiveKey],
     valuePatterns: DEFAULT_VALUE_PATTERNS,
+    builtins: true,
     replacement: '[REDACTED]',
   },
 
   /**
    * Strict preset - more aggressive redaction for high-security environments
-   * Includes everything in default plus: Bearer tokens, JWTs, API keys in values
+   * Includes everything in default plus: Bearer tokens, JWTs, IBAN, API keys in values
    */
   strict: {
     keyPatterns: [REDACTOR_PATTERNS.sensitiveKey, /bearer/i, /jwt/i],
     valuePatterns: [
       ...DEFAULT_VALUE_PATTERNS,
-      { name: 'bearerToken', pattern: REDACTOR_PATTERNS.bearerToken },
+      builtinToValuePattern('jwt'),
+      builtinToValuePattern('bearer'),
+      builtinToValuePattern('iban'),
       { name: 'apiKeyInValue', pattern: REDACTOR_PATTERNS.apiKeyInValue },
-      { name: 'jwt', pattern: REDACTOR_PATTERNS.jwt },
     ],
+    builtins: true,
     replacement: '[REDACTED]',
   },
 
   /**
    * PCI-DSS preset - focused on payment card industry compliance
-   * Redacts: credit card numbers, CVV-like patterns, card-related keys
+   * Redacts: credit card numbers (****1111), CVV-like patterns, card-related keys
    */
   'pci-dss': {
     keyPatterns: [/card/i, /cvv/i, /cvc/i, /pan/i, /expir/i, /ccn/i],
-    valuePatterns: [
-      { name: 'creditCard', pattern: REDACTOR_PATTERNS.creditCard },
-    ],
+    valuePatterns: [builtinToValuePattern('creditCard')],
+    builtins: ['creditCard'],
     replacement: '[REDACTED]',
   },
 };
 
+/**
+ * Normalize redactor config that may have been deserialized from JSON/YAML.
+ * Converts regex-like values back to RegExp instances.
+ */
+export function normalizeAttributeRedactorConfig(
+  raw: AttributeRedactorConfig | AttributeRedactorPreset | unknown,
+): AttributeRedactorConfig | AttributeRedactorPreset | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (typeof raw === 'string') return raw as AttributeRedactorPreset;
+  if (!isPlainObject(raw)) return undefined;
+
+  const config: AttributeRedactorConfig = {};
+
+  if (Array.isArray(raw.paths)) {
+    config.paths = raw.paths.filter(
+      (value): value is string => typeof value === 'string',
+    );
+  }
+
+  if (typeof raw.replacement === 'string') {
+    config.replacement = raw.replacement;
+  }
+
+  if (typeof raw.builtins === 'boolean') {
+    config.builtins = raw.builtins;
+  } else if (Array.isArray(raw.builtins)) {
+    config.builtins = raw.builtins.filter(
+      (name): name is BuiltinPatternName => typeof name === 'string',
+    );
+  }
+
+  if (typeof raw.redactor === 'function') {
+    config.redactor = raw.redactor as AttributeRedactorFn;
+  }
+
+  const keyPatterns = toRegExpArray(raw.keyPatterns);
+  if (keyPatterns) config.keyPatterns = keyPatterns;
+
+  const patterns = toRegExpArray(raw.patterns);
+  if (patterns) config.patterns = patterns;
+
+  if (Array.isArray(raw.valuePatterns)) {
+    const valuePatterns: ValuePatternConfig[] = [];
+    for (const item of raw.valuePatterns) {
+      if (!isPlainObject(item) || typeof item.name !== 'string') continue;
+      const pattern = toRegExp(item.pattern);
+      if (!pattern) continue;
+      valuePatterns.push({
+        name: item.name,
+        pattern,
+        replacement:
+          typeof item.replacement === 'string' ? item.replacement : undefined,
+        mask:
+          typeof item.mask === 'function' ? (item.mask as MaskFn) : undefined,
+      });
+    }
+    config.valuePatterns = valuePatterns;
+  }
+
+  return config;
+}
+
 /**
  * Resolve config to a normalized form
  */
 function resolveConfig(
   config: AttributeRedactorConfig | AttributeRedactorPreset,
 ): AttributeRedactorConfig {
-  if (typeof config === 'string') {
-    const preset = REDACTOR_PRESETS[config];
+  const normalized = normalizeAttributeRedactorConfig(config);
+  if (!normalized) {
+    throw new Error('Invalid attribute redactor config');
+  }
+
+  if (typeof normalized === 'string') {
+    const preset = REDACTOR_PRESETS[normalized];
     if (!preset) {
       throw new Error(
-        `Unknown attribute redactor preset: "${config}". ` +
+        `Unknown attribute redactor preset: "${normalized}". ` +
           `Available presets: ${Object.keys(REDACTOR_PRESETS).join(', ')}`,
       );
     }
     return preset;
   }
-  return config;
+
+  const resolvedConfig: AttributeRedactorConfig = {
+    ...normalized,
+    keyPatterns: normalized.keyPatterns
+      ? [...normalized.keyPatterns]
+      : undefined,
+    valuePatterns: normalized.valuePatterns
+      ? [...normalized.valuePatterns]
+      : undefined,
+    paths: normalized.paths ? [...normalized.paths] : undefined,
+    patterns: normalized.patterns ? [...normalized.patterns] : undefined,
+  };
+
+  // Merge built-in patterns if enabled
+  if (resolvedConfig.builtins !== false) {
+    const builtinNames = Array.isArray(resolvedConfig.builtins)
+      ? resolvedConfig.builtins
+      : (Object.keys(builtinPatterns) as BuiltinPatternName[]);
+    const builtinValuePatterns = builtinNames
+      .filter((name) => name in builtinPatterns)
+      .map(builtinToValuePattern);
+
+    resolvedConfig.valuePatterns = [
+      ...(resolvedConfig.valuePatterns ?? []),
+      ...builtinValuePatterns,
+    ];
+  }
+
+  return resolvedConfig;
 }
 
 /**
@@ -188,27 +404,40 @@ function createRedactorFromConfig(
 
   const keyPatterns = config.keyPatterns ?? [];
   const valuePatterns = config.valuePatterns ?? [];
+  const paths = config.paths ?? [];
+  const pathSet = new Set(paths);
+  const customPatterns = config.patterns ?? [];
   const defaultReplacement = config.replacement ?? '[REDACTED]';
 
+  // Build masker list from valuePatterns that have mask functions
+  const maskers: [RegExp, MaskFn][] = valuePatterns
+    .filter((vp) => vp.mask)
+    .map((vp) => [cloneRegex(vp.pattern), vp.mask!]);
+
   return (key: string, value: AttributeValue): AttributeValue => {
     // Check if key matches any sensitive key pattern
     for (const pattern of keyPatterns) {
-      // Reset lastIndex for global regexes
       pattern.lastIndex = 0;
       if (pattern.test(key)) {
         return defaultReplacement;
       }
     }
 
-    // For non-string values, return as-is (can't pattern match)
+    // Check if key matches any path-based redaction
+    if (pathSet.has(key)) {
+      return defaultReplacement;
+    }
+
+    // For non-string values, return as-is
     if (typeof value !== 'string') {
-      // Handle arrays of strings
       if (Array.isArray(value)) {
         return value.map((item) => {
           if (typeof item === 'string') {
             return redactStringValue(
               item,
               valuePatterns,
+              maskers,
+              customPatterns,
               defaultReplacement,
             ) as string;
           }
@@ -218,25 +447,50 @@ function createRedactorFromConfig(
       return value;
     }
 
-    // Apply value patterns to string values
-    return redactStringValue(value, valuePatterns, defaultReplacement);
+    // Three-tier strategy: path-based → masker-based → pattern-based
+    return redactStringValue(
+      value,
+      valuePatterns,
+      maskers,
+      customPatterns,
+      defaultReplacement,
+    );
   };
 }
 
 /**
- * Apply value patterns to a string
+ * Apply three-tier redaction strategy to a string
+ * 1. Masker-based: built-in patterns with smart partial masking
+ * 2. Pattern-based: custom RegExp patterns replaced with replacement
  */
 function redactStringValue(
   value: string,
   patterns: ValuePatternConfig[],
+  maskers: [RegExp, MaskFn][],
+  customPatterns: RegExp[],
   defaultReplacement: string,
 ): string {
   let result = value;
-  for (const { pattern, replacement } of patterns) {
-    // Reset lastIndex for global regexes
+
+  // Tier 1: Apply maskers (smart partial masking)
+  for (const [pattern, mask] of maskers) {
+    pattern.lastIndex = 0;
+    result = result.replace(pattern, mask);
+  }
+
+  // Tier 2: Apply value patterns without mask (full replacement)
+  for (const { pattern, replacement, mask } of patterns) {
+    if (mask) continue; // Already handled by maskers
     pattern.lastIndex = 0;
     result = result.replaceAll(pattern, replacement ?? defaultReplacement);
   }
+
+  // Tier 3: Apply custom patterns
+  for (const pattern of customPatterns) {
+    pattern.lastIndex = 0;
+    result = result.replaceAll(pattern, defaultReplacement);
+  }
+
   return result;
 }
 

package/src/autotel-logger.ts

@@ -232,7 +232,7 @@ export function createBuiltinLogger(
           log(level, extraOrMessage, message as Record<string, unknown>);
         } else {
           // Pure string-only call: logger.info('message')
-          log(level, extraOrMessage, undefined);
+          log(level, extraOrMessage);
         }
       } else {
         // Pino style: logger.info({ extra }, 'message')
@@ -303,7 +303,7 @@ export function createBuiltinLogger(
         }
 
         // Pure string-only call: logger.error('message')
-        log('error', extraOrMessage, undefined);
+        log('error', extraOrMessage);
         return;
       }
 

package/src/index.ts

@@ -29,7 +29,7 @@
  */
 
 // Core initialization
-export { init, type AutotelConfig } from './init';
+export { init, lockLogger, isLoggerLocked, type AutotelConfig } from './init';
 
 // Baggage span processor
 export {
@@ -126,6 +126,7 @@ export {
 // Structured errors
 export {
   createStructuredError,
+  structuredErrorToJSON,
   getStructuredErrorAttributes,
   recordStructuredError,
   type StructuredError,

package/src/init.ts

@@ -60,6 +60,7 @@ import {
 } from './span-name-normalizer';
 import {
   AttributeRedactingProcessor,
+  normalizeAttributeRedactorConfig,
   type AttributeRedactorConfig,
   type AttributeRedactorPreset,
 } from './attribute-redacting-processor';
@@ -1142,10 +1143,28 @@ export interface AutotelConfig {
      */
     pretty?: boolean;
   };
+
+  /**
+   * Suppress console output while keeping OTel exporters running.
+   * Useful for platforms like GCP Cloud Run / AWS Lambda where stdout
+   * is managed externally by the platform's log collector.
+   *
+   * @default false
+   */
+  silent?: boolean;
+
+  /**
+   * Minimum log level for internal autotel diagnostic messages.
+   * Messages below this level are dropped before processing.
+   *
+   * @default 'info'
+   */
+  minLevel?: 'debug' | 'info' | 'warn' | 'error';
 }
 
 // Internal state
 let initialized = false;
+let locked = false;
 let config: AutotelConfig | null = null;
 let sdk: NodeSDK | null = null;
 let warnedOnce = false;
@@ -1156,6 +1175,85 @@ let _stringRedactor: StringRedactor | null = null;
 let _optionalRequire: typeof safeRequire = safeRequire;
 let _devtoolsClose: (() => Promise<void> | void) | null = null;
 
+const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3 } as const;
+type LogLevelKey = keyof typeof LOG_LEVELS;
+
+/**
+ * Lock the logger to prevent further `init()` calls.
+ * Use this when framework plugins set up instrumentation and you want
+ * to prevent accidental re-initialization from user code.
+ */
+export function lockLogger(): void {
+  locked = true;
+}
+
+/**
+ * Check if the logger has been locked.
+ */
+export function isLoggerLocked(): boolean {
+  return locked;
+}
+
+function createSilentLogger(): Logger {
+  return {
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+  };
+}
+
+function wrapLogger(
+  base: Logger,
+  silent: boolean,
+  minLevel: LogLevelKey,
+): Logger {
+  if (silent) return createSilentLogger();
+  const threshold = LOG_LEVELS[minLevel];
+  const wrap = (fn: Logger['info'], level: LogLevelKey): Logger['info'] => {
+    if (LOG_LEVELS[level] < threshold) {
+      return (() => {}) as Logger['info'];
+    }
+    return ((...args: Parameters<Logger['info']>) =>
+      fn(...args)) as Logger['info'];
+  };
+  return {
+    debug: wrap(base.debug, 'debug'),
+    info: wrap(base.info, 'info'),
+    warn: wrap(base.warn, 'warn'),
+    error: wrap(base.error, 'error'),
+  };
+}
+
+function detectEnvironmentAttributes(): Record<string, string> {
+  const attrs: Record<string, string> = {};
+
+  const commitSha =
+    process.env.COMMIT_SHA ||
+    process.env.GITHUB_SHA ||
+    process.env.VERCEL_GIT_COMMIT_SHA ||
+    process.env.CF_PAGES_COMMIT_SHA ||
+    process.env.AWS_CODEPIPELINE_EXECUTION_ID;
+  if (commitSha) attrs['service.commit.sha'] = commitSha;
+
+  const region =
+    process.env.VERCEL_REGION ||
+    process.env.AWS_REGION ||
+    process.env.AWS_DEFAULT_REGION ||
+    process.env.FLY_REGION ||
+    process.env.CF_REGION ||
+    process.env.GOOGLE_CLOUD_REGION;
+  if (region) attrs['service.region'] = region;
+
+  const version =
+    process.env.APP_VERSION ||
+    process.env.HEROKU_RELEASE_VERSION ||
+    process.env.VERCEL_GIT_COMMIT_REF;
+  if (version) attrs['service.deploy.version'] = version;
+
+  return attrs;
+}
+
 /**
  * Resolve metrics flag with env var override support
  */
@@ -1295,6 +1393,10 @@ function normalizeOtlpHeaders(
  */
 
 export function init(cfg: AutotelConfig): void {
+  if (locked) {
+    return;
+  }
+
   // Resolve configs in priority order: explicit > yaml > env > defaults
   const envConfig = resolveConfigFromEnv();
   const yamlConfig = loadYamlConfig() ?? {};
@@ -1308,19 +1410,32 @@ export function init(cfg: AutotelConfig): void {
     resourceAttributes: {
       ...envConfig.resourceAttributes,
       ...yamlConfig.resourceAttributes,
+      ...detectEnvironmentAttributes(),
       ...cfg.resourceAttributes,
     },
     // Handle headers merge (can be string or object)
     headers: cfg.headers ?? yamlConfig.headers ?? envConfig.headers,
   } as AutotelConfig;
 
+  if (mergedConfig.attributeRedactor !== undefined) {
+    const normalizedRedactor = normalizeAttributeRedactorConfig(
+      mergedConfig.attributeRedactor,
+    );
+    if (!normalizedRedactor) {
+      throw new Error('Invalid attributeRedactor config');
+    }
+    mergedConfig.attributeRedactor = normalizedRedactor;
+  }
+
   const devtoolsConfig = resolveDevtoolsConfig(mergedConfig.devtools);
   if (devtoolsConfig.enabled && mergedConfig.logs === undefined) {
     mergedConfig.logs = true;
   }
 
-  // Set logger (use provided or default to silent - no spam)
-  logger = mergedConfig.logger || silentLogger;
+  const silent = mergedConfig.silent ?? false;
+  const minLevel = mergedConfig.minLevel ?? 'info';
+  const baseLogger = mergedConfig.logger || silentLogger;
+  logger = wrapLogger(baseLogger, silent, minLevel);
 
   // Warn if re-initializing (same behavior in all environments)
   if (initialized) {