@provide-io/telemetry 0.2.2

package/src/index.ts

@@ -0,0 +1,183 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @provide-io/telemetry — TypeScript structured logging + OTEL
+ *
+ * Feature parity with the Python provide.telemetry package.
+ *
+ * Quick start:
+ *   import { setupTelemetry, getLogger, bindContext } from '@provide-io/telemetry';
+ *
+ *   setupTelemetry({ serviceName: 'my-app', logLevel: 'debug' });
+ *   const log = getLogger('api');
+ *   log.info({ event: 'request_ok', method: 'GET', path: '/api/v1/users', status: 200 });
+ */
+
+// Config + setup
+export {
+  setupTelemetry,
+  applyConfigPolicies,
+  getConfig,
+  configFromEnv,
+  parseOtlpHeaders,
+  redactConfig,
+  version,
+  __version__,
+} from './config';
+export type { TelemetryConfig, RuntimeOverrides } from './config';
+
+// Logger
+export { getLogger, logger } from './logger';
+export type { Logger } from './logger';
+
+// Context binding (mirrors Python bind_context / unbind_context / clear_context)
+export {
+  bindContext,
+  unbindContext,
+  clearContext,
+  getContext,
+  runWithContext,
+  bindSessionContext,
+  getSessionId,
+  clearSessionContext,
+} from './context';
+
+// Error fingerprinting (mirrors Python add_error_fingerprint processor)
+export { computeErrorFingerprint } from './fingerprint';
+
+// Pretty ANSI renderer (mirrors Python PrettyRenderer)
+export { formatPretty, supportsColor } from './pretty';
+
+// Metrics (mirrors Python counter / gauge / histogram)
+export {
+  counter,
+  gauge,
+  histogram,
+  getMeter,
+  CounterInstrument,
+  GaugeInstrument,
+  HistogramInstrument,
+} from './metrics';
+export type { Counter, Histogram, Meter, MetricOptions, UpDownCounter } from './metrics';
+
+// Tracing (mirrors Python @trace decorator)
+export {
+  withTrace,
+  traceDecorator as trace,
+  getActiveTraceIds,
+  getTracer,
+  tracer,
+  setTraceContext,
+  getTraceContext,
+} from './tracing';
+
+// Optional OTEL SDK wiring (call after setupTelemetry to activate exporters)
+export { registerOtelProviders } from './otel';
+
+// PII sanitization utilities
+export {
+  sanitize,
+  DEFAULT_SANITIZE_FIELDS,
+  sanitizePayload,
+  registerPiiRule,
+  getPiiRules,
+  replacePiiRules,
+  resetPiiRulesForTests,
+} from './pii';
+export type { MaskMode, PIIRule, SanitizePayloadOptions } from './pii';
+
+// Exceptions
+export { TelemetryError, ConfigurationError } from './exceptions';
+
+// Health
+export { getHealthSnapshot, setSetupError } from './health';
+export type { HealthSnapshot } from './health';
+
+// Backpressure
+export { setQueuePolicy, getQueuePolicy, tryAcquire, release } from './backpressure';
+export type { QueuePolicy, QueueTicket } from './backpressure';
+
+// Cardinality
+export {
+  OVERFLOW_VALUE,
+  registerCardinalityLimit,
+  getCardinalityLimits,
+  clearCardinalityLimits,
+  guardAttributes,
+} from './cardinality';
+export type { CardinalityLimit } from './cardinality';
+
+// Sampling
+export { setSamplingPolicy, getSamplingPolicy, shouldSample } from './sampling';
+export type { SamplingPolicy } from './sampling';
+
+// Resilience
+export {
+  setExporterPolicy,
+  getExporterPolicy,
+  runWithResilience,
+  getCircuitState,
+  TelemetryTimeoutError,
+} from './resilience';
+export type { ExporterPolicy, CircuitState } from './resilience';
+
+// Schema
+export {
+  EventSchemaError,
+  event,
+  eventName,
+  validateEventName,
+  validateRequiredKeys,
+} from './schema';
+export type { EventRecord } from './schema';
+
+// SLO
+export { recordRedMetrics, recordUseMetrics, classifyError } from './slo';
+export type { ErrorClassification } from './slo';
+
+// Propagation
+export {
+  extractW3cContext,
+  bindPropagationContext,
+  clearPropagationContext,
+  getActivePropagationContext,
+} from './propagation';
+export type { PropagationContext } from './propagation';
+
+// Runtime reconfiguration
+export {
+  getRuntimeConfig,
+  updateRuntimeConfig,
+  reloadRuntimeFromEnv,
+  reconfigureTelemetry,
+} from './runtime';
+
+// Test utilities
+export { resetTelemetryState, resetTraceContext, telemetryTestPlugin } from './testing';
+
+// Optional governance module — strippable: consent
+export type { ConsentLevel } from './consent';
+export {
+  setConsentLevel,
+  getConsentLevel,
+  shouldAllow,
+  loadConsentFromEnv,
+  resetConsentForTests,
+} from './consent';
+
+// Optional governance module — strippable
+export type { DataClass, ClassificationRule, ClassificationPolicy } from './classification';
+export {
+  registerClassificationRules,
+  setClassificationPolicy,
+  getClassificationPolicy,
+  resetClassificationForTests,
+} from './classification';
+
+// Optional governance module — strippable: receipts
+export type { RedactionReceipt } from './receipts';
+export { enableReceipts, getEmittedReceiptsForTests, resetReceiptsForTests } from './receipts';
+
+// Shutdown
+export { shutdownTelemetry } from './shutdown';

