@zudojs/observability 0.0.1 → 1.0.0

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

package/dist/metrics/metrics.reader.js

@@ -0,0 +1,81 @@
+/**
+ * @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.
+ */
+const DEFAULT_INTERVAL_MS = 60_000;
+/** Snapshots a registry on an interval and exports the result. */
+export class PeriodicMetricReader {
+    registry;
+    exporter;
+    intervalMs;
+    onError;
+    timer;
+    started = false;
+    shuttingDown = false;
+    inFlight;
+    constructor(options) {
+        this.registry = options.registry;
+        this.exporter = options.exporter;
+        this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+        this.onError = options.onError;
+    }
+    /** Begins periodic export. Calling it twice is a no-op. */
+    start() {
+        if (this.started || this.shuttingDown || this.intervalMs <= 0)
+            return;
+        this.started = true;
+        this.timer = setInterval(() => {
+            void this.collect();
+        }, this.intervalMs);
+        if (typeof this.timer === "object" && "unref" in this.timer) {
+            this.timer.unref();
+        }
+    }
+    /** Exports one snapshot immediately. */
+    async collect() {
+        if (this.inFlight) {
+            await this.inFlight;
+            return;
+        }
+        const run = (async () => {
+            const snapshots = this.registry.getAll();
+            if (snapshots.length === 0)
+                return;
+            try {
+                await this.exporter.export(snapshots);
+            }
+            catch (error) {
+                this.onError?.(error, "MetricExporter.export");
+            }
+        })();
+        this.inFlight = run;
+        try {
+            await run;
+        }
+        finally {
+            if (this.inFlight === run)
+                this.inFlight = undefined;
+        }
+    }
+    /** Exports a final snapshot and stops. Safe to call more than once. */
+    async shutdown() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        await this.collect();
+        await this.exporter.shutdown();
+    }
+}
+/** Creates a periodic metric reader. */
+export function createPeriodicMetricReader(options) {
+    return new PeriodicMetricReader(options);
+}
+//# sourceMappingURL=metrics.reader.js.map

package/dist/metrics/metrics.registry.d.ts

@@ -4,20 +4,71 @@
  * Central registry for all metrics. Creates and caches metrics by name+labels.
  */
 import type { Counter, Gauge, Histogram, MetricsRegistry, MetricSnapshot } from "../types.js";
+/**
+ * Builds the cache key for one series.
+ *
+ * Label keys and values are JSON-encoded, so `{ a: "b,c=d" }` and
+ * `{ a: "b", c: "d" }` cannot collapse onto the same key the way a bare
+ * `k=v` join lets them.
+ */
+export declare function metricKey(type: string, name: string, labels?: Record<string, string>): string;
+/** Options for {@link DefaultMetricsRegistry}. */
+export interface MetricsRegistryOptions {
+    /**
+     * Maximum number of distinct series held at once. Default: 10,000.
+     *
+     * A label carrying a user ID or a path with IDs in it turns an unbounded
+     * registry into a memory leak, so the cap is on by default and creating a
+     * series past it reports the offending metric instead of growing silently.
+     */
+    readonly maxSeries?: number;
+    /** Bucket boundaries for histograms created by this registry. */
+    readonly histogramBoundaries?: readonly number[];
+    /** Called when the series cap is hit, once per rejected series. */
+    readonly onCardinalityLimit?: (name: string, size: number) => void;
+}
 /**
  * In-memory metrics registry. Creates, caches, and manages metrics.
  */
 export declare class DefaultMetricsRegistry implements MetricsRegistry {
     private readonly metrics;
+    /**
+     * The type each metric name was first registered as.
+     *
+     * The cache key includes the type, so the map alone can never surface a
+     * differently-typed entry — the conflict check that reads it was dead code,
+     * and `counter("x")` followed by `gauge("x")` produced two same-named series
+     * of different types in one document. An OTLP or Prometheus backend rejects
+     * that, so the whole scrape is lost rather than one metric.
+     */
+    private readonly typeByName;
+    private readonly maxSeries;
+    private readonly histogramBoundaries?;
+    private readonly onCardinalityLimit?;
+    /** Series rejected by the cap, reused so callers still get a usable object. */
+    private readonly overflow;
+    /**
+     * Cap on the detached-series cache. Bounded well below `maxSeries` so the
+     * documented ceiling is not quietly doubled by the overflow path.
+     */
+    private readonly maxOverflow;
+    constructor(options?: MetricsRegistryOptions);
+    private create;
+    private obtain;
     counter(name: string, labels?: Record<string, string>): Counter;
     gauge(name: string, labels?: Record<string, string>): Gauge;
     histogram(name: string, labels?: Record<string, string>): Histogram;
-    getCounter(name: string): Counter | undefined;
-    getGauge(name: string): Gauge | undefined;
-    getHistogram(name: string): Histogram | undefined;
+    private lookup;
+    getCounter(name: string, labels?: Record<string, string>): Counter | undefined;
+    getGauge(name: string, labels?: Record<string, string>): Gauge | undefined;
+    getHistogram(name: string, labels?: Record<string, string>): Histogram | undefined;
+    getSeries(name: string): readonly MetricSnapshot[];
+    private snapshot;
     getAll(): MetricSnapshot[];
+    size(): number;
     reset(): void;
+    clear(): void;
 }
 /** Creates a metrics registry. */
-export declare function createMetricsRegistry(): DefaultMetricsRegistry;
+export declare function createMetricsRegistry(options?: MetricsRegistryOptions): DefaultMetricsRegistry;
 //# sourceMappingURL=metrics.registry.d.ts.map