@superblocksteam/telemetry 2.0.173-next.4 → 2.0.174

package/dist-esm/node/metrics-client.js

@@ -0,0 +1,205 @@
+/**
+ * Metrics Client for Node.js Telemetry
+ *
+ * Provides a simple interface for recording metrics via OpenTelemetry.
+ * This is the recommended way to record metrics in services using the telemetry package.
+ */
+/**
+ * Converts Labels to OTEL Attributes.
+ */
+function labelsToAttributes(labels) {
+    if (!labels)
+        return {};
+    const attributes = {};
+    for (const [key, value] of Object.entries(labels)) {
+        attributes[key] = String(value);
+    }
+    return attributes;
+}
+/**
+ * TTL configuration for gauge values.
+ */
+const GAUGE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const GAUGE_MAX_ENTRIES = 10_000; // Max entries per gauge to prevent unbounded growth
+const GAUGE_CLEANUP_INTERVAL_MS = 60 * 1000; // Cleanup every minute
+/**
+ * TTL-based map for gauge values with automatic cleanup.
+ */
+class TTLGaugeMap {
+    ttlMs;
+    maxEntries;
+    entries = new Map();
+    cleanupTimer = null;
+    constructor(ttlMs = GAUGE_TTL_MS, maxEntries = GAUGE_MAX_ENTRIES) {
+        this.ttlMs = ttlMs;
+        this.maxEntries = maxEntries;
+        // Start periodic cleanup
+        this.cleanupTimer = setInterval(() => this.cleanup(), GAUGE_CLEANUP_INTERVAL_MS);
+        // Don't prevent Node.js from exiting
+        this.cleanupTimer.unref();
+    }
+    set(labelsKey, value) {
+        // If at max capacity, remove oldest entry
+        if (this.entries.size >= this.maxEntries && !this.entries.has(labelsKey)) {
+            this.evictOldest();
+        }
+        this.entries.set(labelsKey, {
+            value,
+            updatedAt: Date.now(),
+        });
+    }
+    /**
+     * Gets all non-expired entries.
+     */
+    getAll() {
+        const now = Date.now();
+        const result = new Map();
+        for (const [key, entry] of this.entries) {
+            if (now - entry.updatedAt <= this.ttlMs) {
+                result.set(key, entry.value);
+            }
+        }
+        return result;
+    }
+    /**
+     * Removes expired entries.
+     */
+    cleanup() {
+        const now = Date.now();
+        for (const [key, entry] of this.entries) {
+            if (now - entry.updatedAt > this.ttlMs) {
+                this.entries.delete(key);
+            }
+        }
+    }
+    /**
+     * Evicts the oldest entry when at max capacity.
+     */
+    evictOldest() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.entries) {
+            if (entry.updatedAt < oldestTime) {
+                oldestTime = entry.updatedAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.entries.delete(oldestKey);
+        }
+    }
+    /**
+     * Stops the cleanup timer.
+     */
+    destroy() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+    }
+}
+/**
+ * Metrics client that provides a unified interface for recording OTEL metrics.
+ */
+export class MetricsClient {
+    meter;
+    counters = new Map();
+    histograms = new Map();
+    // Gauges use TTL-based maps to prevent unbounded memory growth
+    gaugeValues = new Map();
+    constructor(meter) {
+        this.meter = meter;
+    }
+    /**
+     * Creates or retrieves a counter and returns a handle.
+     */
+    counter(name, options) {
+        if (!this.counters.has(name)) {
+            this.counters.set(name, this.meter.createCounter(name, options));
+        }
+        const counter = this.counters.get(name);
+        return {
+            inc: (labels, value = 1) => {
+                counter.add(value, labelsToAttributes(labels));
+            },
+        };
+    }
+    /**
+     * Creates or retrieves a gauge and returns a handle.
+     * Note: OTEL gauges are async/observable, so we store the value and emit via callback.
+     * Values are automatically expired after 5 minutes to prevent unbounded memory growth.
+     */
+    gauge(name) {
+        if (!this.gaugeValues.has(name)) {
+            const ttlMap = new TTLGaugeMap();
+            this.gaugeValues.set(name, ttlMap);
+            // Create an observable gauge that reads from the TTL map
+            this.meter.createObservableGauge(name, {}).addCallback((result) => {
+                const ttlMapRef = this.gaugeValues.get(name);
+                if (ttlMapRef) {
+                    // getAll() only returns non-expired entries
+                    for (const [labelsKey, value] of ttlMapRef.getAll()) {
+                        const labels = JSON.parse(labelsKey);
+                        result.observe(value, labelsToAttributes(labels));
+                    }
+                }
+            });
+        }
+        return {
+            set: (labels, value) => {
+                const ttlMap = this.gaugeValues.get(name);
+                const labelsKey = JSON.stringify(labels);
+                ttlMap.set(labelsKey, value);
+            },
+        };
+    }
+    /**
+     * Creates or retrieves a histogram and returns a handle.
+     */
+    histogram(name, options) {
+        if (!this.histograms.has(name)) {
+            this.histograms.set(name, this.meter.createHistogram(name, options
+                ? {
+                    ...(options.bucketBoundaries
+                        ? {
+                            advice: {
+                                explicitBucketBoundaries: options.bucketBoundaries,
+                            },
+                        }
+                        : {}),
+                    ...(options.description
+                        ? { description: options.description }
+                        : {}),
+                    ...(options.unit ? { unit: options.unit } : {}),
+                }
+                : undefined));
+        }
+        const histogram = this.histograms.get(name);
+        return {
+            observe: (labels, value) => {
+                histogram.record(value, labelsToAttributes(labels));
+            },
+        };
+    }
+    /**
+     * Increments a counter by name (creates if not exists). `options` is only
+     * applied on the instrument's first registration; see `counter`.
+     */
+    incCounter(name, labels, value = 1, options) {
+        this.counter(name, options).inc(labels, value);
+    }
+    /**
+     * Sets a gauge value by name (creates if not exists).
+     */
+    setGauge(name, labels, value) {
+        this.gauge(name).set(labels, value);
+    }
+    /**
+     * Observes a histogram value by name (creates if not exists). `options` is
+     * only applied on the instrument's first registration; see `histogram`.
+     */
+    observeHistogram(name, labels, value, options) {
+        this.histogram(name, options).observe(labels, value);
+    }
+}
+//# sourceMappingURL=metrics-client.js.map

