@zudojs/observability 0.1.0 → 1.0.0

package/dist/logRecord/logRecord.core.js

@@ -4,46 +4,68 @@
  * Factory functions for creating structured log records.
  */
 import { LogLevel } from "../types.js";
+import { logLevelToName } from "../logLevel/index.js";
+/**
+ * Serializes a thrown value into something a JSON transport can carry.
+ *
+ * `Error`'s own fields are non-enumerable, so an error placed in a log
+ * context stringifies to `{}` — this is what turns it back into data.
+ * `cause` chains are followed, with a depth cap so a self-referential cause
+ * cannot recurse forever.
+ */
+export function serializeError(error, depth = 0) {
+    if (error instanceof Error) {
+        const cause = error.cause !== undefined && depth < 4
+            ? serializeError(error.cause, depth + 1)
+            : undefined;
+        return {
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+            cause,
+        };
+    }
+    if (typeof error === "object" && error !== null) {
+        const record = error;
+        const name = typeof record["name"] === "string" ? record["name"] : "Error";
+        const message = typeof record["message"] === "string"
+            ? record["message"]
+            : safeStringify(error);
+        return { name, message };
+    }
+    return { name: "Error", message: String(error) };
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
 /** Creates a structured log record. */
 export function createLogRecord(options) {
-    const error = options.error
-        ? {
-            name: options.error.name,
-            message: options.error.message,
-            stack: options.error.stack,
-            cause: options.error.cause,
-        }
-        : undefined;
     return {
         level: options.level,
-        levelName: logLevelToNameInternal(options.level),
+        levelName: logLevelToName(options.level),
         message: options.message,
-        timestamp: new Date(),
+        timestamp: options.timestamp ?? new Date(),
         loggerName: options.loggerName,
         context: options.context,
-        error,
+        error: options.error === undefined ? undefined : serializeError(options.error),
+        traceId: options.traceId,
+        spanId: options.spanId,
     };
 }
 /** Creates a log record for an error. */
-export function createErrorLogRecord(error, level, loggerName) {
+export function createErrorLogRecord(error, level, loggerName, context) {
+    const serialized = serializeError(error);
     return createLogRecord({
         level,
-        message: error.message,
+        message: serialized.message,
         loggerName,
-        context: { stack: error.stack },
+        context,
         error,
     });
 }
-function logLevelToNameInternal(level) {
-    const names = {
-        [LogLevel.TRACE]: "trace",
-        [LogLevel.DEBUG]: "debug",
-        [LogLevel.INFO]: "info",
-        [LogLevel.WARN]: "warn",
-        [LogLevel.ERROR]: "error",
-        [LogLevel.FATAL]: "fatal",
-        [LogLevel.OFF]: "off",
-    };
-    return names[level] ?? "off";
-}
 //# sourceMappingURL=logRecord.core.js.map

package/dist/logger/logger.core.d.ts

@@ -2,26 +2,34 @@
  * @zudojs/observability — Logger Core
  *
  * Structured logger implementation with level filtering, transport support,
- * child loggers, and persistent context.
+ * child loggers, persistent context, trace correlation and redaction.
  */
 import type { Logger, LoggerOptions } from "../types.js";
 import { LogLevel } from "../types.js";
 /**
  * Core structured logger with level filtering, child loggers,
  * persistent context, and transport support.
+ *
+ * Every record is stamped with the ambient `traceId`/`spanId` when a
+ * propagation context is active, so logs and traces line up without the
+ * caller threading IDs through by hand.
  */
 export declare class StructuredLogger implements Logger {
     readonly name: string;
-    readonly level: LogLevel;
+    private currentLevel;
     private readonly context;
     private readonly transport;
+    private readonly correlate;
+    private readonly redact?;
     constructor(options: LoggerOptions);
-    trace(message: string, context?: Record<string, unknown>): void;
-    debug(message: string, context?: Record<string, unknown>): void;
-    info(message: string, context?: Record<string, unknown>): void;
-    warn(message: string, context?: Record<string, unknown>): void;
-    error(message: string, context?: Record<string, unknown>): void;
-    fatal(message: string, context?: Record<string, unknown>): void;
+    get level(): LogLevel;
+    setLevel(level: LogLevel): void;
+    trace(message: string, context?: Record<string, unknown>, error?: unknown): void;
+    debug(message: string, context?: Record<string, unknown>, error?: unknown): void;
+    info(message: string, context?: Record<string, unknown>, error?: unknown): void;
+    warn(message: string, context?: Record<string, unknown>, error?: unknown): void;
+    error(message: string, context?: Record<string, unknown>, error?: unknown): void;
+    fatal(message: string, context?: Record<string, unknown>, error?: unknown): void;
     child(name: string, context?: Record<string, unknown>): Logger;
     isLevelEnabled(level: LogLevel): boolean;
     flush(): Promise<void>;

package/dist/logger/logger.core.js

@@ -2,11 +2,12 @@
  * @zudojs/observability — Logger Core
  *
  * Structured logger implementation with level filtering, transport support,
- * child loggers, and persistent context.
+ * child loggers, persistent context, trace correlation and redaction.
  */
 import { LogLevel } from "../types.js";
-import { shouldLog, logLevelToName } from "../logLevel/index.js";
+import { shouldLog } from "../logLevel/index.js";
 import { createLogRecord } from "../logRecord/index.js";
+import { getCurrentContext } from "../propagation/index.js";
 /** Default no-op transport that discards all records. */
 const noopTransport = {
     name: "noop",
@@ -15,63 +16,93 @@ const noopTransport = {
 /**
  * Core structured logger with level filtering, child loggers,
  * persistent context, and transport support.
+ *
+ * Every record is stamped with the ambient `traceId`/`spanId` when a
+ * propagation context is active, so logs and traces line up without the
+ * caller threading IDs through by hand.
  */
 export class StructuredLogger {
     name;
-    level;
+    currentLevel;
     context;
     transport;
+    correlate;
+    redact;
     constructor(options) {
         this.name = options.name;
-        this.level = options.level ?? LogLevel.INFO;
+        this.currentLevel = options.level ?? LogLevel.INFO;
         this.context = { ...(options.context ?? {}) };
         this.transport = options.transport ?? noopTransport;
+        this.correlate = options.correlate ?? true;
+        this.redact = options.redact;
+    }
+    get level() {
+        return this.currentLevel;
+    }
+    setLevel(level) {
+        this.currentLevel = level;
     }
-    trace(message, context) {
-        this.log(LogLevel.TRACE, message, context);
+    trace(message, context, error) {
+        this.log(LogLevel.TRACE, message, context, error);
     }
-    debug(message, context) {
-        this.log(LogLevel.DEBUG, message, context);
+    debug(message, context, error) {
+        this.log(LogLevel.DEBUG, message, context, error);
     }
-    info(message, context) {
-        this.log(LogLevel.INFO, message, context);
+    info(message, context, error) {
+        this.log(LogLevel.INFO, message, context, error);
     }
-    warn(message, context) {
-        this.log(LogLevel.WARN, message, context);
+    warn(message, context, error) {
+        this.log(LogLevel.WARN, message, context, error);
     }
-    error(message, context) {
-        this.log(LogLevel.ERROR, message, context);
+    error(message, context, error) {
+        this.log(LogLevel.ERROR, message, context, error);
     }
-    fatal(message, context) {
-        this.log(LogLevel.FATAL, message, context);
+    fatal(message, context, error) {
+        this.log(LogLevel.FATAL, message, context, error);
     }
     child(name, context) {
         const childName = `${this.name}.${name}`;
         const childContext = { ...this.context, ...(context ?? {}) };
         return new StructuredLogger({
             name: childName,
-            level: this.level,
+            level: this.currentLevel,
             context: childContext,
             transport: this.transport,
+            correlate: this.correlate,
+            redact: this.redact,
         });
     }
     isLevelEnabled(level) {
-        return shouldLog(this.level, level);
+        return shouldLog(this.currentLevel, level);
     }
     async flush() {
-        // Transport-specific flush; default is no-op
+        await this.transport.flush?.();
     }
-    log(level, message, context) {
+    log(level, message, context, error) {
         if (!this.isLevelEnabled(level))
             return;
-        const mergedContext = { ...this.context, ...(context ?? {}) };
+        const merged = { ...this.context, ...(context ?? {}) };
+        const redacted = this.redact ? this.redact(merged) : merged;
+        const propagation = this.correlate ? getCurrentContext() : undefined;
         const record = createLogRecord({
             level,
             message,
             loggerName: this.name,
-            context: Object.keys(mergedContext).length > 0 ? mergedContext : undefined,
+            context: Object.keys(redacted).length > 0 ? redacted : undefined,
+            error,
+            traceId: propagation?.traceId,
+            spanId: propagation?.spanId,
         });
-        this.transport.write(record);
+        // A transport must never take the caller down with it. A failing sink is
+        // reported through the transport's own channel, not raised here.
+        try {
+            const written = this.transport.write(record);
+            if (written instanceof Promise)
+                written.catch(() => { });
+        }
+        catch {
+            // Intentionally swallowed: logging is not allowed to throw.
+        }
     }
 }
 /** Creates a structured logger. */

package/dist/metrics/counter/counter.core.d.ts

@@ -6,7 +6,10 @@
 import type { Counter } from "../../types.js";
 /**
  * In-memory counter. Increments monotonically.
- * Designed to be safe and cheap — no async, no locks.
+ *
+ * Invalid increments throw rather than being dropped: a counter that quietly
+ * ignored a negative delta would report a total nobody can reconcile with the
+ * code that produced it.
  */
 export declare class DefaultCounter implements Counter {
     readonly name: string;

package/dist/metrics/counter/counter.core.js

@@ -3,9 +3,13 @@
  *
  * Monotonically increasing counter for tracking event counts.
  */
+import { MetricValueError } from "../../errors/index.js";
 /**
  * In-memory counter. Increments monotonically.
- * Designed to be safe and cheap — no async, no locks.
+ *
+ * Invalid increments throw rather than being dropped: a counter that quietly
+ * ignored a negative delta would report a total nobody can reconcile with the
+ * code that produced it.
  */
 export class DefaultCounter {
     name;
@@ -16,8 +20,12 @@ export class DefaultCounter {
         this.labels = labels;
     }
     increment(value = 1) {
-        if (value < 0)
-            return;
+        if (!Number.isFinite(value)) {
+            throw new MetricValueError(this.name, value, "must be finite");
+        }
+        if (value < 0) {
+            throw new MetricValueError(this.name, value, "a counter cannot decrease; use a gauge");
+        }
         this.value += value;
     }
     getValue() {

package/dist/metrics/gauge/gauge.core.d.ts

@@ -12,6 +12,7 @@ export declare class DefaultGauge implements Gauge {
     readonly labels?: Record<string, string>;
     private value;
     constructor(name: string, labels?: Record<string, string>);
+    private assertFinite;
     setValue(value: number): void;
     increment(value?: number): void;
     decrement(value?: number): void;

package/dist/metrics/gauge/gauge.core.js

@@ -3,6 +3,7 @@
  *
  * A value that can go up and down, for tracking current state.
  */
+import { MetricValueError } from "../../errors/index.js";
 /**
  * In-memory gauge. Tracks a value that can be set, incremented, or decremented.
  */
@@ -14,13 +15,21 @@ export class DefaultGauge {
         this.name = name;
         this.labels = labels;
     }
+    assertFinite(value) {
+        if (!Number.isFinite(value)) {
+            throw new MetricValueError(this.name, value, "must be finite");
+        }
+    }
     setValue(value) {
+        this.assertFinite(value);
         this.value = value;
     }
     increment(value = 1) {
+        this.assertFinite(value);
         this.value += value;
     }
     decrement(value = 1) {
+        this.assertFinite(value);
         this.value -= value;
     }
     getValue() {

package/dist/metrics/histogram/histogram.core.d.ts

@@ -2,29 +2,40 @@
  * @zudojs/observability — Histogram
  *
  * Distribution of observed values for tracking latencies, sizes, etc.
- * Memory-bounded by keeping only summary statistics.
+ *
+ * Memory is bounded by fixed bucket boundaries rather than by keeping the
+ * observations: count, sum, min and max alone cannot answer "what is the p95",
+ * which is the question a latency histogram exists to answer.
+ */
+import type { Histogram, HistogramValue } from "../../types.js";
+/**
+ * Default boundaries, in milliseconds, covering sub-millisecond calls through
+ * ten-second ones. Pass your own when the unit is not latency.
  */
-import type { Histogram } from "../../types.js";
+export declare const DEFAULT_BUCKET_BOUNDARIES: readonly number[];
 /**
- * In-memory histogram. Tracks count, sum, min, and max of observed values.
+ * In-memory histogram with cumulative buckets and interpolated quantiles.
  */
 export declare class DefaultHistogram implements Histogram {
     readonly name: string;
     readonly labels?: Record<string, string>;
+    private readonly boundaries;
+    /** Counts per bucket; one slot longer than `boundaries` for the overflow. */
+    private counts;
     private count;
     private sum;
     private min;
     private max;
-    constructor(name: string, labels?: Record<string, string>);
+    constructor(name: string, labels?: Record<string, string>, boundaries?: readonly number[]);
     record(value: number): void;
-    getValue(): {
-        readonly count: number;
-        readonly sum: number;
-        readonly min: number;
-        readonly max: number;
-    };
+    getValue(): HistogramValue;
+    /**
+     * Estimates a quantile by linear interpolation inside the bucket the
+     * quantile falls in, clamped to the observed min and max.
+     */
+    percentile(q: number): number;
     reset(): void;
 }
 /** Creates a histogram. */
-export declare function createHistogram(name: string, labels?: Record<string, string>): DefaultHistogram;
+export declare function createHistogram(name: string, labels?: Record<string, string>, boundaries?: readonly number[]): DefaultHistogram;
 //# sourceMappingURL=histogram.core.d.ts.map

package/dist/metrics/histogram/histogram.core.js

@@ -2,47 +2,142 @@
  * @zudojs/observability — Histogram
  *
  * Distribution of observed values for tracking latencies, sizes, etc.
- * Memory-bounded by keeping only summary statistics.
+ *
+ * Memory is bounded by fixed bucket boundaries rather than by keeping the
+ * observations: count, sum, min and max alone cannot answer "what is the p95",
+ * which is the question a latency histogram exists to answer.
+ */
+import { MetricValueError } from "../../errors/index.js";
+/**
+ * Default boundaries, in milliseconds, covering sub-millisecond calls through
+ * ten-second ones. Pass your own when the unit is not latency.
+ */
+export const DEFAULT_BUCKET_BOUNDARIES = [
+    1, 2, 5, 10, 25, 50, 100, 250, 500, 1_000, 2_500, 5_000, 10_000,
+];
+/**
+ * Validates and canonicalises bucket boundaries.
+ *
+ * A `NaN` boundary makes `sort` leave the list in an arbitrary order, and
+ * every quantile computed from it comes back `NaN` — a latency histogram that
+ * reports nothing while looking like it works. Duplicates create zero-width
+ * buckets that skew interpolation, and an empty list leaves a single overflow
+ * bucket that cannot answer a percentile at all.
  */
+function normalizeBoundaries(name, boundaries) {
+    for (const boundary of boundaries) {
+        if (!Number.isFinite(boundary)) {
+            throw new MetricValueError(name, boundary, "histogram bucket boundaries must all be finite numbers");
+        }
+    }
+    const sorted = [...new Set(boundaries)].sort((a, b) => a - b);
+    if (sorted.length === 0) {
+        throw new MetricValueError(name, 0, "a histogram needs at least one bucket boundary");
+    }
+    return sorted;
+}
 /**
- * In-memory histogram. Tracks count, sum, min, and max of observed values.
+ * In-memory histogram with cumulative buckets and interpolated quantiles.
  */
 export class DefaultHistogram {
     name;
     labels;
+    boundaries;
+    /** Counts per bucket; one slot longer than `boundaries` for the overflow. */
+    counts;
     count = 0;
     sum = 0;
     min = Infinity;
     max = -Infinity;
-    constructor(name, labels) {
+    constructor(name, labels, boundaries = DEFAULT_BUCKET_BOUNDARIES) {
         this.name = name;
         this.labels = labels;
+        this.boundaries = normalizeBoundaries(name, boundaries);
+        this.counts = new Array(this.boundaries.length + 1).fill(0);
     }
     record(value) {
+        if (!Number.isFinite(value)) {
+            throw new MetricValueError(this.name, value, "must be finite");
+        }
         this.count++;
         this.sum += value;
         if (value < this.min)
             this.min = value;
         if (value > this.max)
             this.max = value;
+        let bucket = this.boundaries.length;
+        for (let i = 0; i < this.boundaries.length; i++) {
+            if (value <= this.boundaries[i]) {
+                bucket = i;
+                break;
+            }
+        }
+        this.counts[bucket] += 1;
     }
     getValue() {
+        const empty = this.count === 0;
+        let cumulative = 0;
+        const buckets = this.boundaries.map((le, i) => {
+            cumulative += this.counts[i];
+            return { le, count: cumulative };
+        });
         return {
             count: this.count,
             sum: this.sum,
-            min: this.count === 0 ? 0 : this.min,
-            max: this.count === 0 ? 0 : this.max,
+            min: empty ? 0 : this.min,
+            max: empty ? 0 : this.max,
+            mean: empty ? 0 : this.sum / this.count,
+            buckets,
+            p50: this.percentile(0.5),
+            p90: this.percentile(0.9),
+            p95: this.percentile(0.95),
+            p99: this.percentile(0.99),
         };
     }
+    /**
+     * Estimates a quantile by linear interpolation inside the bucket the
+     * quantile falls in, clamped to the observed min and max.
+     */
+    percentile(q) {
+        if (!Number.isFinite(q) || q < 0 || q > 1) {
+            throw new MetricValueError(this.name, q, "quantile must be in [0, 1]");
+        }
+        if (this.count === 0)
+            return 0;
+        const target = q * this.count;
+        let cumulative = 0;
+        let lowerBound = this.min;
+        for (let i = 0; i < this.counts.length; i++) {
+            const inBucket = this.counts[i];
+            if (inBucket === 0) {
+                if (i < this.boundaries.length)
+                    lowerBound = this.boundaries[i];
+                continue;
+            }
+            const upperBound = i < this.boundaries.length ? this.boundaries[i] : this.max;
+            if (cumulative + inBucket >= target) {
+                const within = (target - cumulative) / inBucket;
+                const low = Math.max(lowerBound, this.min);
+                const high = Math.min(upperBound, this.max);
+                if (high <= low)
+                    return high;
+                return low + within * (high - low);
+            }
+            cumulative += inBucket;
+            lowerBound = upperBound;
+        }
+        return this.max;
+    }
     reset() {
         this.count = 0;
         this.sum = 0;
         this.min = Infinity;
         this.max = -Infinity;
+        this.counts = new Array(this.boundaries.length + 1).fill(0);
     }
 }
 /** Creates a histogram. */
-export function createHistogram(name, labels) {
-    return new DefaultHistogram(name, labels);
+export function createHistogram(name, labels, boundaries) {
+    return new DefaultHistogram(name, labels, boundaries);
 }
 //# sourceMappingURL=histogram.core.js.map

package/dist/metrics/histogram/index.d.ts

@@ -3,5 +3,5 @@
  *
  * Distribution of observed values for latencies and sizes.
  */
-export { DefaultHistogram, createHistogram } from "./histogram.core.js";
+export { DefaultHistogram, createHistogram, DEFAULT_BUCKET_BOUNDARIES, } from "./histogram.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/metrics/histogram/index.js

@@ -3,5 +3,5 @@
  *
  * Distribution of observed values for latencies and sizes.
  */
-export { DefaultHistogram, createHistogram } from "./histogram.core.js";
+export { DefaultHistogram, createHistogram, DEFAULT_BUCKET_BOUNDARIES, } from "./histogram.core.js";
 //# sourceMappingURL=index.js.map

package/dist/metrics/index.d.ts

@@ -1,10 +1,11 @@
 /**
  * @zudojs/observability — Metrics
  *
- * Counters, gauges, histograms, and the metrics registry.
+ * Counters, gauges, histograms, the registry, and the periodic reader.
  */
 export { DefaultCounter, createCounter } from "./counter/index.js";
 export { DefaultGauge, createGauge } from "./gauge/index.js";
-export { DefaultHistogram, createHistogram } from "./histogram/index.js";
-export { DefaultMetricsRegistry, createMetricsRegistry, } from "./metrics.registry.js";
+export { DefaultHistogram, createHistogram, DEFAULT_BUCKET_BOUNDARIES, } from "./histogram/index.js";
+export { DefaultMetricsRegistry, createMetricsRegistry, metricKey, type MetricsRegistryOptions, } from "./metrics.registry.js";
+export { PeriodicMetricReader, createPeriodicMetricReader, type PeriodicMetricReaderOptions, } from "./metrics.reader.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/metrics/index.js

@@ -1,10 +1,11 @@
 /**
  * @zudojs/observability — Metrics
  *
- * Counters, gauges, histograms, and the metrics registry.
+ * Counters, gauges, histograms, the registry, and the periodic reader.
  */
 export { DefaultCounter, createCounter } from "./counter/index.js";
 export { DefaultGauge, createGauge } from "./gauge/index.js";
-export { DefaultHistogram, createHistogram } from "./histogram/index.js";
-export { DefaultMetricsRegistry, createMetricsRegistry, } from "./metrics.registry.js";
+export { DefaultHistogram, createHistogram, DEFAULT_BUCKET_BOUNDARIES, } from "./histogram/index.js";
+export { DefaultMetricsRegistry, createMetricsRegistry, metricKey, } from "./metrics.registry.js";
+export { PeriodicMetricReader, createPeriodicMetricReader, } from "./metrics.reader.js";
 //# sourceMappingURL=index.js.map

package/dist/metrics/metrics.reader.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @zudojs/observability — Metric Reader
+ *
+ * Metrics are pull-based in-process: the registry holds live numbers and
+ * nothing moves them anywhere. This reader is the missing half — it snapshots
+ * the registry on an interval and hands the snapshots to an exporter, so a
+ * configured `metricExporter` actually receives data.
+ */
+import type { MetricExporter, MetricsRegistry } from "../types.js";
+/** Options for {@link PeriodicMetricReader}. */
+export interface PeriodicMetricReaderOptions {
+    readonly registry: MetricsRegistry;
+    readonly exporter: MetricExporter;
+    /** Export interval in ms. Default: 60,000. `0` disables the timer. */
+    readonly intervalMs?: number;
+    /** Reports export failures. */
+    readonly onError?: (error: unknown, source: string) => void;
+}
+/** Snapshots a registry on an interval and exports the result. */
+export declare class PeriodicMetricReader {
+    private readonly registry;
+    private readonly exporter;
+    private readonly intervalMs;
+    private readonly onError?;
+    private timer?;
+    private started;
+    private shuttingDown;
+    private inFlight?;
+    constructor(options: PeriodicMetricReaderOptions);
+    /** Begins periodic export. Calling it twice is a no-op. */
+    start(): void;
+    /** Exports one snapshot immediately. */
+    collect(): Promise<void>;
+    /** Exports a final snapshot and stops. Safe to call more than once. */
+    shutdown(): Promise<void>;
+}
+/** Creates a periodic metric reader. */
+export declare function createPeriodicMetricReader(options: PeriodicMetricReaderOptions): PeriodicMetricReader;
+//# sourceMappingURL=metrics.reader.d.ts.map