@provide-io/telemetry 0.2.2

package/README.md

@@ -0,0 +1,247 @@
+# @provide-io/telemetry
+
+Structured logging + OpenTelemetry traces and metrics for TypeScript — feature parity with the [`provide-telemetry`](https://pypi.org/p/provide-telemetry) Python package.
+
+## Install
+
+```bash
+npm install @provide-io/telemetry
+```
+
+### Optional OTEL peer dependencies
+
+To export traces and metrics to an OTLP endpoint (e.g. OpenObserve, Jaeger, Tempo):
+
+```bash
+npm install \
+  @opentelemetry/sdk-trace-base \
+  @opentelemetry/sdk-metrics \
+  @opentelemetry/resources \
+  @opentelemetry/exporter-trace-otlp-http \
+  @opentelemetry/exporter-metrics-otlp-http
+```
+
+All five are optional — the library degrades gracefully to no-op providers when they are absent.
+
+## Quick start
+
+```typescript
+import { setupTelemetry, getConfig, getLogger, registerOtelProviders, shutdownTelemetry } from '@provide-io/telemetry';
+
+// Call once at app startup.
+setupTelemetry({
+  serviceName: 'my-app',
+  environment: 'production',
+  version: '1.0.0',
+  logLevel: 'info',
+  logFormat: 'json',
+  otelEnabled: true,
+  otlpEndpoint: 'http://localhost:4318',
+  otlpHeaders: { Authorization: 'Basic ...' },
+});
+
+// Activate OTLP exporters (requires peer deps above).
+await registerOtelProviders(getConfig());
+
+const log = getLogger('api');
+log.info({ event: 'request.received.ok', method: 'GET', path: '/health', status: 200 });
+
+// On shutdown — flushes and drains all OTel providers.
+await shutdownTelemetry();
+```
+
+## API reference
+
+### Setup
+
+| Export | Description |
+|--------|-------------|
+| `setupTelemetry(config)` | Configure the library. Idempotent — safe to call multiple times. |
+| `getConfig()` | Return the current `TelemetryConfig`. |
+| `configFromEnv()` | Build config from environment variables (see [Configuration](#configuration)). |
+| `registerOtelProviders(cfg)` | Wire OTLP trace + metrics exporters. Call after `setupTelemetry`. |
+| `shutdownTelemetry()` | Flush and shut down all registered OTel providers. |
+
+### Logging
+
+```typescript
+import { getLogger } from '@provide-io/telemetry';
+
+const log = getLogger('my-module');
+log.debug({ event: 'cache.miss.ok', key: 'user:42' });
+log.info({ event: 'request.complete.ok', status: 200, duration_ms: 14 });
+log.warn({ event: 'retry.attempt.warn', attempt: 2 });
+log.error({ event: 'db.query.error', error: err.message });
+```
+
+Event names follow the DA(R)S pattern: 3 segments (`domain.action.status`) or 4 segments (`domain.action.resource.status`).
+
+### Tracing
+
+```typescript
+import { withTrace, getActiveTraceIds, setTraceContext } from '@provide-io/telemetry';
+
+const result = await withTrace('my.operation.ok', async () => {
+  const { trace_id, span_id } = getActiveTraceIds();
+  // trace_id / span_id are available here and in any log emitted inside
+  return doWork();
+});
+```
+
+### Metrics
+
+```typescript
+import { counter, gauge, histogram } from '@provide-io/telemetry';
+
+const requests = counter('http.requests', { unit: '1', description: 'Total HTTP requests' });
+requests.add(1, { method: 'GET', status: '200' });
+
+const latency = histogram('http.duration', { unit: 'ms' });
+latency.record(42, { route: '/api/users' });
+```
+
+### Context binding
+
+```typescript
+import { bindContext, runWithContext, clearContext } from '@provide-io/telemetry';
+
+bindContext({ request_id: 'req-abc', user_id: 7 });
+// All log calls in this async context will include these fields automatically.
+clearContext();
+
+// Scoped — context is automatically cleaned up after fn resolves.
+await runWithContext({ trace_id: '...' }, async () => { /* ... */ });
+```
+
+### Session correlation
+
+```typescript
+import { bindSessionContext, getSessionId, clearSessionContext } from '@provide-io/telemetry';
+
+bindSessionContext('sess-abc-123');
+// All logs and traces now include session_id automatically.
+const sid = getSessionId(); // 'sess-abc-123'
+clearSessionContext();
+```
+
+### Error fingerprinting
+
+```typescript
+import { computeErrorFingerprint } from '@provide-io/telemetry';
+
+try {
+  throw new Error('connection refused');
+} catch (e) {
+  const err = e as Error;
+  const fp = computeErrorFingerprint(err.constructor.name, err.stack);
+  // fp: 12-char hex digest, stable across deploys — use for dedup and alert grouping.
+}
+```
+
+### W3C trace propagation
+
+```typescript
+import { extractW3cContext, bindPropagationContext } from '@provide-io/telemetry';
+
+// In an HTTP handler — extract incoming traceparent/tracestate.
+const ctx = extractW3cContext(req.headers);
+bindPropagationContext(ctx);
+```
+
+### PII sanitization
+
+```typescript
+import { sanitize, registerPiiRule } from '@provide-io/telemetry';
+
+// Built-in: redacts password, token, secret, authorization, api_key, ...
+const obj = { user: 'alice', password: 'hunter2' }; // pragma: allowlist secret
+sanitize(obj);
+// obj is now { user: 'alice', password: '[REDACTED]' }
+
+// Custom rule (dot-separated path; '*' as wildcard segment)
+registerPiiRule({ path: 'user.ssn', mode: 'redact' });
+```
+
+### Health snapshot
+
+```typescript
+import { getHealthSnapshot } from '@provide-io/telemetry';
+
+const snap = getHealthSnapshot();
+// snap.export_failures_logs, snap.queue_depth_traces, ...
+```
+
+## React integration
+
+Requires React 18+ as a peer dependency.
+
+```typescript
+import { useTelemetryContext, TelemetryErrorBoundary } from '@provide-io/telemetry/react';
+```
+
+### `useTelemetryContext(values)`
+
+Binds key/value pairs into telemetry context for the lifetime of a component. Automatically cleans up on unmount and re-runs when values change (compared by content, not reference).
+
+```tsx
+function UserDashboard({ userId }: { userId: string }) {
+  useTelemetryContext({ user_id: userId, page: 'dashboard' });
+  return <Dashboard />;
+}
+```
+
+### `TelemetryErrorBoundary`
+
+React error boundary that auto-logs caught render errors via `getLogger('react.error_boundary')`. Accepts a static fallback or a render-prop receiving the error and a reset callback.
+
+```tsx
+<TelemetryErrorBoundary
+  fallback={(error, reset) => <ErrorPage error={error} onRetry={reset} />}
+  onError={(error, info) => reportToSentry(error, info)}
+>
+  <App />
+</TelemetryErrorBoundary>
+```
+
+## Browser support
+
+The library is browser-compatible via conditional exports. OpenTelemetry providers become no-ops in browser environments, so no server-only imports leak into client bundles. No polyfills are required for modern browsers (ES2020+).
+
+Browser-specific options in `setupTelemetry()`:
+
+| Option | Effect |
+|--------|--------|
+| `captureToWindow: true` | Buffers structured logs to `window.__pinoLogs` for devtools inspection |
+| `consoleOutput: true` | Mirrors log output to `console.debug` / `console.log` / `console.warn` / `console.error` |
+
+## Configuration
+
+All options can be set programmatically via `setupTelemetry()` or via environment variables:
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `PROVIDE_TELEMETRY_SERVICE_NAME` | `provide-service` | Service identity |
+| `PROVIDE_ENV` | `development` | Deployment environment |
+| `PROVIDE_VERSION` | `unknown` | Service version |
+| `PROVIDE_LOG_LEVEL` | `info` | Log level: `debug` / `info` / `warn` / `error` |
+| `PROVIDE_LOG_FORMAT` | `json` | Output format: `json` / `pretty` |
+| `PROVIDE_TRACE_ENABLED` | `false` | Enable OTLP export |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` | OTLP base endpoint |
+| `OTEL_EXPORTER_OTLP_HEADERS` | — | Comma-separated `key=value` auth headers |
+
+### Pretty renderer
+
+Set `logFormat: 'pretty'` (or `PROVIDE_LOG_FORMAT=pretty`) for human-readable colored output during local development. Color support respects `FORCE_COLOR` and `NO_COLOR` environment variables.
+
+```typescript
+setupTelemetry({ logFormat: 'pretty' });
+```
+
+## Requirements
+
+- Node.js ≥ 18
+- TypeScript ≥ 5 (built with TypeScript 6)
+
+## License
+
+Apache-2.0. See [LICENSE](../LICENSES/Apache-2.0.txt).

package/dist/backpressure.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Bounded queue controls for telemetry signal paths.
+ * Mirrors Python provide.telemetry.backpressure.
+ */
+export interface QueuePolicy {
+    maxLogs: number;
+    maxTraces: number;
+    maxMetrics: number;
+}
+export interface QueueTicket {
+    signal: 'logs' | 'traces' | 'metrics';
+    token: number;
+}
+export declare function setQueuePolicy(policy: Partial<QueuePolicy>): void;
+export declare function getQueuePolicy(): QueuePolicy;
+export declare function tryAcquire(signal: QueueTicket['signal']): QueueTicket | null;
+export declare function release(ticket: QueueTicket): void;
+export declare function _resetBackpressureForTests(): void;
+//# sourceMappingURL=backpressure.d.ts.map

package/dist/backpressure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backpressure.d.ts","sourceRoot":"","sources":["../src/backpressure.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IACtC,KAAK,EAAE,MAAM,CAAC;CACf;AAYD,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,CAEjE;AAED,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAQD,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,GAAG,WAAW,GAAG,IAAI,CAW5E;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAKjD;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAIjD"}

package/dist/backpressure.js

@@ -0,0 +1,51 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+const DEFAULT_POLICY = { maxLogs: 0, maxTraces: 0, maxMetrics: 0 };
+let _policy = { ...DEFAULT_POLICY };
+let _tokenCounter = 1;
+const _acquired = new Map([
+    ['logs', new Set()],
+    ['traces', new Set()],
+    ['metrics', new Set()],
+]);
+export function setQueuePolicy(policy) {
+    _policy = { ..._policy, ...policy };
+}
+export function getQueuePolicy() {
+    return { ..._policy };
+}
+function _maxFor(signal) {
+    if (signal === 'logs')
+        return _policy.maxLogs;
+    if (signal === 'traces')
+        return _policy.maxTraces;
+    return _policy.maxMetrics;
+}
+export function tryAcquire(signal) {
+    const max = _maxFor(signal);
+    if (max <= 0)
+        return { signal, token: 0 };
+    const set = _acquired.get(signal);
+    // Stryker disable next-line ConditionalExpression: defensive guard — _acquired is initialized with all three signal keys, so get() never returns undefined
+    /* v8 ignore next */
+    if (!set)
+        return null;
+    if (set.size >= max)
+        return null;
+    const token = _tokenCounter++;
+    set.add(token);
+    return { signal, token };
+}
+export function release(ticket) {
+    // Stryker disable next-line ConditionalExpression: token=0 is the unlimited-queue sentinel; delete(0) from set is always a no-op
+    if (ticket.token === 0)
+        return;
+    // Stryker disable next-line OptionalChaining: signal is always a key in _acquired (initialized in the Map constructor)
+    _acquired.get(ticket.signal)?.delete(ticket.token);
+}
+export function _resetBackpressureForTests() {
+    _policy = { ...DEFAULT_POLICY };
+    _tokenCounter = 1;
+    for (const set of _acquired.values())
+        set.clear();
+}

package/dist/cardinality.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Attribute cardinality guardrails with TTL pruning.
+ * Mirrors Python provide.telemetry.cardinality.
+ */
+export interface CardinalityLimit {
+    maxValues: number;
+    ttlSeconds: number;
+}
+export declare const OVERFLOW_VALUE = "__overflow__";
+export declare function registerCardinalityLimit(key: string, limit: CardinalityLimit): void;
+export declare function getCardinalityLimits(): Map<string, CardinalityLimit>;
+export declare function clearCardinalityLimits(): void;
+export declare function guardAttributes(attrs: Record<string, string>): Record<string, string>;
+export declare function _resetCardinalityForTests(): void;
+//# sourceMappingURL=cardinality.d.ts.map

package/dist/cardinality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardinality.d.ts","sourceRoot":"","sources":["../src/cardinality.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,cAAc,iBAAiB,CAAC;AAQ7C,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAOnF;AAED,wBAAgB,oBAAoB,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAEpE;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAI7C;AAcD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0BrF;AAED,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/cardinality.js

@@ -0,0 +1,69 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+export const OVERFLOW_VALUE = '__overflow__';
+const _limits = new Map();
+/** key → (value → expiresAt timestamp ms) */
+const _seen = new Map();
+const _lastPrune = new Map();
+const PRUNE_INTERVAL_MS = 5000;
+export function registerCardinalityLimit(key, limit) {
+    _limits.set(key, {
+        maxValues: Math.max(1, limit.maxValues),
+        ttlSeconds: Math.max(1, limit.ttlSeconds),
+    });
+    // Stryker disable next-line ConditionalExpression: equivalent mutant — guardAttributes line 64 has a ?? fallback that compensates if _seen entry is absent
+    if (!_seen.has(key))
+        _seen.set(key, new Map());
+}
+export function getCardinalityLimits() {
+    return new Map(_limits);
+}
+export function clearCardinalityLimits() {
+    _limits.clear();
+    _seen.clear();
+    _lastPrune.clear();
+}
+function _pruneExpired(key, now) {
+    const limit = _limits.get(key);
+    const seen = _seen.get(key);
+    // Stryker disable next-line ConditionalExpression,LogicalOperator: defensive guard — _pruneExpired is only called from guardAttributes after _limits.get(key) succeeds
+    /* v8 ignore next 2 */
+    if (!limit || !seen)
+        return;
+    const threshold = now - limit.ttlSeconds * 1000;
+    for (const [value, seenAt] of seen) {
+        if (seenAt < threshold)
+            seen.delete(value);
+    }
+}
+export function guardAttributes(attrs) {
+    const now = Date.now();
+    const result = { ...attrs };
+    for (const [key, value] of Object.entries(result)) {
+        const limit = _limits.get(key);
+        if (!limit)
+            continue;
+        const lastPrune = _lastPrune.get(key) ?? 0;
+        // Stryker disable next-line ConditionalExpression,ArithmeticOperator: early prune is a no-op (only deletes expired values); now+lastPrune equivalent because fresh values are always within TTL
+        if (now - lastPrune >= PRUNE_INTERVAL_MS) {
+            _pruneExpired(key, now);
+            _lastPrune.set(key, now);
+        }
+        /* v8 ignore next */
+        const seen = _seen.get(key) ?? new Map();
+        if (seen.has(value)) {
+            seen.set(value, now);
+            continue;
+        }
+        if (seen.size >= limit.maxValues) {
+            result[key] = OVERFLOW_VALUE;
+            continue;
+        }
+        seen.set(value, now);
+        _seen.set(key, seen);
+    }
+    return result;
+}
+export function _resetCardinalityForTests() {
+    clearCardinalityLimits();
+}

package/dist/classification.d.ts

@@ -0,0 +1,29 @@
+/** Data classification labels. */
+export type DataClass = 'PUBLIC' | 'INTERNAL' | 'PII' | 'PHI' | 'PCI' | 'SECRET';
+/** Maps a glob pattern to a DataClass label. */
+export interface ClassificationRule {
+    pattern: string;
+    classification: DataClass;
+}
+/** Defines the action to take per DataClass. */
+export interface ClassificationPolicy {
+    PUBLIC: string;
+    INTERNAL: string;
+    PII: string;
+    PHI: string;
+    PCI: string;
+    SECRET: string;
+}
+/**
+ * Register classification rules and install the classification hook on the PII engine.
+ */
+export declare function registerClassificationRules(rules: ClassificationRule[]): void;
+/** Replace the current classification policy. */
+export declare function setClassificationPolicy(policy: ClassificationPolicy): void;
+/** Return the current classification policy. */
+export declare function getClassificationPolicy(): ClassificationPolicy;
+/** Return the DataClass label for a key if a rule matches, else null. */
+export declare function _classifyField(key: string, _value: unknown): string | null;
+/** Reset all classification state and remove the hook (test helper). */
+export declare function resetClassificationForTests(): void;
+//# sourceMappingURL=classification.d.ts.map

package/dist/classification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification.d.ts","sourceRoot":"","sources":["../src/classification.ts"],"names":[],"mappings":"AAYA,kCAAkC;AAClC,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEjF,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,SAAS,CAAC;CAC3B;AAED,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAwBD;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,kBAAkB,EAAE,GAAG,IAAI,CAG7E;AAED,iDAAiD;AACjD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAE1E;AAED,gDAAgD;AAChD,wBAAgB,uBAAuB,IAAI,oBAAoB,CAE9D;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAO1E;AAED,wEAAwE;AACxE,wBAAgB,2BAA2B,IAAI,IAAI,CAIlD"}

package/dist/classification.js

@@ -0,0 +1,58 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Data classification engine — strippable governance module.
+ *
+ * Registers a classification hook on the PII engine when rules are configured.
+ * If this file is deleted, the PII engine runs unchanged (hook stays null).
+ */
+import { setClassificationHook } from './pii';
+const _DEFAULT_POLICY = {
+    PUBLIC: 'pass',
+    INTERNAL: 'pass',
+    PII: 'redact',
+    PHI: 'drop',
+    PCI: 'hash',
+    SECRET: 'drop', // pragma: allowlist secret
+};
+// Stryker disable next-line ArrayDeclaration
+const _rules = [];
+let _policy = { ..._DEFAULT_POLICY };
+/**
+ * Convert a glob pattern (supporting * wildcards) to a RegExp.
+ * Only * is treated as a wildcard; all other regex special chars are escaped.
+ */
+function matchGlob(pattern, key) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`).test(key);
+}
+/**
+ * Register classification rules and install the classification hook on the PII engine.
+ */
+export function registerClassificationRules(rules) {
+    _rules.push(...rules);
+    setClassificationHook(_classifyField);
+}
+/** Replace the current classification policy. */
+export function setClassificationPolicy(policy) {
+    _policy = { ...policy };
+}
+/** Return the current classification policy. */
+export function getClassificationPolicy() {
+    return { ..._policy };
+}
+/** Return the DataClass label for a key if a rule matches, else null. */
+export function _classifyField(key, _value) {
+    for (const rule of _rules) {
+        if (matchGlob(rule.pattern, key)) {
+            return rule.classification;
+        }
+    }
+    return null;
+}
+/** Reset all classification state and remove the hook (test helper). */
+export function resetClassificationForTests() {
+    _rules.length = 0;
+    _policy = { ..._DEFAULT_POLICY };
+    setClassificationHook(null);
+}

package/dist/config.d.ts

@@ -0,0 +1,156 @@
+export interface TelemetryConfig {
+    /** Service name injected into every log record. */
+    serviceName: string;
+    /** Deployment environment (e.g. "development", "production"). */
+    environment: string;
+    /** Application version injected into every log record. */
+    version: string;
+    /** Pino log level: trace | debug | info | warn | error. */
+    logLevel: string;
+    /** Output format: "json" (default) or "pretty". */
+    logFormat: 'json' | 'pretty';
+    /** Enable OTEL SDK registration on setupTelemetry(). */
+    otelEnabled: boolean;
+    /** OTLP export endpoint (e.g. "http://localhost:4318"). */
+    otlpEndpoint?: string;
+    /** OTLP headers as key=value pairs. */
+    otlpHeaders?: Record<string, string>;
+    /** Fields whose values are replaced with "[REDACTED]". */
+    sanitizeFields: string[];
+    /** Push every log object into window.__pinoLogs (browser only). */
+    captureToWindow: boolean;
+    /**
+     * Emit logs to browser console via console.debug/log/warn/error.
+     * Default false — use captureToWindow + window.__pinoLogs or OTEL export instead.
+     * Set true during local development for live devtools inspection.
+     */
+    consoleOutput: boolean;
+    /** Enforce strict event name validation (3-5 dot-separated segments). */
+    strictSchema: boolean;
+    /** Keys required on every log record when strictSchema is enabled. */
+    requiredLogKeys: string[];
+    /** Include timestamp in log output. */
+    logIncludeTimestamp: boolean;
+    /** Include caller info in log output. */
+    logIncludeCaller: boolean;
+    /** Enable PII/secret sanitization in logs. */
+    logSanitize: boolean;
+    /** Attach code.filepath / code.lineno attributes to log records. */
+    logCodeAttributes: boolean;
+    /** Per-module log level overrides (e.g. {"provide.server": "DEBUG"}). */
+    logModuleLevels: Record<string, string>;
+    /** Trace sampling rate (0.0–1.0). */
+    traceSampleRate: number;
+    /** Enable metrics collection. */
+    metricsEnabled: boolean;
+    /** Probabilistic sampling rate for logs (0.0–1.0). */
+    samplingLogsRate: number;
+    /** Probabilistic sampling rate for traces (0.0–1.0). */
+    samplingTracesRate: number;
+    /** Probabilistic sampling rate for metrics (0.0–1.0). */
+    samplingMetricsRate: number;
+    /** Max queue size for log export (0 = unbounded). */
+    backpressureLogsMaxsize: number;
+    /** Max queue size for trace export (0 = unbounded). */
+    backpressureTracesMaxsize: number;
+    /** Max queue size for metric export (0 = unbounded). */
+    backpressureMetricsMaxsize: number;
+    /** Max retries for log export. */
+    exporterLogsRetries: number;
+    /** Backoff between log export retries (ms). */
+    exporterLogsBackoffMs: number;
+    /** Timeout for log export (ms). */
+    exporterLogsTimeoutMs: number;
+    /** If true, drop telemetry on export failure instead of crashing. */
+    exporterLogsFailOpen: boolean;
+    /** Max retries for trace export. */
+    exporterTracesRetries: number;
+    /** Backoff between trace export retries (ms). */
+    exporterTracesBackoffMs: number;
+    /** Timeout for trace export (ms). */
+    exporterTracesTimeoutMs: number;
+    /** If true, drop telemetry on export failure instead of crashing. */
+    exporterTracesFailOpen: boolean;
+    /** Max retries for metric export. */
+    exporterMetricsRetries: number;
+    /** Backoff between metric export retries (ms). */
+    exporterMetricsBackoffMs: number;
+    /** Timeout for metric export (ms). */
+    exporterMetricsTimeoutMs: number;
+    /** If true, drop telemetry on export failure instead of crashing. */
+    exporterMetricsFailOpen: boolean;
+    /** Enable RED (Rate/Error/Duration) metrics. */
+    sloEnableRedMetrics: boolean;
+    /** Enable USE (Utilization/Saturation/Errors) metrics. */
+    sloEnableUseMetrics: boolean;
+    /** Maximum recursion depth for PII sanitization of nested objects. */
+    piiMaxDepth: number;
+    /** Max length for any single attribute value. */
+    securityMaxAttrValueLength: number;
+    /** Max number of attributes on a single span/log/metric point. */
+    securityMaxAttrCount: number;
+}
+/**
+ * Hot-reloadable config subset. Only fields that can be changed at runtime
+ * without restarting providers. All fields are optional.
+ */
+export interface RuntimeOverrides {
+    samplingLogsRate?: number;
+    samplingTracesRate?: number;
+    samplingMetricsRate?: number;
+    backpressureLogsMaxsize?: number;
+    backpressureTracesMaxsize?: number;
+    backpressureMetricsMaxsize?: number;
+    exporterLogsRetries?: number;
+    exporterLogsBackoffMs?: number;
+    exporterLogsTimeoutMs?: number;
+    exporterLogsFailOpen?: boolean;
+    exporterTracesRetries?: number;
+    exporterTracesBackoffMs?: number;
+    exporterTracesTimeoutMs?: number;
+    exporterTracesFailOpen?: boolean;
+    exporterMetricsRetries?: number;
+    exporterMetricsBackoffMs?: number;
+    exporterMetricsTimeoutMs?: number;
+    exporterMetricsFailOpen?: boolean;
+    securityMaxAttrValueLength?: number;
+    securityMaxAttrCount?: number;
+    sloEnableRedMetrics?: boolean;
+    sloEnableUseMetrics?: boolean;
+    piiMaxDepth?: number;
+}
+/**
+ * Build a TelemetryConfig from environment variables.
+ * Uses the same env var names as the Python package.
+ * Explicit values passed to setupTelemetry() override env vars.
+ */
+export declare function configFromEnv(): TelemetryConfig;
+/** Return the active TelemetryConfig. */
+export declare function getConfig(): TelemetryConfig;
+/**
+ * Apply parsed config fields to the runtime policy engines (sampling, backpressure, resilience).
+ * Mirrors Python provide.telemetry.runtime.apply_runtime_config.
+ */
+export declare function applyConfigPolicies(cfg: TelemetryConfig): void;
+/**
+ * Configure telemetry. Call once at app startup.
+ * Merges explicit values over the current config (which may include env-derived values).
+ */
+export declare function setupTelemetry(overrides?: Partial<TelemetryConfig>): void;
+/** Reset to defaults (used in tests). */
+export declare function _resetConfig(): void;
+/**
+ * Parse OTLP-style header string "key=value,key2=value2" into a Record.
+ * Keys and values are URL-decoded. Malformed pairs (no '=') and empty keys are skipped.
+ * Values may contain '=' characters (only the first '=' splits key from value).
+ */
+export declare function parseOtlpHeaders(raw: string): Record<string, string>;
+/**
+ * Return a copy of the config with OTLP secrets masked.
+ * Safe to log or serialize — never leaks header values or endpoint credentials.
+ */
+export declare function redactConfig(config: TelemetryConfig): Record<string, unknown>;
+/** Package version — mirrors Python __version__. */
+export declare const version = "0.2.0";
+export declare const __version__ = "0.2.0";
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}