@provide-io/telemetry 0.2.2

package/dist/resilience.js

@@ -0,0 +1,183 @@
+// 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) {
+        super(message);
+        this.name = 'TelemetryTimeoutError';
+    }
+}
+const DEFAULT_POLICY = {
+    retries: 0,
+    backoffMs: 0,
+    timeoutMs: 10000,
+    failOpen: true,
+};
+export const CIRCUIT_BREAKER_THRESHOLD = 3;
+export const CIRCUIT_BASE_COOLDOWN_MS = 30000;
+const CIRCUIT_MAX_COOLDOWN_MS = 1024000;
+// Stryker disable next-line ObjectLiteral
+let _policies = {};
+// Stryker disable next-line ObjectLiteral
+export const _consecutiveTimeouts = { logs: 0, traces: 0, metrics: 0 };
+// Stryker disable next-line ObjectLiteral
+export const _circuitTrippedAt = { logs: 0, traces: 0, metrics: 0 };
+// Stryker disable next-line ObjectLiteral
+export const _openCount = { 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 = {
+    logs: false,
+    traces: false,
+    metrics: false,
+};
+/* Stryker restore BooleanLiteral */
+export function setExporterPolicy(signal, policy) {
+    _policies[signal] = { ...DEFAULT_POLICY, ...policy };
+}
+export function getExporterPolicy(signal) {
+    return { ...(_policies[signal] ?? DEFAULT_POLICY) };
+}
+// Stryker disable next-line BlockStatement
+function _sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function _withTimeout(fn, timeoutMs) {
+    // Stryker disable next-line ConditionalExpression,EqualityOperator
+    if (timeoutMs <= 0)
+        return fn();
+    return new Promise((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) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+export async function runWithResilience(signal, fn) {
+    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 = 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 function getCircuitState(signal) {
+    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() {
+    _policies = {};
+    for (const k of ['logs', 'traces', 'metrics']) {
+        _consecutiveTimeouts[k] = 0;
+        _circuitTrippedAt[k] = 0;
+        _openCount[k] = 0;
+        _halfOpenProbing[k] = false;
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Runtime reconfiguration helpers.
+ * Mirrors Python provide.telemetry.runtime.
+ */
+import { type RuntimeOverrides, type TelemetryConfig } from './config';
+/** Minimal interface for providers that can be flushed and shut down cleanly. */
+export interface ShutdownableProvider {
+    forceFlush?(): Promise<void>;
+    shutdown?(): Promise<void>;
+}
+/** Store the live providers so shutdownTelemetry can flush and drain them. */
+export declare function _storeRegisteredProviders(providers: ShutdownableProvider[]): void;
+/** Return the currently registered providers (snapshot). */
+export declare function _getRegisteredProviders(): ShutdownableProvider[];
+/** Called by registerOtelProviders once providers are live. */
+export declare function _markProvidersRegistered(): void;
+/** Return true if OTEL providers have been registered. */
+export declare function _areProvidersRegistered(): boolean;
+/** Return the active runtime config (or env-derived defaults if none set). */
+export declare function getRuntimeConfig(): Readonly<TelemetryConfig>;
+/** Merge hot-reloadable overrides into the active config and re-apply policies. */
+export declare function updateRuntimeConfig(overrides: RuntimeOverrides): void;
+/** Reload config from env vars and apply only hot-reloadable fields. */
+export declare function reloadRuntimeFromEnv(): void;
+/**
+ * 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 declare function reconfigureTelemetry(config: Partial<TelemetryConfig>): void;
+export declare function _resetRuntimeForTests(): void;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EAGrB,MAAM,UAAU,CAAC;AAElB,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAQD,8EAA8E;AAC9E,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,oBAAoB,EAAE,GAAG,IAAI,CAEjF;AAED,4DAA4D;AAC5D,wBAAgB,uBAAuB,IAAI,oBAAoB,EAAE,CAEhE;AAED,+DAA+D;AAC/D,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED,0DAA0D;AAC1D,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD;AAWD,8EAA8E;AAC9E,wBAAgB,gBAAgB,IAAI,QAAQ,CAAC,eAAe,CAAC,CAG5D;AAED,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAUrE;AAWD,wEAAwE;AACxE,wBAAgB,oBAAoB,IAAI,IAAI,CA0C3C;AAQD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAuB3E;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C"}

package/dist/runtime.js

@@ -0,0 +1,133 @@
+// 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 { configFromEnv, setupTelemetry, } from './config';
+let _activeConfig = 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 = [];
+/** Store the live providers so shutdownTelemetry can flush and drain them. */
+export function _storeRegisteredProviders(providers) {
+    _registeredProviders = providers;
+}
+/** Return the currently registered providers (snapshot). */
+export function _getRegisteredProviders() {
+    return [..._registeredProviders];
+}
+/** Called by registerOtelProviders once providers are live. */
+export function _markProvidersRegistered() {
+    _providersRegistered = true;
+}
+/** Return true if OTEL providers have been registered. */
+export function _areProvidersRegistered() {
+    return _providersRegistered;
+}
+function deepFreeze(obj) {
+    for (const val of Object.values(obj)) {
+        if (typeof val === 'object' && val !== null && !Object.isFrozen(val)) {
+            deepFreeze(val);
+        }
+    }
+    return Object.freeze(obj);
+}
+/** Return the active runtime config (or env-derived defaults if none set). */
+export function getRuntimeConfig() {
+    const cfg = _activeConfig ?? configFromEnv();
+    return deepFreeze({ ...cfg });
+}
+/** Merge hot-reloadable overrides into the active config and re-apply policies. */
+export function updateRuntimeConfig(overrides) {
+    const base = _activeConfig ?? configFromEnv();
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value !== undefined) {
+            merged[key] = value;
+        }
+    }
+    _activeConfig = merged;
+    setupTelemetry(_activeConfig);
+}
+const _COLD_FIELDS = [
+    'serviceName',
+    'environment',
+    'version',
+    'otelEnabled',
+    'otlpEndpoint',
+    'otlpHeaders',
+];
+/** Reload config from env vars and apply only hot-reloadable fields. */
+export function reloadRuntimeFromEnv() {
+    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 = {
+        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 = [
+    '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) {
+    const current = getRuntimeConfig();
+    const proposed = { ...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() {
+    _activeConfig = null;
+    _providersRegistered = false;
+    _registeredProviders = [];
+}

package/dist/sampling.d.ts

@@ -0,0 +1,9 @@
+export interface SamplingPolicy {
+    defaultRate: number;
+    overrides?: Record<string, number>;
+}
+export declare function setSamplingPolicy(signal: string, policy: SamplingPolicy): void;
+export declare function getSamplingPolicy(signal: string): SamplingPolicy;
+export declare function shouldSample(signal: string, key?: string): boolean;
+export declare function _resetSamplingForTests(): void;
+//# sourceMappingURL=sampling.d.ts.map

package/dist/sampling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.d.ts","sourceRoot":"","sources":["../src/sampling.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAmBD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI,CAQ9E;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAOhE;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAalE;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/sampling.js

@@ -0,0 +1,53 @@
+// 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';
+const DEFAULT_POLICY = { defaultRate: 1.0 };
+let _policies = {};
+const VALID_SIGNALS = new Set(['logs', 'traces', 'metrics']);
+function _validateSignal(signal) {
+    if (!VALID_SIGNALS.has(signal)) {
+        throw new ConfigurationError(`unknown signal "${signal}", expected one of [logs, metrics, traces]`);
+    }
+}
+function _clamp(rate) {
+    return Math.max(0, Math.min(1, rate));
+}
+export function setSamplingPolicy(signal, policy) {
+    _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) {
+    _validateSignal(signal);
+    const _policy = _policies[signal] ?? DEFAULT_POLICY;
+    return {
+        defaultRate: _policy.defaultRate,
+        overrides: _policy.overrides ? { ..._policy.overrides } : undefined,
+    };
+}
+export function shouldSample(signal, key) {
+    _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() {
+    _policies = {};
+}

package/dist/sanitize.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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';
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,OAAO,EAAE,QAAQ,EAAE,uBAAuB,EAAE,MAAM,OAAO,CAAC"}

package/dist/sanitize.js

@@ -0,0 +1,7 @@
+// 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/dist/schema.d.ts

@@ -0,0 +1,41 @@
+import { TelemetryError } from './exceptions';
+export declare class EventSchemaError extends TelemetryError {
+    constructor(message?: string);
+}
+/**
+ * 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 declare function event(...segments: string[]): EventRecord;
+/**
+ * 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 declare function eventName(...segments: string[]): string;
+/**
+ * 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 declare function validateEventName(name: string, strict?: boolean): void;
+/**
+ * Verify that all required keys are present in obj.
+ * Throws EventSchemaError listing the missing keys.
+ */
+export declare function validateRequiredKeys(obj: Record<string, unknown>, keys: string[]): void;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,qBAAa,gBAAiB,SAAQ,cAAc;gBACtC,OAAO,CAAC,EAAE,MAAM;CAI7B;AAMD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,WAAW,CA0BxD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAqBvD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,OAAc,GAAG,IAAI,CAsB5E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAKvF"}

package/dist/schema.js

@@ -0,0 +1,109 @@
+// 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) {
+        super(message);
+        this.name = 'EventSchemaError';
+    }
+}
+const SEGMENT_RE = /^[a-z][a-z0-9_]*$/;
+const MIN_SEGMENTS = 3;
+const MAX_SEGMENTS = 5;
+/**
+ * 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) {
+    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) {
+    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, strict = true) {
+    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, keys) {
+    const missing = keys.filter((k) => !(k in obj));
+    if (missing.length > 0) {
+        throw new EventSchemaError(`missing required keys: ${missing.sort().join(', ')}`);
+    }
+}

package/dist/shutdown.d.ts

@@ -0,0 +1,2 @@
+export declare function shutdownTelemetry(): Promise<void>;
+//# sourceMappingURL=shutdown.d.ts.map

package/dist/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../src/shutdown.ts"],"names":[],"mappings":"AAaA,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAIvD"}

package/dist/shutdown.js

@@ -0,0 +1,15 @@
+// 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() {
+    const providers = _getRegisteredProviders();
+    await Promise.allSettled(providers.map((p) => p.forceFlush?.() ?? Promise.resolve()));
+    await Promise.allSettled(providers.map((p) => p.shutdown?.() ?? Promise.resolve()));
+}

package/dist/slo.d.ts

@@ -0,0 +1,25 @@
+export declare function recordRedMetrics(opts: {
+    route: string;
+    method: string;
+    statusCode: number;
+    durationMs: number;
+}): void;
+export declare function recordUseMetrics(opts: {
+    resource: string;
+    utilization: number;
+    unit?: string;
+}): void;
+export interface ErrorClassification {
+    errorType: 'server' | 'client' | 'timeout' | 'unknown';
+    errorCode: number;
+    errorName: string;
+    category: 'server_error' | 'client_error' | 'timeout' | 'unknown';
+    severity: 'critical' | 'warning' | 'info' | 'unknown';
+    'error.type': string;
+    'error.category': string;
+    'error.severity': string;
+    'http.status_code': string;
+}
+export declare function classifyError(excName: string, statusCode: number): ErrorClassification;
+export declare function _resetSloForTests(): void;
+//# sourceMappingURL=slo.d.ts.map

package/dist/slo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slo.d.ts","sourceRoot":"","sources":["../src/slo.ts"],"names":[],"mappings":"AAiDA,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,IAAI,CAgBP;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,IAAI,CAIP;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,cAAc,GAAG,cAAc,GAAG,SAAS,GAAG,SAAS,CAAC;IAClE,QAAQ,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IAEtD,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,mBAAmB,CAsDtF;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC"}