@provide-io/telemetry 0.2.2

package/src/context.ts

@@ -0,0 +1,157 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Module-level context binding — mirrors Python provide.telemetry bind_context/unbind_context.
+ *
+ * In browser environments, context is stored in a module-level object. All log calls
+ * in the same JS execution context share the same bindings.
+ *
+ * In Node.js environments, AsyncLocalStorage provides per-async-context isolation
+ * (useful for SSR / worker processes where multiple requests run concurrently).
+ * Use runWithContext() to scope bindings to a single request/operation.
+ */
+
+type Context = Record<string, unknown>;
+
+// ── AsyncLocalStorage type (Node.js / Cloudflare Workers) ─────────────────────
+type ALS = {
+  getStore(): Context | undefined;
+  run<T>(store: Context, fn: () => T): T;
+  enterWith(store: Context): void;
+};
+
+// ── AsyncLocalStorage (Node.js / Cloudflare Workers) ──────────────────────────
+let _asyncLocalStorage: ALS | null = null;
+let _AlsConstructor: (new () => ALS) | null = null;
+try {
+  // Dynamic require so the import doesn't break browser bundles.
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const als = require('node:async_hooks') as { AsyncLocalStorage: new () => ALS };
+  _AlsConstructor = als.AsyncLocalStorage;
+  _asyncLocalStorage = new _AlsConstructor();
+} catch {
+  // Not available — fall back to module-level context below.
+}
+
+// ── Fallback: module-level context (browser / single-thread) ──────────────────
+let _moduleCtx: Context = {};
+
+function getStore(): Context {
+  if (_asyncLocalStorage) {
+    return _asyncLocalStorage.getStore() ?? _moduleCtx;
+  }
+  return _moduleCtx;
+}
+
+function ensureStore(): Context {
+  if (_asyncLocalStorage) {
+    const store = _asyncLocalStorage.getStore();
+    if (store) return store;
+    const next = { ..._moduleCtx };
+    _asyncLocalStorage.enterWith(next);
+    return next;
+  }
+  return _moduleCtx;
+}
+
+/**
+ * Bind key/value pairs into the current context.
+ * These fields are merged into every log record emitted after this call.
+ */
+export function bindContext(values: Context): void {
+  const store = ensureStore();
+  Object.assign(store, values);
+}
+
+/**
+ * Remove specific keys from the current context.
+ */
+export function unbindContext(...keys: string[]): void {
+  const store = ensureStore();
+  for (const k of keys) delete store[k];
+}
+
+/**
+ * Clear all context bindings.
+ */
+export function clearContext(): void {
+  if (_asyncLocalStorage) {
+    const store = _asyncLocalStorage.getStore();
+    if (store) {
+      for (const k of Object.keys(store)) delete store[k];
+      return;
+    }
+  }
+  _moduleCtx = {};
+}
+
+/**
+ * Return a snapshot of the current context (no side effects).
+ */
+export function getContext(): Context {
+  return { ...getStore() };
+}
+
+/**
+ * Run fn with additional context values scoped to its execution.
+ * In Node.js, uses AsyncLocalStorage so the bindings are isolated per-request.
+ * In browser, temporarily binds then restores the previous state.
+ * Mirrors Python: contextvars copy_context().run(fn) pattern.
+ */
+export function runWithContext<T>(values: Context, fn: () => T): T {
+  if (_asyncLocalStorage) {
+    const inherited = { ...getStore(), ...values };
+    return _asyncLocalStorage.run(inherited, fn);
+  }
+  const prev = { ...getStore() };
+  bindContext(values);
+  try {
+    return fn();
+  } finally {
+    _moduleCtx = prev;
+  }
+}
+
+/**
+ * Bind a session ID that propagates across all telemetry events.
+ */
+export function bindSessionContext(sessionId: string): void {
+  bindContext({ session_id: sessionId });
+}
+
+/**
+ * Return the current session ID, or null if not set.
+ */
+export function getSessionId(): string | null {
+  const sessionId = getStore()['session_id'];
+  return typeof sessionId === 'string' ? sessionId : null;
+}
+
+/**
+ * Clear the session ID.
+ */
+export function clearSessionContext(): void {
+  unbindContext('session_id');
+}
+
+/** Reset to empty context (used in tests). */
+export function _resetContext(): void {
+  // Recreate ALS so no enterWith-seeded store leaks between tests.
+  // The null branch is only reachable in environments without node:async_hooks (e.g. browsers).
+  /* v8 ignore next */
+  _asyncLocalStorage = _AlsConstructor ? new _AlsConstructor() : null;
+  _moduleCtx = {};
+}
+
+/** Disable AsyncLocalStorage for testing the module-level fallback path. */
+export function _disableAsyncLocalStorageForTest(): ALS | null {
+  const prev = _asyncLocalStorage;
+  _asyncLocalStorage = null;
+  return prev;
+}
+
+/** Re-enable AsyncLocalStorage after testing (pass value from _disable call). */
+export function _restoreAsyncLocalStorageForTest(saved: ALS | null): void {
+  _asyncLocalStorage = saved;
+}