package/dist-esm/node/metrics-client.js.map

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

package/dist-esm/node/safe-logger.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Policy-Aware Safe Logger (Pino Wrapper)
+ *
+ * Wraps a Pino logger to redact forbidden fields (e.g. stack, prompt, code)
+ * from log call arguments so Tier 1 data is not written to stdout/log export.
+ *
+ * @see https://github.com/superblocksteam/engineering/blob/main/projects/o11y-refactor/epics/epic-c4-logging-strategy.md
+ */
+import { type LoggingPolicyConfig } from "./log-processor.js";
+/**
+ * Minimal logger interface compatible with Pino.
+ * Use createSafeLogger(pinoLogger, policy) with a Pino logger instance.
+ */
+export interface SafeLoggerLike {
+    trace(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    fatal(...args: unknown[]): void;
+    child(bindings: Record<string, unknown>): SafeLoggerLike;
+}
+/**
+ * Redact and sanitize a single log argument: key-based (forbidden fields) and
+ * value-based (stack traces, PII, policy redactPatterns). Error instances are
+ * converted to a plain object first. Exported for use by callers (e.g. server
+ * RemoteLogger redactRecord) so stdout and OTLP paths share the same rules.
+ */
+export declare function redactForbiddenFields(arg: unknown, policy: LoggingPolicyConfig): unknown;
+/**
+ * Creates a logger wrapper that redacts policy-forbidden fields from log calls
+ * and applies the policy-effective log level (exportMode + envLevel) so that
+ * both the root and any child loggers respect exportMode (e.g. ERRORS_ONLY → warn floor).
+ *
+ * Use when logging in contexts where output may be exported (e.g. cloud-prem).
+ * Forbidden fields (stack, prompt, code, filePath, etc.) are replaced with
+ * "[REDACTED]" so they never appear in exported logs.
+ *
+ * @param baseLogger - Underlying Pino (or compatible) logger
+ * @param policy - Logging policy (e.g. from getLoggingPolicy(telemetryPolicy))
+ * @param envLevel - Optional env-configured level (e.g. SUPERBLOCKS_SERVER_LOG_LEVEL).
+ *   When provided, base logger level is set from getMinimumPinoLevelFromLoggingPolicy(policy, envLevel)
+ *   so exportMode (e.g. ERRORS_ONLY) is respected; children inherit this level in .child().
+ * @returns A logger that redacts forbidden fields and respects policy level (same interface as baseLogger)
+ *
+ * @example
+ * ```typescript
+ * const policy = getLoggingPolicy(telemetryPolicy);
+ * const safeLogger = createSafeLogger(logger, policy, envs.get('SUPERBLOCKS_SERVER_LOG_LEVEL'));
+ * safeLogger.error({ err, stack: err.stack }, 'Request failed');
+ * // Exported logs see stack: "[REDACTED]"
+ * ```
+ */
+export declare function createSafeLogger<T extends SafeLoggerLike>(baseLogger: T, policy: LoggingPolicyConfig, envLevel?: string): T;
+//# sourceMappingURL=safe-logger.d.ts.map

package/dist-esm/node/safe-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-logger.d.ts","sourceRoot":"","sources":["../../src/node/safe-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAE5B;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChC,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChC,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAAC;CAC1D;AA+BD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAaT;AAsCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,cAAc,EACvD,UAAU,EAAE,CAAC,EACb,MAAM,EAAE,mBAAmB,EAC3B,QAAQ,CAAC,EAAE,MAAM,GAChB,CAAC,CA6EH"}

package/dist-esm/node/safe-logger.js

@@ -0,0 +1,154 @@
+/**
+ * Policy-Aware Safe Logger (Pino Wrapper)
+ *
+ * Wraps a Pino logger to redact forbidden fields (e.g. stack, prompt, code)
+ * from log call arguments so Tier 1 data is not written to stdout/log export.
+ *
+ * @see https://github.com/superblocksteam/engineering/blob/main/projects/o11y-refactor/epics/epic-c4-logging-strategy.md
+ */
+import { sanitizeLogMessageForExport, sanitizeLogRecordForExport, } from "../common/log-sanitizer.js";
+import { getMinimumPinoLevelFromLoggingPolicy, } from "./log-processor.js";
+/** Log level methods only. "child" is handled separately so returned children are also wrapped with createSafeLogger. */
+const LOG_METHODS = new Set([
+    "trace",
+    "debug",
+    "info",
+    "warn",
+    "error",
+    "fatal",
+]);
+/**
+ * Convert an Error to a plain object so it can be redacted like any other object.
+ * Includes name, message, stack, and any own enumerable properties (e.g. code, statusCode).
+ */
+function errorToPlainObject(err) {
+    const obj = {
+        message: err.message,
+        name: err.name,
+        stack: err.stack,
+    };
+    const errRecord = err;
+    for (const key of Object.keys(err)) {
+        if (!Object.prototype.hasOwnProperty.call(obj, key)) {
+            obj[key] = errRecord[key];
+        }
+    }
+    return obj;
+}
+/**
+ * Redact and sanitize a single log argument: key-based (forbidden fields) and
+ * value-based (stack traces, PII, policy redactPatterns). Error instances are
+ * converted to a plain object first. Exported for use by callers (e.g. server
+ * RemoteLogger redactRecord) so stdout and OTLP paths share the same rules.
+ */
+export function redactForbiddenFields(arg, policy) {
+    if (arg === null || typeof arg !== "object") {
+        return arg;
+    }
+    if (arg instanceof Error) {
+        return redactForbiddenFields(errorToPlainObject(arg), policy);
+    }
+    return sanitizeLogRecordForExport(arg, policy.forbiddenFields, policy.redactPatterns, policy.sensitivePatterns);
+}
+function redactArg(arg, policy) {
+    return redactForbiddenFields(arg, policy);
+}
+/**
+ * Redact log call arguments: first arg (merge object) with key+value sanitization,
+ * and message string (second arg) with value-based sanitization (patterns, stack, PII).
+ */
+function redactArgs(args, policy) {
+    if (args.length === 0)
+        return args;
+    const [first, ...rest] = args;
+    const redactedFirst = typeof first === "object" && first !== null
+        ? redactArg(first, policy)
+        : typeof first === "string"
+            ? sanitizeLogMessageForExport(first, policy.redactPatterns, policy.sensitivePatterns)
+            : first;
+    const redactedRest = rest.map((r, i) => i === 0 && typeof r === "string"
+        ? sanitizeLogMessageForExport(r, policy.redactPatterns, policy.sensitivePatterns)
+        : r);
+    return [redactedFirst, ...redactedRest];
+}
+/**
+ * Creates a logger wrapper that redacts policy-forbidden fields from log calls
+ * and applies the policy-effective log level (exportMode + envLevel) so that
+ * both the root and any child loggers respect exportMode (e.g. ERRORS_ONLY → warn floor).
+ *
+ * Use when logging in contexts where output may be exported (e.g. cloud-prem).
+ * Forbidden fields (stack, prompt, code, filePath, etc.) are replaced with
+ * "[REDACTED]" so they never appear in exported logs.
+ *
+ * @param baseLogger - Underlying Pino (or compatible) logger
+ * @param policy - Logging policy (e.g. from getLoggingPolicy(telemetryPolicy))
+ * @param envLevel - Optional env-configured level (e.g. SUPERBLOCKS_SERVER_LOG_LEVEL).
+ *   When provided, base logger level is set from getMinimumPinoLevelFromLoggingPolicy(policy, envLevel)
+ *   so exportMode (e.g. ERRORS_ONLY) is respected; children inherit this level in .child().
+ * @returns A logger that redacts forbidden fields and respects policy level (same interface as baseLogger)
+ *
+ * @example
+ * ```typescript
+ * const policy = getLoggingPolicy(telemetryPolicy);
+ * const safeLogger = createSafeLogger(logger, policy, envs.get('SUPERBLOCKS_SERVER_LOG_LEVEL'));
+ * safeLogger.error({ err, stack: err.stack }, 'Request failed');
+ * // Exported logs see stack: "[REDACTED]"
+ * ```
+ */
+export function createSafeLogger(baseLogger, policy, envLevel) {
+    if (envLevel !== undefined) {
+        const effectiveLevel = getMinimumPinoLevelFromLoggingPolicy(policy, envLevel);
+        baseLogger.level = effectiveLevel;
+    }
+    return new Proxy(baseLogger, {
+        get(target, prop) {
+            if (typeof prop === "symbol")
+                return Reflect.get(target, prop);
+            const value = target[prop];
+            if (LOG_METHODS.has(prop) && typeof value === "function") {
+                return (...args) => {
+                    let redacted;
+                    try {
+                        redacted = redactArgs(args, policy);
+                    }
+                    catch {
+                        // Redaction can throw (e.g. Proxy with throwing getters, circular refs).
+                        // Never emit original args — use a safe fallback so PII/Tier 1 is not exported.
+                        redacted = [
+                            { "[SafeLogger]": "redaction_failed" },
+                            "[SafeLogger] Log omitted: redaction failed",
+                        ];
+                        target.error("[SafeLogger] Redaction failed; log omitted to avoid leaking data");
+                    }
+                    return value.apply(target, redacted);
+                };
+            }
+            if (prop === "child" && typeof value === "function") {
+                return (bindings) => {
+                    // Redact forbidden fields from child bindings so they never appear in log output
+                    // (e.g. user-email from req.logTags would otherwise be merged into every log line)
+                    let redactedBindings;
+                    try {
+                        redactedBindings = redactArg(bindings, policy);
+                    }
+                    catch {
+                        // Never pass original bindings — use empty so PII/Tier 1 is not exported.
+                        redactedBindings = {};
+                        target.error("[SafeLogger] Child bindings omitted: redaction failed");
+                    }
+                    const child = value.call(target, redactedBindings);
+                    // Ensure child respects same level as parent (exportMode / localMaxLevel)
+                    const parentWithLevel = target;
+                    const childWithLevel = child;
+                    if (parentWithLevel.level !== undefined &&
+                        childWithLevel.level !== undefined) {
+                        childWithLevel.level = parentWithLevel.level;
+                    }
+                    return createSafeLogger(child, policy);
+                };
+            }
+            return value;
+        },
+    });
+}
+//# sourceMappingURL=safe-logger.js.map

package/dist-esm/node/safe-logger.js.map

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

package/dist-esm/node/sanitizing-processor.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Sanitizing Span Processor (Tier 2)
+ *
+ * Sanitizes spans before export per epic-a3-sanitized-traces.
+ * - All spans are passed to localProcessor (full fidelity for local/on-prem retention).
+ * - Only contract-compliant, sanitized spans are exported to Tier 2.
+ * - Fail-closed: when Tier 2 export is disabled, no exporter is attached.
+ */
+import type { Context } from "@opentelemetry/api";
+import type { ReadableSpan, Span, SpanExporter, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { TelemetryPolicyEvaluator } from "../common/policy-evaluator.js";
+import { TraceSanitizer } from "../common/trace-sanitizer.js";
+/** No-op span processor for the "local" path when only Tier 2 export is used. */
+declare class NoopSpanProcessor implements SpanProcessor {
+    onStart(): void;
+    onEnd(): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
+export declare const noopSpanProcessor: NoopSpanProcessor;
+/** Logger interface for processor messages (e.g. queue full, export failure). */
+interface SanitizingProcessorLogger {
+    debug?(obj: object, msg?: string): void;
+    debug?(msg: string): void;
+    error?(obj: object, msg?: string): void;
+    error?(msg: string): void;
+    warn(obj: object, msg?: string): void;
+    warn(msg: string): void;
+}
+/**
+ * Span processor that sanitizes spans before Tier 2 export.
+ *
+ * CRITICAL: This processor owns the export path. The exporter is internal.
+ * For Tier 1: All spans passed to localProcessor (e.g. no-op or local collector).
+ * For Tier 2: Only contract-compliant spans, sanitized, then batched and exported.
+ *
+ * NOTE: The wrapped tier2Exporter must tolerate concurrent export() calls.
+ * The periodic timer and the batch-size trigger can both fire flushExports()
+ * in the same tick. OTLPTraceExporter is safe; custom exporters should verify.
+ */
+export declare class SanitizingSpanProcessor implements SpanProcessor {
+    private readonly exportTimeoutMs;
+    private readonly sanitizer;
+    private readonly localProcessor;
+    private readonly tier2Exporter;
+    private readonly logger;
+    private pendingExports;
+    private exportTimer;
+    private droppedQueueFull;
+    /** Tracks in-flight fire-and-forget flushes so shutdown/forceFlush can await them. */
+    private readonly inflight;
+    constructor(policyEvaluator: TelemetryPolicyEvaluator, localProcessor: SpanProcessor, tier2Exporter: SpanExporter | null, traceSanitizer: TraceSanitizer, logger: SanitizingProcessorLogger, exportTimeoutMs?: number);
+    onStart(span: Span, parentContext: Context): void;
+    onEnd(span: ReadableSpan): void;
+    /** Fire-and-forget batch flush — tracks the in-flight promise so shutdown/forceFlush can await it. */
+    private flushExports;
+    /**
+     * Awaitable batch flush for drain paths (shutdown, forceFlush).
+     * Always resolves — times out after exportTimeoutMs if the exporter
+     * never calls its callback (e.g. broken socket, hung downstream).
+     */
+    private flushExportsAsync;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=sanitizing-processor.d.ts.map

package/dist-esm/node/sanitizing-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitizing-processor.d.ts","sourceRoot":"","sources":["../../src/node/sanitizing-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EACV,YAAY,EACZ,IAAI,EACJ,YAAY,EACZ,aAAa,EACd,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAO9D,iFAAiF;AACjF,cAAM,iBAAkB,YAAW,aAAa;IAC9C,OAAO,IAAI,IAAI;IACf,KAAK,IAAI,IAAI;IACP,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IACzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAClC;AAED,eAAO,MAAM,iBAAiB,mBAA0B,CAAC;AAGzD,iFAAiF;AACjF,UAAU,yBAAyB;IACjC,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAKD;;;;;;;;;;GAUG;AACH,qBAAa,uBAAwB,YAAW,aAAa;IAiBzD,OAAO,CAAC,QAAQ,CAAC,eAAe;IAhBlC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgB;IAC/C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,WAAW,CAA+C;IAClE,OAAO,CAAC,gBAAgB,CAAS;IACjC,sFAAsF;IACtF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;gBAGnD,eAAe,EAAE,wBAAwB,EACzC,cAAc,EAAE,aAAa,EAC7B,aAAa,EAAE,YAAY,GAAG,IAAI,EAClC,cAAc,EAAE,cAAc,EAC9B,MAAM,EAAE,yBAAyB,EAChB,eAAe,SAAO;IAoBzC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,GAAG,IAAI;IAIjD,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IA8B/B,sGAAsG;IACtG,OAAO,CAAC,YAAY;IAOpB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAoDnB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAezB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAUlC"}

package/dist-esm/node/sanitizing-processor.js

@@ -0,0 +1,163 @@
+/**
+ * Sanitizing Span Processor (Tier 2)
+ *
+ * Sanitizes spans before export per epic-a3-sanitized-traces.
+ * - All spans are passed to localProcessor (full fidelity for local/on-prem retention).
+ * - Only contract-compliant, sanitized spans are exported to Tier 2.
+ * - Fail-closed: when Tier 2 export is disabled, no exporter is attached.
+ */
+import { ExportResultCode } from "@opentelemetry/core";
+import { TelemetryTier } from "../types/policy.js";
+const BATCH_SIZE = 512;
+/** Max pending spans before dropping. Aligns with BatchSpanProcessor / resilient-exporter queue limits. */
+const MAX_PENDING_EXPORTS = 2048;
+/** No-op span processor for the "local" path when only Tier 2 export is used. */
+class NoopSpanProcessor {
+    onStart() { }
+    onEnd() { }
+    async shutdown() { }
+    async forceFlush() { }
+}
+export const noopSpanProcessor = new NoopSpanProcessor();
+const EXPORT_INTERVAL_MS = 5000;
+/**
+ * Span processor that sanitizes spans before Tier 2 export.
+ *
+ * CRITICAL: This processor owns the export path. The exporter is internal.
+ * For Tier 1: All spans passed to localProcessor (e.g. no-op or local collector).
+ * For Tier 2: Only contract-compliant spans, sanitized, then batched and exported.
+ *
+ * NOTE: The wrapped tier2Exporter must tolerate concurrent export() calls.
+ * The periodic timer and the batch-size trigger can both fire flushExports()
+ * in the same tick. OTLPTraceExporter is safe; custom exporters should verify.
+ */
+export class SanitizingSpanProcessor {
+    exportTimeoutMs;
+    sanitizer;
+    localProcessor;
+    tier2Exporter;
+    logger;
+    pendingExports = [];
+    exportTimer = null;
+    droppedQueueFull = false;
+    /** Tracks in-flight fire-and-forget flushes so shutdown/forceFlush can await them. */
+    inflight = new Set();
+    constructor(policyEvaluator, localProcessor, tier2Exporter, traceSanitizer, logger, exportTimeoutMs = 5000) {
+        this.exportTimeoutMs = exportTimeoutMs;
+        this.sanitizer = traceSanitizer;
+        this.localProcessor = localProcessor;
+        this.logger = logger;
+        this.tier2Exporter = policyEvaluator.isExportEnabled(TelemetryTier.TIER_2_OPERATIONAL)
+            ? tier2Exporter
+            : null;
+        if (this.tier2Exporter) {
+            this.exportTimer = setInterval(() => this.flushExports("periodic"), EXPORT_INTERVAL_MS);
+            this.exportTimer.unref();
+        }
+    }
+    onStart(span, parentContext) {
+        this.localProcessor.onStart(span, parentContext);
+    }
+    onEnd(span) {
+        this.localProcessor.onEnd(span);
+        if (this.tier2Exporter) {
+            const sanitized = this.sanitizer.sanitize(span);
+            if (sanitized) {
+                if (this.pendingExports.length >= MAX_PENDING_EXPORTS) {
+                    if (!this.droppedQueueFull) {
+                        this.droppedQueueFull = true;
+                        const msg = "Tier 2 pending queue full, dropping new spans until next flush";
+                        const log = this.logger.error ?? this.logger.warn;
+                        log({
+                            component: "SanitizingSpanProcessor",
+                            maxPendingExports: MAX_PENDING_EXPORTS,
+                        }, msg);
+                    }
+                }
+                else {
+                    this.pendingExports.push(sanitized);
+                    if (this.pendingExports.length >= BATCH_SIZE) {
+                        this.flushExports("batch");
+                    }
+                }
+            }
+        }
+    }
+    /** Fire-and-forget batch flush — tracks the in-flight promise so shutdown/forceFlush can await it. */
+    flushExports(phase) {
+        const p = this.flushExportsAsync(phase).finally(() => this.inflight.delete(p));
+        this.inflight.add(p);
+    }
+    /**
+     * Awaitable batch flush for drain paths (shutdown, forceFlush).
+     * Always resolves — times out after exportTimeoutMs if the exporter
+     * never calls its callback (e.g. broken socket, hung downstream).
+     */
+    flushExportsAsync(phase) {
+        if (!this.tier2Exporter || this.pendingExports.length === 0) {
+            return Promise.resolve();
+        }
+        if (this.pendingExports.length < MAX_PENDING_EXPORTS) {
+            this.droppedQueueFull = false;
+        }
+        const batch = this.pendingExports.splice(0, BATCH_SIZE);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.logger.warn({
+                    component: "SanitizingSpanProcessor",
+                    batchSize: batch.length,
+                    exportTimeoutMs: this.exportTimeoutMs,
+                    phase,
+                }, "Tier 2 span export timed out");
+                resolve();
+            }, this.exportTimeoutMs).unref();
+            try {
+                this.tier2Exporter.export(batch, (result) => {
+                    clearTimeout(timer);
+                    if (result.code !== ExportResultCode.SUCCESS) {
+                        this.logger.warn({
+                            component: "SanitizingSpanProcessor",
+                            err: result.error,
+                            batchSize: batch.length,
+                        }, "Tier 2 span export failed");
+                    }
+                    resolve();
+                });
+            }
+            catch (err) {
+                clearTimeout(timer);
+                this.logger.warn({
+                    component: "SanitizingSpanProcessor",
+                    err,
+                    batchSize: batch.length,
+                }, "Tier 2 span export threw synchronously");
+                resolve();
+            }
+        });
+    }
+    async shutdown() {
+        if (this.exportTimer) {
+            clearInterval(this.exportTimer);
+            this.exportTimer = null;
+        }
+        while (this.pendingExports.length > 0) {
+            await this.flushExportsAsync("shutdown");
+        }
+        await Promise.allSettled([...this.inflight]);
+        await this.localProcessor.shutdown();
+        if (this.tier2Exporter) {
+            await this.tier2Exporter.shutdown();
+        }
+    }
+    async forceFlush() {
+        while (this.pendingExports.length > 0) {
+            await this.flushExportsAsync("forceFlush");
+        }
+        await Promise.allSettled([...this.inflight]);
+        await this.localProcessor.forceFlush();
+        if (this.tier2Exporter?.forceFlush) {
+            await this.tier2Exporter.forceFlush();
+        }
+    }
+}
+//# sourceMappingURL=sanitizing-processor.js.map