observability-toolkit 1.8.5 → 2.1.0

package/dist/lib/observability/histogram.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Response Time Histogram for Query Latency Tracking
+ *
+ * Provides histogram data structure with configurable buckets and reservoir
+ * sampling for percentile calculation. Used to track query response times
+ * across different query types (traces, logs, metrics, etc.).
+ *
+ * Features:
+ * - O(1) bucket assignment via binary search
+ * - Reservoir sampling (max 10,000 values) for accurate percentile calculation
+ * - Configurable bucket boundaries (default aligned with OTel conventions)
+ * - Thread-safe operations (single-threaded JS)
+ */
+/**
+ * Bucket distribution data
+ */
+export interface HistogramBuckets {
+    /** Bucket upper boundaries */
+    readonly buckets: readonly number[];
+    /** Count of observations per bucket (includes +Inf bucket) */
+    readonly counts: readonly number[];
+    /** Total sum of all observed values */
+    readonly sum: number;
+    /** Total count of observations */
+    readonly count: number;
+}
+/**
+ * Statistical summary of histogram observations
+ */
+export interface HistogramStats {
+    /** Minimum observed value */
+    min: number;
+    /** Maximum observed value */
+    max: number;
+    /**
+     * Mean (average) of all observations.
+     * Note: Subject to IEEE 754 floating-point precision limits. For typical
+     * millisecond latency values this is negligible, but comparisons should
+     * use tolerance (e.g., Math.abs(a - b) < 0.001) rather than strict equality.
+     */
+    mean: number;
+    /** 50th percentile (median) */
+    p50: number;
+    /** 95th percentile */
+    p95: number;
+    /** 99th percentile */
+    p99: number;
+    /** Total observation count */
+    count: number;
+}
+/**
+ * Default latency bucket boundaries (milliseconds)
+ * Aligned with OTel conventions for HTTP request duration
+ */
+export declare const DEFAULT_LATENCY_BUCKETS: readonly [10, 50, 100, 250, 500, 1000, 2500, 5000, 10000];
+/**
+ * Default reservoir size for percentile calculation.
+ * Each number uses ~8 bytes, so 10,000 values ≈ 80KB per histogram.
+ * With 5 histograms (one per query type), total ≈ 400KB memory usage.
+ * Configurable via constructor to balance memory vs. percentile accuracy.
+ */
+export declare const DEFAULT_RESERVOIR_MAX_SIZE = 10000;
+/**
+ * Histogram for tracking response time distributions
+ *
+ * Uses reservoir sampling to maintain memory-bounded percentile calculation
+ * while still providing accurate bucket counts for all observations.
+ */
+export declare class Histogram {
+    private readonly bucketBoundaries;
+    private bucketCounts;
+    private sketch;
+    private totalSum;
+    private totalCount;
+    private minValue;
+    private maxValue;
+    /**
+     * Create a new histogram
+     * @param boundaries - Bucket boundaries (sorted ascending, finite non-negative numbers). Defaults to DEFAULT_LATENCY_BUCKETS.
+     * @param _reservoirMaxSize - Ignored (kept for API compatibility). DDSketch controls compression internally.
+     * @throws Error if boundaries contain invalid values (non-finite, negative, or duplicates)
+     */
+    constructor(boundaries?: number[], _reservoirMaxSize?: number);
+    /**
+     * Record an observation
+     * @param value - Value to observe (must be non-negative)
+     */
+    observe(value: number): void;
+    /**
+     * Find the bucket index for a value using binary search
+     * @param value - Value to place in bucket
+     * @returns Bucket index (0 to bucketBoundaries.length)
+     */
+    private findBucket;
+    /**
+     * Get bucket distribution
+     */
+    getBuckets(): HistogramBuckets;
+    /**
+     * Get statistical summary
+     */
+    getStats(): HistogramStats;
+    /**
+     * Reset all histogram data
+     */
+    reset(): void;
+    /**
+     * Get the count of observations (alias for convenience)
+     */
+    getCount(): number;
+}
+//# sourceMappingURL=histogram.d.ts.map