package/src/exceptions.ts

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Exception hierarchy — mirrors Python provide.telemetry.exceptions.
+ */
+
+export class TelemetryError extends Error {
+  constructor(message?: string) {
+    super(message);
+    this.name = 'TelemetryError';
+  }
+}
+
+/**
+ * Raised when telemetry configuration is invalid.
+ * Also extends Error directly for maximum compatibility.
+ */
+export class ConfigurationError extends TelemetryError {
+  constructor(message?: string) {
+    super(message);
+    this.name = 'ConfigurationError';
+  }
+}

package/src/fingerprint.ts

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Stable error fingerprinting — generates a 12-char hex hash from
+ * exception type + top 3 stack frames (file:function, no line numbers).
+ *
+ * Cross-language compatible: same error in Python and TypeScript produces
+ * the same fingerprint when the call path is equivalent.
+ */
+
+import { shortHash12 } from './hash';
+
+/**
+ * Parse an Error stack trace into normalized frames: `basename:function`.
+ * Returns at most 3 frames (most recent).
+ */
+function extractFrames(stack: string | undefined): string[] {
+  // Stryker disable next-line ConditionalExpression -- equivalent: falsy stack always yields no frames
+  if (!stack) return [];
+  const frames: string[] = [];
+  // V8: "at functionName (filename:line:col)" or "at filename:line:col"
+  // Stryker disable next-line Regex -- \s+ vs \s and trailing \d+ vs \d are equivalent for real stacks
+  const v8Re = /at\s+(?:(.+?)\s+\()?(.*?):\d+:\d+\)?/g;
+  // SpiderMonkey/JSC: "functionName@filename:line:col"
+  // Stryker disable next-line Regex -- trailing \d+ vs \d is equivalent for file extraction
+  const smRe = /(.+?)@(.*?):\d+:\d+/g;
+  for (const re of [v8Re, smRe]) {
+    let match: RegExpExecArray | null;
+    while ((match = re.exec(stack)) !== null) {
+      const func = String(match[1] || '').toLowerCase();
+      const file = String(match[2] || '');
+      const parts = file.split('/');
+      const last = parts[parts.length - 1] || '';
+      const winParts = last.split('\\');
+      const leaf = winParts[winParts.length - 1] || '';
+      const basename = leaf.replace(/\.[^.]+$/, '').toLowerCase();
+      if (basename) {
+        frames.push(`${basename}:${func}`);
+      }
+    }
+  }
+  return frames.slice(-3);
+}
+
+/**
+ * Compute a stable 12-char hex fingerprint for an error.
+ */
+export function computeErrorFingerprint(errorName: string, stack?: string): string {
+  const parts = [errorName.toLowerCase()];
+  parts.push(...extractFrames(stack));
+  return shortHash12(parts.join(':'));
+}

package/src/hash.ts

