@provide-io/telemetry 0.2.2

package/src/resilience.ts

@@ -0,0 +1,220 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Exporter resilience — retry, backoff, timeout, and circuit breaker.
+ * Mirrors Python provide.telemetry.resilience.
+ */
+
+import {
+  _exportFailuresField,
+  _incrementHealth,
+  _recordExportLatency,
+  _registerCircuitStateFn,
+  _retriesField,
+} from './health';
+
+export class TelemetryTimeoutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'TelemetryTimeoutError';
+  }
+}
+
+export interface ExporterPolicy {
+  retries: number;
+  backoffMs: number;
+  timeoutMs: number;
+  failOpen: boolean;
+}
+
+const DEFAULT_POLICY: ExporterPolicy = {
+  retries: 0,
+  backoffMs: 0,
+  timeoutMs: 10_000,
+  failOpen: true,
+};
+
+export const CIRCUIT_BREAKER_THRESHOLD = 3;
+export const CIRCUIT_BASE_COOLDOWN_MS = 30_000;
+const CIRCUIT_MAX_COOLDOWN_MS = 1_024_000;
+
+// Stryker disable next-line ObjectLiteral
+let _policies: Record<string, ExporterPolicy> = {};
+// Stryker disable next-line ObjectLiteral
+export const _consecutiveTimeouts: Record<string, number> = { logs: 0, traces: 0, metrics: 0 };
+// Stryker disable next-line ObjectLiteral
+export const _circuitTrippedAt: Record<string, number> = { logs: 0, traces: 0, metrics: 0 };
+// Stryker disable next-line ObjectLiteral
+export const _openCount: Record<string, number> = { logs: 0, traces: 0, metrics: 0 };
+/* Stryker disable BooleanLiteral: initial false values are reset by _resetResilienceForTests before each test — equivalent mutant */
+// Stryker disable next-line ObjectLiteral
+export const _halfOpenProbing: Record<string, boolean> = {
+  logs: false,
+  traces: false,
+  metrics: false,
+};
+/* Stryker restore BooleanLiteral */
+
+export function setExporterPolicy(signal: string, policy: Partial<ExporterPolicy>): void {
+  _policies[signal] = { ...DEFAULT_POLICY, ...policy };
+}
+
+export function getExporterPolicy(signal: string): ExporterPolicy {
+  return { ...(_policies[signal] ?? DEFAULT_POLICY) };
+}
+
+// Stryker disable next-line BlockStatement
+function _sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function _withTimeout<T>(fn: () => Promise<T>, timeoutMs: number): Promise<T> {
+  // Stryker disable next-line ConditionalExpression,EqualityOperator
+  if (timeoutMs <= 0) return fn();
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      // Stryker disable next-line StringLiteral: timeout error message content is not tested
+      reject(new TelemetryTimeoutError(`operation timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    fn().then(
+      (val) => {
+        clearTimeout(timer);
+        resolve(val);
+      },
+      (err: unknown) => {
+        clearTimeout(timer);
+        reject(err);
+      },
+    );
+  });
+}
+
+export async function runWithResilience<T>(
+  signal: string,
+  fn: () => Promise<T>,
+): Promise<T | null> {
+  const policy = _policies[signal] ?? { ...DEFAULT_POLICY };
+  const attempts = Math.max(1, policy.retries + 1);
+
+  // Ensure per-signal dicts are initialized for custom signals.
+  if (!(signal in _openCount)) _openCount[signal] = 0;
+  // Stryker disable next-line ConditionalExpression: custom signal init — skipping is equivalent since undefined is falsy like false
+  if (!(signal in _halfOpenProbing)) _halfOpenProbing[signal] = false;
+
+  // Circuit breaker check.
+  const failField = _exportFailuresField(signal);
+  const retryField = _retriesField(signal);
+  // Stryker disable next-line ConditionalExpression
+  if (_consecutiveTimeouts[signal] >= CIRCUIT_BREAKER_THRESHOLD) {
+    // Reject concurrent callers while a half-open probe is already in flight.
+    if (_halfOpenProbing[signal]) {
+      _incrementHealth(failField);
+      if (policy.failOpen) return null;
+      throw new TelemetryTimeoutError('circuit breaker open: probe in progress');
+    }
+    const cooldown = Math.min(
+      CIRCUIT_BASE_COOLDOWN_MS * 2 ** _openCount[signal],
+      CIRCUIT_MAX_COOLDOWN_MS,
+    );
+    const elapsed = Date.now() - _circuitTrippedAt[signal];
+    if (elapsed < cooldown) {
+      _incrementHealth(failField);
+      if (policy.failOpen) return null;
+      throw new TelemetryTimeoutError('circuit breaker open: too many consecutive timeouts');
+    }
+    // Half-open: cooldown elapsed — allow one probe.
+    _halfOpenProbing[signal] = true;
+  }
+
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    const started = Date.now();
+    try {
+      const result = await _withTimeout(fn, policy.timeoutMs);
+      _recordExportLatency(signal, Date.now() - started);
+      if (_halfOpenProbing[signal]) {
+        _halfOpenProbing[signal] = false;
+        _consecutiveTimeouts[signal] = 0;
+        _openCount[signal] = Math.max(0, _openCount[signal] - 1);
+        // Stryker disable next-line BlockStatement: else-block body on non-probe success — removing is equivalent since timeouts are already 0 on fresh closed circuit
+      } else {
+        _consecutiveTimeouts[signal] = 0;
+      }
+      return result;
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      _incrementHealth(failField);
+
+      if (err instanceof TelemetryTimeoutError) {
+        if (_halfOpenProbing[signal]) {
+          _halfOpenProbing[signal] = false;
+          _openCount[signal] += 1;
+          _circuitTrippedAt[signal] = Date.now();
+        } else {
+          _consecutiveTimeouts[signal] = (_consecutiveTimeouts[signal] ?? 0) + 1;
+          // Stryker disable next-line ConditionalExpression,EqualityOperator
+          if (_consecutiveTimeouts[signal] >= CIRCUIT_BREAKER_THRESHOLD) {
+            _openCount[signal] += 1;
+            _circuitTrippedAt[signal] = Date.now();
+          }
+        }
+      } else if (_halfOpenProbing[signal]) {
+        _halfOpenProbing[signal] = false;
+        _openCount[signal] += 1;
+        _circuitTrippedAt[signal] = Date.now();
+      } else {
+        _consecutiveTimeouts[signal] = 0;
+      }
+
+      // Stryker disable next-line ArithmeticOperator
+      if (attempt < attempts - 1) {
+        _incrementHealth(retryField);
+        // Stryker disable next-line ConditionalExpression,EqualityOperator
+        if (policy.backoffMs > 0) await _sleep(policy.backoffMs);
+      }
+    }
+  }
+
+  if (policy.failOpen) return null;
+  // Stryker disable next-line StringLiteral: unreachable fallback — lastError is always set by the catch block above
+  /* v8 ignore next */
+  throw lastError ?? new Error('all retry attempts failed');
+}
+
+export interface CircuitState {
+  state: string;
+  openCount: number;
+  cooldownRemainingMs: number;
+}
+
+export function getCircuitState(signal: string): CircuitState {
+  const openCount = _openCount[signal] ?? 0;
+  if (_halfOpenProbing[signal]) {
+    return { state: 'half-open', openCount, cooldownRemainingMs: 0 };
+  }
+  if ((_consecutiveTimeouts[signal] ?? 0) >= CIRCUIT_BREAKER_THRESHOLD) {
+    const cooldown = Math.min(CIRCUIT_BASE_COOLDOWN_MS * 2 ** openCount, CIRCUIT_MAX_COOLDOWN_MS);
+    const remaining = cooldown - (Date.now() - _circuitTrippedAt[signal]);
+    // Stryker disable next-line EqualityOperator: > 0 vs >= 0 — exact millisecond boundary P≈0
+    if (remaining > 0) {
+      return { state: 'open', openCount, cooldownRemainingMs: remaining };
+    }
+    return { state: 'half-open', openCount, cooldownRemainingMs: 0 };
+  }
+  return { state: 'closed', openCount, cooldownRemainingMs: 0 };
+}
+
+// Register with health module to break circular dependency.
+_registerCircuitStateFn(getCircuitState);
+
+export function _resetResilienceForTests(): void {
+  _policies = {};
+  for (const k of ['logs', 'traces', 'metrics']) {
+    _consecutiveTimeouts[k] = 0;
+    _circuitTrippedAt[k] = 0;
+    _openCount[k] = 0;
+    _halfOpenProbing[k] = false;
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,171 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Runtime reconfiguration helpers.
+ * Mirrors Python provide.telemetry.runtime.
+ */
+
+import {
+  type RuntimeOverrides,
+  type TelemetryConfig,
+  configFromEnv,
+  setupTelemetry,
+} from './config';
+
+/** Minimal interface for providers that can be flushed and shut down cleanly. */
+export interface ShutdownableProvider {
+  forceFlush?(): Promise<void>;
+  shutdown?(): Promise<void>;
+}
+
+let _activeConfig: TelemetryConfig | null = null;
+// Stryker disable next-line BooleanLiteral: initial false is overwritten by _resetRuntimeForTests() in every test beforeEach — equivalent mutant
+let _providersRegistered = false;
+// Stryker disable next-line ArrayDeclaration: initial [] is overwritten by _resetRuntimeForTests() in every test beforeEach — equivalent mutant
+let _registeredProviders: ShutdownableProvider[] = [];
+
+/** Store the live providers so shutdownTelemetry can flush and drain them. */
+export function _storeRegisteredProviders(providers: ShutdownableProvider[]): void {
+  _registeredProviders = providers;
+}
+
+/** Return the currently registered providers (snapshot). */
+export function _getRegisteredProviders(): ShutdownableProvider[] {
+  return [..._registeredProviders];
+}
+
+/** Called by registerOtelProviders once providers are live. */
+export function _markProvidersRegistered(): void {
+  _providersRegistered = true;
+}
+
+/** Return true if OTEL providers have been registered. */
+export function _areProvidersRegistered(): boolean {
+  return _providersRegistered;
+}
+
+function deepFreeze<T extends object>(obj: T): Readonly<T> {
+  for (const val of Object.values(obj)) {
+    if (typeof val === 'object' && val !== null && !Object.isFrozen(val)) {
+      deepFreeze(val as object);
+    }
+  }
+  return Object.freeze(obj);
+}
+
+/** Return the active runtime config (or env-derived defaults if none set). */
+export function getRuntimeConfig(): Readonly<TelemetryConfig> {
+  const cfg = _activeConfig ?? configFromEnv();
+  return deepFreeze({ ...cfg });
+}
+
+/** Merge hot-reloadable overrides into the active config and re-apply policies. */
+export function updateRuntimeConfig(overrides: RuntimeOverrides): void {
+  const base = _activeConfig ?? configFromEnv();
+  const merged: TelemetryConfig = { ...base };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value !== undefined) {
+      (merged as unknown as Record<string, unknown>)[key] = value;
+    }
+  }
+  _activeConfig = merged;
+  setupTelemetry(_activeConfig);
+}
+
+const _COLD_FIELDS: (keyof TelemetryConfig)[] = [
+  'serviceName',
+  'environment',
+  'version',
+  'otelEnabled',
+  'otlpEndpoint',
+  'otlpHeaders',
+];
+
+/** Reload config from env vars and apply only hot-reloadable fields. */
+export function reloadRuntimeFromEnv(): void {
+  const fresh = configFromEnv();
+  const current = _activeConfig;
+  if (current) {
+    const drifted = _COLD_FIELDS.filter(
+      (k) => JSON.stringify(current[k]) !== JSON.stringify(fresh[k]),
+    );
+    if (drifted.length > 0) {
+      console.warn(
+        '[provide-telemetry] runtime.cold_field_drift:',
+        drifted.join(', '),
+        '— restart required to apply',
+      );
+    }
+  }
+  // Apply only hot fields via overrides
+  const overrides: RuntimeOverrides = {
+    samplingLogsRate: fresh.samplingLogsRate,
+    samplingTracesRate: fresh.samplingTracesRate,
+    samplingMetricsRate: fresh.samplingMetricsRate,
+    backpressureLogsMaxsize: fresh.backpressureLogsMaxsize,
+    backpressureTracesMaxsize: fresh.backpressureTracesMaxsize,
+    backpressureMetricsMaxsize: fresh.backpressureMetricsMaxsize,
+    exporterLogsRetries: fresh.exporterLogsRetries,
+    exporterLogsBackoffMs: fresh.exporterLogsBackoffMs,
+    exporterLogsTimeoutMs: fresh.exporterLogsTimeoutMs,
+    exporterLogsFailOpen: fresh.exporterLogsFailOpen,
+    exporterTracesRetries: fresh.exporterTracesRetries,
+    exporterTracesBackoffMs: fresh.exporterTracesBackoffMs,
+    exporterTracesTimeoutMs: fresh.exporterTracesTimeoutMs,
+    exporterTracesFailOpen: fresh.exporterTracesFailOpen,
+    exporterMetricsRetries: fresh.exporterMetricsRetries,
+    exporterMetricsBackoffMs: fresh.exporterMetricsBackoffMs,
+    exporterMetricsTimeoutMs: fresh.exporterMetricsTimeoutMs,
+    exporterMetricsFailOpen: fresh.exporterMetricsFailOpen,
+    securityMaxAttrValueLength: fresh.securityMaxAttrValueLength,
+    securityMaxAttrCount: fresh.securityMaxAttrCount,
+    sloEnableRedMetrics: fresh.sloEnableRedMetrics,
+    sloEnableUseMetrics: fresh.sloEnableUseMetrics,
+    piiMaxDepth: fresh.piiMaxDepth,
+  };
+  updateRuntimeConfig(overrides);
+}
+
+const PROVIDER_CHANGING_FIELDS: (keyof TelemetryConfig)[] = [
+  'otelEnabled',
+  'otlpEndpoint',
+  'otlpHeaders',
+];
+
+/**
+ * Apply config changes.
+ * If provider-changing fields differ and providers are already registered, performs a
+ * best-effort shutdown (fire-and-forget) then re-initialises — matching Go/Python behaviour.
+ * Otherwise delegates to setupTelemetry.
+ */
+export function reconfigureTelemetry(config: Partial<TelemetryConfig>): void {
+  const current = getRuntimeConfig();
+  const proposed: TelemetryConfig = { ...current, ...config };
+
+  if (_providersRegistered) {
+    const changed = PROVIDER_CHANGING_FIELDS.some(
+      (k) => JSON.stringify(current[k]) !== JSON.stringify(proposed[k]),
+    );
+    if (changed) {
+      // Best-effort async shutdown — fire-and-forget, errors ignored (mirrors Go's `_ = ShutdownTelemetry(ctx)`)
+      const providers = _getRegisteredProviders();
+      // Stryker disable LogicalOperator: ?? vs && is equivalent here — forceFlush/shutdown return Promise (truthy) so && still resolves; when undefined, Promise.allSettled wraps both in Promise.resolve
+      void Promise.allSettled(providers.map((p) => p.forceFlush?.() ?? Promise.resolve())).then(
+        () => Promise.allSettled(providers.map((p) => p.shutdown?.() ?? Promise.resolve())),
+      );
+      // Stryker restore LogicalOperator
+      _providersRegistered = false;
+      _registeredProviders = [];
+    }
+  }
+
+  setupTelemetry(proposed);
+  _activeConfig = proposed;
+}
+
+export function _resetRuntimeForTests(): void {
+  _activeConfig = null;
+  _providersRegistered = false;
+  _registeredProviders = [];
+}

package/src/sampling.ts

@@ -0,0 +1,68 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Runtime sampling policy — mirrors Python provide.telemetry.sampling.
+ */
+
+import { ConfigurationError } from './exceptions';
+
+export interface SamplingPolicy {
+  defaultRate: number;
+  overrides?: Record<string, number>;
+}
+
+const DEFAULT_POLICY: SamplingPolicy = { defaultRate: 1.0 };
+let _policies: Record<string, SamplingPolicy> = {};
+
+const VALID_SIGNALS = new Set(['logs', 'traces', 'metrics']);
+
+function _validateSignal(signal: string): void {
+  if (!VALID_SIGNALS.has(signal)) {
+    throw new ConfigurationError(
+      `unknown signal "${signal}", expected one of [logs, metrics, traces]`,
+    );
+  }
+}
+
+function _clamp(rate: number): number {
+  return Math.max(0, Math.min(1, rate));
+}
+
+export function setSamplingPolicy(signal: string, policy: SamplingPolicy): void {
+  _validateSignal(signal);
+  _policies[signal] = {
+    defaultRate: _clamp(policy.defaultRate),
+    overrides: policy.overrides
+      ? Object.fromEntries(Object.entries(policy.overrides).map(([k, v]) => [k, _clamp(v)]))
+      : undefined,
+  };
+}
+
+export function getSamplingPolicy(signal: string): SamplingPolicy {
+  _validateSignal(signal);
+  const _policy = _policies[signal] ?? DEFAULT_POLICY;
+  return {
+    defaultRate: _policy.defaultRate,
+    overrides: _policy.overrides ? { ..._policy.overrides } : undefined,
+  };
+}
+
+export function shouldSample(signal: string, key?: string): boolean {
+  _validateSignal(signal);
+  const _policy = _policies[signal] ?? DEFAULT_POLICY;
+  const overrides = _policy.overrides;
+  const lookupKey = key ?? signal;
+  const rate = overrides && lookupKey in overrides ? overrides[lookupKey] : _policy.defaultRate;
+  const clamped = _clamp(rate);
+  // Stryker disable next-line ConditionalExpression,EqualityOperator: equivalent mutant — Math.random() in [0,1) so boundary is not observable
+  if (clamped <= 0) return false;
+  // Stryker disable next-line ConditionalExpression,EqualityOperator: equivalent mutant — Math.random() in [0,1) so boundary is not observable
+  if (clamped >= 1) return true;
+  // Stryker disable next-line EqualityOperator: Math.random() is in [0,1) so < 1.0 and <= 1.0 are equivalent (random never equals 1.0)
+  return Math.random() < clamped;
+}
+
+export function _resetSamplingForTests(): void {
+  _policies = {};
+}

package/src/sanitize.ts

@@ -0,0 +1,8 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Re-exports sanitize() and DEFAULT_SANITIZE_FIELDS from pii.ts for backwards compatibility.
+ * New code should import from './pii' directly.
+ */
+export { sanitize, DEFAULT_SANITIZE_FIELDS } from './pii';

package/src/schema.ts

@@ -0,0 +1,135 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Event schema validation — mirrors Python provide.telemetry.schema.events.
+ */
+
+import { getConfig } from './config';
+import { TelemetryError } from './exceptions';
+
+export class EventSchemaError extends TelemetryError {
+  constructor(message?: string) {
+    super(message);
+    this.name = 'EventSchemaError';
+  }
+}
+
+const SEGMENT_RE = /^[a-z][a-z0-9_]*$/;
+const MIN_SEGMENTS = 3;
+const MAX_SEGMENTS = 5;
+
+/**
+ * Structured event record returned by event().
+ * Fields spread directly into pino log objects.
+ */
+export interface EventRecord {
+  event: string;
+  domain: string;
+  action: string;
+  resource?: string;
+  status: string;
+}
+
+/**
+ * Build a structured EventRecord from 3 (DAS) or 4 (DARS) segments.
+ *
+ * In strict mode: validates each segment matches /^[a-z][a-z0-9_]*$/.
+ *
+ * Usage: `log.info({ ...event('auth', 'login', 'success'), userId: '123' })`
+ */
+export function event(...segments: string[]): EventRecord {
+  if (segments.length !== 3 && segments.length !== 4) {
+    throw new EventSchemaError(`event() requires 3 or 4 segments (DA[R]S), got ${segments.length}`);
+  }
+
+  const strict = getConfig().strictSchema;
+  if (strict) {
+    for (const seg of segments) {
+      if (!SEGMENT_RE.test(seg)) {
+        throw new EventSchemaError(`segment '${seg}' does not match pattern ^[a-z][a-z0-9_]*$`);
+      }
+    }
+  }
+
+  const name = segments.join('.');
+
+  if (segments.length === 3) {
+    return { event: name, domain: segments[0], action: segments[1], status: segments[2] };
+  }
+  return {
+    event: name,
+    domain: segments[0],
+    action: segments[1],
+    resource: segments[2],
+    status: segments[3],
+  };
+}
+
+/**
+ * Build a dot-joined event name string from segments.
+ * In strict mode (default): enforces 3–5 segments, each matching /^[a-z][a-z0-9_]*$/.
+ * In relaxed mode: requires at least 1 segment, skips count and format checks.
+ */
+export function eventName(...segments: string[]): string {
+  if (segments.length === 0) {
+    // Stryker disable next-line StringLiteral: error message content doesn't affect behavior
+    throw new EventSchemaError(`expected ${MIN_SEGMENTS}-${MAX_SEGMENTS} segments, got 0`);
+  }
+  const strict = getConfig().strictSchema;
+  if (strict) {
+    if (segments.length < MIN_SEGMENTS || segments.length > MAX_SEGMENTS) {
+      throw new EventSchemaError(
+        `expected ${MIN_SEGMENTS}-${MAX_SEGMENTS} segments, got ${segments.length}`,
+      );
+    }
+    // Stryker disable next-line EqualityOperator: segments[length] is undefined; SEGMENT_RE.test('undefined') returns true so no extra throw — equivalent
+    for (let i = 0; i < segments.length; i++) {
+      if (!SEGMENT_RE.test(segments[i])) {
+        // Stryker disable next-line StringLiteral
+        throw new EventSchemaError(`invalid event segment: segment[${i}]=${segments[i]}`);
+      }
+    }
+  }
+  return segments.join('.');
+}
+
+/**
+ * Validate an already-assembled event name string.
+ * In strict mode (default), enforces 3–5 dot-separated lowercase segments.
+ * In relaxed mode, only checks that each segment is non-empty.
+ */
+export function validateEventName(name: string, strict: boolean = true): void {
+  const segments = name.split('.');
+  if (strict) {
+    if (segments.length < MIN_SEGMENTS || segments.length > MAX_SEGMENTS) {
+      // Stryker disable next-line StringLiteral
+      throw new EventSchemaError(
+        `expected ${MIN_SEGMENTS}-${MAX_SEGMENTS} segments, got ${segments.length}`,
+      );
+    }
+    // Stryker disable next-line EqualityOperator: same as above — undefined segment passes SEGMENT_RE
+    for (let i = 0; i < segments.length; i++) {
+      if (!SEGMENT_RE.test(segments[i])) {
+        // Stryker disable next-line StringLiteral
+        throw new EventSchemaError(`invalid event segment: segment[${i}]=${segments[i]}`);
+      }
+    }
+  } else {
+    // Stryker disable next-line ConditionalExpression: an empty input 'split' always has length >= 1; the `< 1` check is never triggered and is unreachable
+    if (segments.length < 1 || segments.some((s) => s.length === 0)) {
+      throw new EventSchemaError('event name must have at least one non-empty segment');
+    }
+  }
+}
+
+/**
+ * Verify that all required keys are present in obj.
+ * Throws EventSchemaError listing the missing keys.
+ */
+export function validateRequiredKeys(obj: Record<string, unknown>, keys: string[]): void {
+  const missing = keys.filter((k) => !(k in obj));
+  if (missing.length > 0) {
+    throw new EventSchemaError(`missing required keys: ${missing.sort().join(', ')}`);
+  }
+}

package/src/shutdown.ts

@@ -0,0 +1,18 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * shutdownTelemetry — flushes and shuts down any OTEL providers registered by
+ * registerOtelProviders. Safe to call before process exit or on hot-reload.
+ *
+ * Uses Promise.allSettled so a failure in one provider's forceFlush/shutdown
+ * does not prevent the others from draining.
+ */
+
+import { _getRegisteredProviders } from './runtime';
+
+export async function shutdownTelemetry(): Promise<void> {
+  const providers = _getRegisteredProviders();
+  await Promise.allSettled(providers.map((p) => p.forceFlush?.() ?? Promise.resolve()));
+  await Promise.allSettled(providers.map((p) => p.shutdown?.() ?? Promise.resolve()));
+}