package/dist/lib/observability/histogram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"histogram.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/histogram.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,2DAA6C,CAAC;AAKlF;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAEhD;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAW;IAC5C,OAAO,CAAC,YAAY,CAAW;IAC/B,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAY;IAC5B,OAAO,CAAC,QAAQ,CAAa;IAE7B;;;;;OAKG;gBACS,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,iBAAiB,GAAE,MAAmC;IA4BzF;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAoB5B;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAiBlB;;OAEG;IACH,UAAU,IAAI,gBAAgB;IAS9B;;OAEG;IACH,QAAQ,IAAI,cAAc;IAyB1B;;OAEG;IACH,KAAK,IAAI,IAAI;IASb;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/lib/observability/histogram.js

@@ -0,0 +1,170 @@
+/**
+ * Response Time Histogram for Query Latency Tracking
+ *
+ * Provides histogram data structure with configurable buckets and reservoir
+ * sampling for percentile calculation. Used to track query response times
+ * across different query types (traces, logs, metrics, etc.).
+ *
+ * Features:
+ * - O(1) bucket assignment via binary search
+ * - Reservoir sampling (max 10,000 values) for accurate percentile calculation
+ * - Configurable bucket boundaries (default aligned with OTel conventions)
+ * - Thread-safe operations (single-threaded JS)
+ */
+import { DDSketch } from '@datadog/sketches-js';
+import { LATENCY_HISTOGRAM_BUCKETS_MS } from './histogram-bucket-constants.js';
+import { PERCENTILE, } from '../core/units.js';
+/**
+ * Default latency bucket boundaries (milliseconds)
+ * Aligned with OTel conventions for HTTP request duration
+ */
+export const DEFAULT_LATENCY_BUCKETS = [...LATENCY_HISTOGRAM_BUCKETS_MS];
+/** DDSketch.getValueAtQuantile() takes 0-1; PERCENTILE enum values are 0-100 */
+const PERCENTILE_SCALE = 100;
+/**
+ * Default reservoir size for percentile calculation.
+ * Each number uses ~8 bytes, so 10,000 values ≈ 80KB per histogram.
+ * With 5 histograms (one per query type), total ≈ 400KB memory usage.
+ * Configurable via constructor to balance memory vs. percentile accuracy.
+ */
+export const DEFAULT_RESERVOIR_MAX_SIZE = 10000;
+/**
+ * Histogram for tracking response time distributions
+ *
+ * Uses reservoir sampling to maintain memory-bounded percentile calculation
+ * while still providing accurate bucket counts for all observations.
+ */
+export class Histogram {
+    bucketBoundaries;
+    bucketCounts;
+    sketch;
+    totalSum = 0;
+    totalCount = 0;
+    minValue = Infinity;
+    maxValue = -Infinity;
+    /**
+     * Create a new histogram
+     * @param boundaries - Bucket boundaries (sorted ascending, finite non-negative numbers). Defaults to DEFAULT_LATENCY_BUCKETS.
+     * @param _reservoirMaxSize - Ignored (kept for API compatibility). DDSketch controls compression internally.
+     * @throws Error if boundaries contain invalid values (non-finite, negative, or duplicates)
+     */
+    constructor(boundaries, _reservoirMaxSize = DEFAULT_RESERVOIR_MAX_SIZE) {
+        // H2 fix: Validate bucket boundaries
+        if (boundaries) {
+            for (const b of boundaries) {
+                if (!Number.isFinite(b) || b < 0) {
+                    throw new Error(`Invalid bucket boundary: ${b}. Boundaries must be finite non-negative numbers.`);
+                }
+            }
+            // Check for duplicates after sorting
+            const sorted = [...boundaries].sort((a, b) => a - b);
+            for (let i = 1; i < sorted.length; i++) {
+                if (sorted[i] === sorted[i - 1]) {
+                    throw new Error(`Duplicate bucket boundary: ${sorted[i]}. Boundaries must be unique.`);
+                }
+            }
+            this.bucketBoundaries = sorted;
+        }
+        else {
+            this.bucketBoundaries = [...DEFAULT_LATENCY_BUCKETS];
+        }
+        // +1 for the +Inf bucket (values > max boundary)
+        this.bucketCounts = new Array(this.bucketBoundaries.length + 1).fill(0);
+        this.sketch = new DDSketch();
+    }
+    /**
+     * Record an observation
+     * @param value - Value to observe (must be non-negative)
+     */
+    observe(value) {
+        // Reject negative values (latency can't be negative)
+        if (value < 0) {
+            return;
+        }
+        // Update bucket count using binary search for O(log n) assignment
+        const bucketIndex = this.findBucket(value);
+        this.bucketCounts[bucketIndex]++;
+        // Update statistics
+        this.totalSum += value;
+        this.totalCount++;
+        this.minValue = Math.min(this.minValue, value);
+        this.maxValue = Math.max(this.maxValue, value);
+        // Feed DDSketch for percentile estimation
+        this.sketch.accept(value);
+    }
+    /**
+     * Find the bucket index for a value using binary search
+     * @param value - Value to place in bucket
+     * @returns Bucket index (0 to bucketBoundaries.length)
+     */
+    findBucket(value) {
+        let low = 0;
+        let high = this.bucketBoundaries.length;
+        while (low < high) {
+            // Unsigned right shift converts to uint32 for safe midpoint calculation
+            const mid = (low + high) >>> 1;
+            if (this.bucketBoundaries[mid] < value) {
+                low = mid + 1;
+            }
+            else {
+                high = mid;
+            }
+        }
+        return low;
+    }
+    /**
+     * Get bucket distribution
+     */
+    getBuckets() {
+        return {
+            buckets: [...this.bucketBoundaries],
+            counts: [...this.bucketCounts],
+            sum: this.totalSum,
+            count: this.totalCount,
+        };
+    }
+    /**
+     * Get statistical summary
+     */
+    getStats() {
+        if (this.totalCount === 0) {
+            return {
+                min: 0,
+                max: 0,
+                mean: 0,
+                p50: 0,
+                p95: 0,
+                p99: 0,
+                count: 0,
+            };
+        }
+        return {
+            min: this.minValue,
+            max: this.maxValue,
+            // L4-B4: Floating-point division - negligible precision loss for typical ms values
+            mean: this.totalSum / this.totalCount,
+            p50: this.sketch.getValueAtQuantile(PERCENTILE.P50 / PERCENTILE_SCALE),
+            p95: this.sketch.getValueAtQuantile(PERCENTILE.P95 / PERCENTILE_SCALE),
+            p99: this.sketch.getValueAtQuantile(PERCENTILE.P99 / PERCENTILE_SCALE),
+            count: this.totalCount,
+        };
+    }
+    /**
+     * Reset all histogram data
+     */
+    reset() {
+        this.bucketCounts = new Array(this.bucketBoundaries.length + 1).fill(0);
+        this.sketch = new DDSketch();
+        this.totalSum = 0;
+        this.totalCount = 0;
+        this.minValue = Infinity;
+        this.maxValue = -Infinity;
+    }
+    /**
+     * Get the count of observations (alias for convenience)
+     */
+    getCount() {
+        return this.totalCount;
+    }
+}
+//# sourceMappingURL=histogram.js.map

package/dist/lib/observability/histogram.js.map

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

package/dist/lib/observability/histogram.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for Response Time Histogram
+ */
+export {};
+//# sourceMappingURL=histogram.test.d.ts.map

package/dist/lib/observability/histogram.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"histogram.test.d.ts","sourceRoot":"","sources":["../../../src/lib/observability/histogram.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}