@@ -0,0 +1,118 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+const INITIAL_HASH: number[] = [
+  0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+];
+
+const ROUND_CONSTANTS: number[] = [
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+
+function add32(...values: number[]): number {
+  let sum = 0;
+  for (const value of values) {
+    sum = (sum + (value >>> 0)) >>> 0;
+  }
+  return sum;
+}
+
+function rotateRight(value: number, bits: number): number {
+  return (value >>> bits) | (value << (32 - bits));
+}
+
+export function sha256Hex(input: string): string {
+  const bytes = new TextEncoder().encode(input);
+  const bitLength = bytes.length * 8;
+  const paddedLength = Math.ceil((bytes.length + 9) / 64) * 64;
+  const padded = new Uint8Array(paddedLength);
+  padded.set(bytes);
+  padded[bytes.length] = 0x80;
+
+  const view = new DataView(padded.buffer);
+  // Stryker disable next-line ArithmeticOperator: highBits is always 0 for inputs under 512 MB — division vs multiplication both produce 0 after ToUint32 coercion
+  const highBits = Math.floor(bitLength / 0x100000000);
+  const lowBits = bitLength >>> 0;
+  // Stryker disable next-line BooleanLiteral: highBits is 0 for all testable inputs — big-endian vs little-endian of 0 is identical
+  view.setUint32(paddedLength - 8, highBits, false);
+  view.setUint32(paddedLength - 4, lowBits, false);
+
+  const words = new Uint32Array(64);
+  let [h0, h1, h2, h3, h4, h5, h6, h7] = INITIAL_HASH;
+
+  for (let offset = 0; offset < paddedLength; offset += 64) {
+    for (let i = 0; i < 16; i++) {
+      words[i] = view.getUint32(offset + i * 4, false);
+    }
+
+    // Stryker disable next-line EqualityOperator: Uint32Array(64) silently ignores writes to index 64 — the extra iteration is a no-op
+    for (let i = 16; i < 64; i++) {
+      const w15 = words[i - 15] as number;
+      const w2 = words[i - 2] as number;
+      const sigma0 = rotateRight(w15, 7) ^ rotateRight(w15, 18) ^ (w15 >>> 3);
+      const sigma1 = rotateRight(w2, 17) ^ rotateRight(w2, 19) ^ (w2 >>> 10);
+      words[i] = add32(words[i - 16] as number, sigma0, words[i - 7] as number, sigma1);
+    }
+
+    let a = h0;
+    let b = h1;
+    let c = h2;
+    let d = h3;
+    let e = h4;
+    let f = h5;
+    let g = h6;
+    let h = h7;
+
+    for (let i = 0; i < 64; i++) {
+      const sum1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+      const choose = (e & f) ^ (~e & g);
+      const temp1 = add32(h, sum1, choose, ROUND_CONSTANTS[i] as number, words[i] as number);
+      const sum0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+      const majority = (a & b) ^ (a & c) ^ (b & c);
+      const temp2 = add32(sum0, majority);
+
+      h = g;
+      g = f;
+      f = e;
+      e = add32(d, temp1);
+      d = c;
+      c = b;
+      b = a;
+      a = add32(temp1, temp2);
+    }
+
+    h0 = add32(h0, a);
+    h1 = add32(h1, b);
+    h2 = add32(h2, c);
+    h3 = add32(h3, d);
+    h4 = add32(h4, e);
+    h5 = add32(h5, f);
+    h6 = add32(h6, g);
+    h7 = add32(h7, h);
+  }
+
+  return [h0, h1, h2, h3, h4, h5, h6, h7]
+    .map((word) => word.toString(16).padStart(8, '0'))
+    .join('');
+}
+
+export function shortHash12(input: string): string {
+  return sha256Hex(input).slice(0, 12);
+}
+
+/**
+ * Generate `numBytes` random bytes and return them as a lowercase hex string.
+ * Uses the Web Crypto API (available in Node.js 15+, browsers, and edge runtimes).
+ */
+export function randomHex(numBytes: number): string {
+  const bytes = new Uint8Array(numBytes);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}

package/src/health.ts

@@ -0,0 +1,175 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Internal self-observability counters — mirrors Python provide.telemetry.health.
+ * Canonical 25-field layout: 8 per signal (logs, traces, metrics) + 1 global.
+ */
+
+export interface HealthSnapshot {
+  // Logs (8)
+  logsEmitted: number;
+  logsDropped: number;
+  exportFailuresLogs: number;
+  retriesLogs: number;
+  exportLatencyMsLogs: number;
+  asyncBlockingRiskLogs: number;
+  circuitStateLogs: string;
+  circuitOpenCountLogs: number;
+  // Traces (8)
+  tracesEmitted: number;
+  tracesDropped: number;
+  exportFailuresTraces: number;
+  retriesTraces: number;
+  exportLatencyMsTraces: number;
+  asyncBlockingRiskTraces: number;
+  circuitStateTraces: string;
+  circuitOpenCountTraces: number;
+  // Metrics (8)
+  metricsEmitted: number;
+  metricsDropped: number;
+  exportFailuresMetrics: number;
+  retriesMetrics: number;
+  exportLatencyMsMetrics: number;
+  asyncBlockingRiskMetrics: number;
+  circuitStateMetrics: string;
+  circuitOpenCountMetrics: number;
+  // Global (1)
+  setupError: string | null;
+}
+
+/** Numeric fields that live in the mutable _state object (not derived circuit fields). */
+type NumericHealthField =
+  | 'logsEmitted'
+  | 'logsDropped'
+  | 'tracesEmitted'
+  | 'tracesDropped'
+  | 'metricsEmitted'
+  | 'metricsDropped'
+  | 'exportFailuresLogs'
+  | 'exportFailuresTraces'
+  | 'exportFailuresMetrics'
+  | 'retriesLogs'
+  | 'retriesTraces'
+  | 'retriesMetrics'
+  | 'exportLatencyMsLogs'
+  | 'exportLatencyMsTraces'
+  | 'exportLatencyMsMetrics'
+  | 'asyncBlockingRiskLogs'
+  | 'asyncBlockingRiskTraces'
+  | 'asyncBlockingRiskMetrics';
+
+let _setupError: string | null = null;
+
+const _state = {
+  logsEmitted: 0,
+  logsDropped: 0,
+  tracesEmitted: 0,
+  tracesDropped: 0,
+  metricsEmitted: 0,
+  metricsDropped: 0,
+  exportFailuresLogs: 0,
+  exportFailuresTraces: 0,
+  exportFailuresMetrics: 0,
+  retriesLogs: 0,
+  retriesTraces: 0,
+  retriesMetrics: 0,
+  exportLatencyMsLogs: 0,
+  exportLatencyMsTraces: 0,
+  exportLatencyMsMetrics: 0,
+  asyncBlockingRiskLogs: 0,
+  asyncBlockingRiskTraces: 0,
+  asyncBlockingRiskMetrics: 0,
+};
+
+// Lazy reference to avoid circular dependency at module load time.
+// resilience.ts imports from health.ts, so we register the callback after load.
+type CircuitStateResult = { state: string; openCount: number; cooldownRemainingMs: number };
+type CircuitStateFn = (signal: string) => CircuitStateResult;
+
+const _defaultCircuitState: CircuitStateResult = {
+  state: 'closed',
+  openCount: 0,
+  cooldownRemainingMs: 0,
+};
+let _circuitStateFn: CircuitStateFn = () => _defaultCircuitState;
+
+/** Called by resilience module to register the getCircuitState function. */
+export function _registerCircuitStateFn(fn: CircuitStateFn): void {
+  _circuitStateFn = fn;
+}
+
+export function getHealthSnapshot(): HealthSnapshot {
+  const csLogs = _circuitStateFn('logs');
+  const csTraces = _circuitStateFn('traces');
+  const csMetrics = _circuitStateFn('metrics');
+  return {
+    ..._state,
+    circuitStateLogs: csLogs.state,
+    circuitStateTraces: csTraces.state,
+    circuitStateMetrics: csMetrics.state,
+    circuitOpenCountLogs: csLogs.openCount,
+    circuitOpenCountTraces: csTraces.openCount,
+    circuitOpenCountMetrics: csMetrics.openCount,
+    setupError: _setupError,
+  };
+}
+
+export function setSetupError(error: string | null): void {
+  _setupError = error;
+}
+
+export function _incrementHealth(field: NumericHealthField, by: number = 1): void {
+  _state[field] += by;
+}
+
+/** Map a signal name to the per-signal export-failures field. */
+export function _exportFailuresField(
+  signal: string,
+): 'exportFailuresLogs' | 'exportFailuresTraces' | 'exportFailuresMetrics' {
+  if (signal === 'traces') return 'exportFailuresTraces';
+  if (signal === 'metrics') return 'exportFailuresMetrics';
+  return 'exportFailuresLogs';
+}
+
+/** Map a signal name to the per-signal retries field. */
+export function _retriesField(signal: string): 'retriesLogs' | 'retriesTraces' | 'retriesMetrics' {
+  if (signal === 'traces') return 'retriesTraces';
+  if (signal === 'metrics') return 'retriesMetrics';
+  return 'retriesLogs';
+}
+
+/** Map a signal name to the per-signal export latency field. */
+export function _exportLatencyField(
+  signal: string,
+): 'exportLatencyMsLogs' | 'exportLatencyMsTraces' | 'exportLatencyMsMetrics' {
+  if (signal === 'traces') return 'exportLatencyMsTraces';
+  if (signal === 'metrics') return 'exportLatencyMsMetrics';
+  return 'exportLatencyMsLogs';
+}
+
+export function _recordExportLatency(signal: string, ms: number): void {
+  _state[_exportLatencyField(signal)] = ms;
+}
+
+export function _resetHealthForTests(): void {
+  _state.logsEmitted = 0;
+  _state.logsDropped = 0;
+  _state.tracesEmitted = 0;
+  _state.tracesDropped = 0;
+  _state.metricsEmitted = 0;
+  _state.metricsDropped = 0;
+  _state.exportFailuresLogs = 0;
+  _state.exportFailuresTraces = 0;
+  _state.exportFailuresMetrics = 0;
+  _state.retriesLogs = 0;
+  _state.retriesTraces = 0;
+  _state.retriesMetrics = 0;
+  _state.exportLatencyMsLogs = 0;
+  _state.exportLatencyMsTraces = 0;
+  _state.exportLatencyMsMetrics = 0;
+  _state.asyncBlockingRiskLogs = 0;
+  _state.asyncBlockingRiskTraces = 0;
+  _state.asyncBlockingRiskMetrics = 0;
+  _setupError = null;
+}