package/src/logger.ts

@@ -0,0 +1,287 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Structured logger — wraps pino with:
+ *   - browser.write hook in actual browsers; custom stream in Node.js/Vitest
+ *   - window.__pinoLogs capture for Playwright/devtools inspection
+ *   - Automatic context binding (from bindContext())
+ *   - Automatic OTEL trace_id/span_id injection
+ *   - PII sanitization
+ *   - msg fallback: if msg is empty, defaults to obj.event
+ *
+ * Mirrors Python provide.telemetry get_logger().
+ */
+
+import pino from 'pino';
+import { getConfig } from './config';
+import { getContext } from './context';
+import { computeErrorFingerprint } from './fingerprint';
+import { formatPretty, supportsColor } from './pretty';
+import { emitLogRecord } from './otel-logs';
+import { sanitizePayload } from './pii';
+import { sanitize } from './sanitize';
+import { EventSchemaError, validateEventName, validateRequiredKeys } from './schema';
+import { getActiveTraceIds } from './tracing';
+
+/** Pino level number → console method name. */
+const LEVEL_MAP: Record<number, string> = {
+  10: 'trace',
+  20: 'debug',
+  30: 'log',
+  40: 'warn',
+  50: 'error',
+  60: 'error',
+};
+
+/** Public Logger interface — consumers should type against this, not pino.Logger. */
+export interface Logger {
+  trace(obj: Record<string, unknown>, msg?: string): void;
+  debug(obj: Record<string, unknown>, msg?: string): void;
+  info(obj: Record<string, unknown>, msg?: string): void;
+  warn(obj: Record<string, unknown>, msg?: string): void;
+  error(obj: Record<string, unknown>, msg?: string): void;
+  /** Create a child logger with additional bound fields. */
+  child(bindings: Record<string, unknown>): Logger;
+}
+
+// Pino root instance — lazily created so config is read after setupTelemetry().
+let _root: pino.Logger | null = null;
+
+/**
+ * Build the write hook that enriches, sanitizes, captures, and optionally
+ * emits each log record.  Config is read dynamically on every invocation so
+ * that resetTelemetryState() + setupTelemetry() changes take effect without
+ * needing to rebuild the hook closure.
+ */
+export function makeWriteHook() {
+  // pino's WriteFn signature uses `object`; we cast internally for safe property access.
+  return (obj: object): void => {
+    // Read config dynamically — avoids stale-capture bug after _resetConfig().
+    const cfg = getConfig();
+    const o = obj as Record<string, unknown>;
+
+    // Inject OTEL trace/span IDs if an active span exists.
+    const ids = getActiveTraceIds();
+    if (ids.trace_id) o['trace_id'] = ids.trace_id;
+    if (ids.span_id) o['span_id'] = ids.span_id;
+
+    // Merge module-level context bindings.
+    Object.assign(o, getContext());
+
+    // Ensure msg is always non-empty — pino sets msg='' when no string arg is passed.
+    if (!o['msg']) o['msg'] = o['event'] ?? '';
+
+    // Caller info injection — intentionally expensive (creates Error per call).
+    // Stryker disable all
+    if (cfg.logIncludeCaller) {
+      const err = new Error();
+      const stack = err.stack?.split('\n');
+      /* v8 ignore next -- stack is always defined in V8 */
+      if (stack) {
+        for (const frame of stack.slice(1)) {
+          if (
+            !frame.includes('logger.ts') &&
+            !frame.includes('node_modules') &&
+            !frame.includes('pino')
+          ) {
+            const match = frame.match(/\((.+):(\d+):\d+\)/) ?? frame.match(/at (.+):(\d+):\d+/);
+            /* v8 ignore next -- match always succeeds for V8 stack frames */
+            if (match) {
+              o['caller_file'] = match[1].replace(/^.*\//, ''); // basename only
+              o['caller_line'] = Number(match[2]);
+            }
+            break;
+          }
+        }
+      }
+    }
+    // Stryker enable all
+
+    // Error fingerprinting — stable hash from error name + stack.
+    const errObj = o['err'] as Record<string, unknown> | undefined;
+    const excName = (o['exc_name'] ?? o['exception'] ?? errObj?.['type'] ?? errObj?.['name']) as
+      | string
+      | undefined;
+    if (excName) {
+      const stack = (errObj?.['stack'] ?? o['stack']) as string | undefined;
+      o['error_fingerprint'] = computeErrorFingerprint(String(excName), stack);
+    }
+
+    // PII sanitization: blocked keys + secret detection + custom PII rules.
+    if (cfg.logSanitize) {
+      sanitize(o, cfg.sanitizeFields);
+      sanitizePayload(o, [], { maxDepth: cfg.piiMaxDepth });
+    }
+
+    // Strip timestamp when configured off.
+    if (!cfg.logIncludeTimestamp) {
+      delete o['time'];
+    }
+
+    // Schema validation — drop records that violate strict schema rules.
+    /* v8 ignore next -- V8 cannot fully attribute all ?? branches in a single expression */
+    if (cfg.strictSchema) {
+      const event = String(o['event'] ?? o['msg'] ?? '');
+      if (event) {
+        try {
+          validateEventName(event);
+        } catch (e) {
+          if (e instanceof EventSchemaError) return;
+          throw e;
+        }
+      }
+      if (cfg.requiredLogKeys.length > 0) {
+        try {
+          validateRequiredKeys(o, cfg.requiredLogKeys);
+        } catch (e) {
+          if (e instanceof EventSchemaError) return;
+          throw e;
+        }
+      }
+    }
+
+    // Export to OTLP when a log provider is registered (noop otherwise).
+    emitLogRecord(o);
+
+    // Capture to window.__pinoLogs for Playwright and devtools inspection.
+    // Check is done inline (not at module load) so it works when loaded in Node.js
+    // test environments that later gain a jsdom window.
+    if (typeof window !== 'undefined' && cfg.captureToWindow) {
+      if (!('__pinoLogs' in window)) {
+        (window as unknown as Record<string, unknown>)['__pinoLogs'] = [];
+      }
+      (window as unknown as Record<string, unknown[]>)['__pinoLogs'].push(o);
+    }
+
+    // Emit to console only when explicitly enabled (opt-in).
+    if (cfg.consoleOutput) {
+      const method = LEVEL_MAP[o['level'] as number] ?? 'log';
+      if (cfg.logFormat === 'pretty') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (console as any)[method](formatPretty(o, supportsColor()));
+      } else {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (console as any)[method](o);
+      }
+    }
+  };
+}
+
+function getRootLogger(): pino.Logger {
+  // Stryker disable next-line ConditionalExpression
+  if (_root) return _root;
+  const cfg = getConfig();
+  const hook = makeWriteHook();
+
+  // pino only invokes browser.write when process.version is absent (real browser).
+  // In Node.js / Vitest, we use a custom destination stream that forwards every
+  // serialised log line back through the write hook.
+  // Stryker disable all
+  const isNodeEnv = typeof process !== 'undefined' && typeof process.version === 'string';
+
+  /* c8 ignore else */
+  if (isNodeEnv) {
+    const stream = {
+      write(msg: string) {
+        try {
+          hook(JSON.parse(msg.trimEnd()) as object);
+        } catch {
+          // Ignore malformed lines (e.g. pino flush sentinels).
+        }
+      },
+    };
+    _root = pino(
+      {
+        base: { service: cfg.serviceName, env: cfg.environment, version: cfg.version },
+        level: cfg.logLevel,
+      },
+      stream as unknown as pino.DestinationStream,
+    );
+  } else {
+    /* c8 ignore next 8 */
+    _root = pino({
+      base: { service: cfg.serviceName, env: cfg.environment, version: cfg.version },
+      level: cfg.logLevel,
+      browser: {
+        write: hook,
+      },
+    });
+  }
+  // Stryker enable all
+  return _root;
+}
+
+function adaptPino(pinoLogger: pino.Logger): Logger {
+  // Stryker disable all
+  return {
+    trace: (obj, msg) => pinoLogger.trace(obj, msg ?? ''),
+    debug: (obj, msg) => pinoLogger.debug(obj, msg ?? ''),
+    info: (obj, msg) => pinoLogger.info(obj, msg ?? ''),
+    warn: (obj, msg) => pinoLogger.warn(obj, msg ?? ''),
+    error: (obj, msg) => pinoLogger.error(obj, msg ?? ''),
+    child: (bindings) => adaptPino(pinoLogger.child(bindings)),
+  };
+  // Stryker enable all
+}
+
+/**
+ * Find the longest-prefix match in logModuleLevels for the given logger name.
+ * Returns the matched level string, or undefined if no match.
+ * Mirrors Python _LevelFilter longest-prefix matching.
+ */
+function findModuleLevel(name: string, moduleLevels: Record<string, string>): string | undefined {
+  let bestMatch: string | undefined;
+  let bestLen = -1;
+  for (const prefix of Object.keys(moduleLevels)) {
+    if (
+      (prefix === '' || name === prefix || name.startsWith(prefix + '.')) &&
+      prefix.length > bestLen
+    ) {
+      bestMatch = prefix;
+      bestLen = prefix.length;
+    }
+  }
+  return bestMatch !== undefined ? moduleLevels[bestMatch] : undefined;
+}
+
+/**
+ * Return a logger for the given name.
+ * Name appears as the `name` field in every log record.
+ * Mirrors Python: get_logger(name)
+ */
+export function getLogger(name?: string): Logger {
+  const root = getRootLogger();
+  // Stryker disable next-line ObjectLiteral
+  const pinoLogger = name ? root.child({ name }) : root;
+  // Apply per-module level overrides (longest-prefix match).
+  if (name) {
+    const cfg = getConfig();
+    const moduleLevels = cfg.logModuleLevels;
+    if (Object.keys(moduleLevels).length > 0) {
+      const level = findModuleLevel(name, moduleLevels);
+      if (level) {
+        pinoLogger.level = level.toLowerCase();
+      }
+    }
+  }
+  return adaptPino(pinoLogger);
+}
+
+/** Reset the root logger (forces re-creation with current config on next call). */
+// Stryker disable next-line BlockStatement
+export function _resetRootLogger(): void {
+  _root = null;
+}
+
+/** Module-level lazy singleton logger. Mirrors Python: logger = get_logger('default'). */
+// Stryker disable all
+export const logger: Logger = {
+  trace: (obj, msg) => getLogger('default').trace(obj, msg),
+  debug: (obj, msg) => getLogger('default').debug(obj, msg),
+  info: (obj, msg) => getLogger('default').info(obj, msg),
+  warn: (obj, msg) => getLogger('default').warn(obj, msg),
+  error: (obj, msg) => getLogger('default').error(obj, msg),
+  child: (bindings) => getLogger('default').child(bindings),
+};
+// Stryker enable all

package/src/metrics.ts

@@ -0,0 +1,204 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Metric instruments — mirrors Python provide.telemetry counter/gauge/histogram.
+ *
+ * Backed by @opentelemetry/api which provides no-op instruments when no SDK is registered.
+ * Safe to call in any environment; instruments are always callable without setup.
+ *
+ * Wrapper classes gate every `.add()`/`.record()` call through sampling + backpressure,
+ * matching the Python fallback.py pattern.
+ */
+
+import {
+  type Attributes,
+  type Counter,
+  type Histogram,
+  type Meter,
+  type UpDownCounter,
+  metrics,
+} from '@opentelemetry/api';
+import { shouldSample } from './sampling';
+import { tryAcquire, release } from './backpressure';
+import { getActiveTraceIds } from './tracing';
+import { getConfig } from './config';
+
+export type { Counter, Histogram, Meter, UpDownCounter };
+
+// Stryker disable next-line StringLiteral: meter name not observable with no-op OTEL SDK in tests
+const METER_NAME = '@provide-io/telemetry';
+
+export interface MetricOptions {
+  description?: string;
+  unit?: string;
+}
+
+/**
+ * Wrapper around OTel Counter that gates add() through sampling + backpressure.
+ */
+export class CounterInstrument {
+  readonly name: string;
+  private readonly _inner: Counter;
+  private _value = 0;
+
+  constructor(name: string, inner: Counter) {
+    this.name = name;
+    this._inner = inner;
+  }
+
+  /** Cumulative counter value (in-process; useful for testing and health checks). */
+  get value(): number {
+    return this._value;
+  }
+
+  add(value: number, attributes?: Attributes): void {
+    if (!getConfig().metricsEnabled) return;
+    if (!shouldSample('metrics', this.name)) return;
+    const ticket = tryAcquire('metrics');
+    if (!ticket) return;
+    try {
+      const ids = getActiveTraceIds();
+      const enriched =
+        ids.trace_id && ids.span_id
+          ? { ...attributes, trace_id: ids.trace_id, span_id: ids.span_id }
+          : attributes;
+      this._inner.add(value, enriched);
+      this._value += value;
+    } finally {
+      release(ticket);
+    }
+  }
+}
+
+/**
+ * Wrapper around OTel UpDownCounter with set semantics.
+ * Gates add()/set() through sampling + backpressure.
+ */
+export class GaugeInstrument {
+  readonly name: string;
+  private readonly _inner: UpDownCounter;
+  private readonly _values: Map<string, number> = new Map();
+  private _lastValue = 0;
+
+  constructor(name: string, inner: UpDownCounter) {
+    this.name = name;
+    this._inner = inner;
+  }
+
+  /** Most recent value set or accumulated via add() (in-process; useful for testing and health checks). */
+  get value(): number {
+    return this._lastValue;
+  }
+
+  add(value: number, attributes?: Attributes): void {
+    if (!getConfig().metricsEnabled) return;
+    if (!shouldSample('metrics', this.name)) return;
+    const ticket = tryAcquire('metrics');
+    if (!ticket) return;
+    try {
+      this._inner.add(value, attributes);
+      this._lastValue += value;
+    } finally {
+      release(ticket);
+    }
+  }
+
+  set(value: number, attributes?: Attributes): void {
+    if (!getConfig().metricsEnabled) return;
+    if (!shouldSample('metrics', this.name)) return;
+    const ticket = tryAcquire('metrics');
+    if (!ticket) return;
+    try {
+      // Stryker disable next-line StringLiteral: empty string fallback for no-attributes key — functionally equivalent to any constant
+      const key = attributes ? JSON.stringify(attributes) : '';
+      const prev = this._values.get(key) ?? 0;
+      const delta = value - prev;
+      this._values.set(key, value);
+      this._inner.add(delta, attributes);
+      this._lastValue = value;
+    } finally {
+      release(ticket);
+    }
+  }
+}
+
+/**
+ * Wrapper around OTel Histogram that gates record() through sampling + backpressure.
+ */
+export class HistogramInstrument {
+  readonly name: string;
+  private readonly _inner: Histogram;
+  private _count = 0;
+  private _total = 0;
+
+  constructor(name: string, inner: Histogram) {
+    this.name = name;
+    this._inner = inner;
+  }
+
+  /** Number of values recorded (in-process; useful for testing and health checks). */
+  get count(): number {
+    return this._count;
+  }
+
+  /** Sum of all recorded values (in-process; useful for testing and health checks). */
+  get total(): number {
+    return this._total;
+  }
+
+  record(value: number, attributes?: Attributes): void {
+    if (!getConfig().metricsEnabled) return;
+    if (!shouldSample('metrics', this.name)) return;
+    const ticket = tryAcquire('metrics');
+    if (!ticket) return;
+    try {
+      const ids = getActiveTraceIds();
+      const enriched =
+        ids.trace_id && ids.span_id
+          ? { ...attributes, trace_id: ids.trace_id, span_id: ids.span_id }
+          : attributes;
+      this._inner.record(value, enriched);
+      this._count += 1;
+      this._total += value;
+    } finally {
+      release(ticket);
+    }
+  }
+}
+
+/**
+ * Create a monotonically increasing counter.
+ * Mirrors Python: counter(name, description, unit)
+ */
+export function counter(name: string, options?: MetricOptions): CounterInstrument {
+  const inner = metrics.getMeter(METER_NAME).createCounter(name, options);
+  return new CounterInstrument(name, inner);
+}
+
+/**
+ * Create an up-down counter (gauge — can increase or decrease).
+ * Mirrors Python: gauge(name, description, unit)
+ */
+export function gauge(name: string, options?: MetricOptions): GaugeInstrument {
+  const inner = metrics.getMeter(METER_NAME).createUpDownCounter(name, options);
+  return new GaugeInstrument(name, inner);
+}
+
+/**
+ * Create a histogram for recording distributions (latencies, sizes).
+ * Mirrors Python: histogram(name, description, unit)
+ */
+export function histogram(name: string, options?: MetricOptions): HistogramInstrument {
+  const inner = metrics.getMeter(METER_NAME).createHistogram(name, options);
+  return new HistogramInstrument(name, inner);
+}
+
+/**
+ * Return an OTEL Meter from the global meter provider.
+ * Mirrors Python: get_meter(name)
+ */
+export function getMeter(name?: string): Meter {
+  // Stryker disable next-line LogicalOperator: getMeter(undefined) behaves identically to getMeter(name) with no-op OTEL API
+  return metrics.getMeter(name ?? METER_NAME);
+}