@manifest-cyber/observability-ts 0.2.11 → 0.2.13

package/dist/metrics/builders.js

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BUCKETS = exports.ENV_KEY_SERVICE_NAME = void 0;
+exports.resetCachedServiceName = resetCachedServiceName;
+exports.setServiceName = setServiceName;
 exports.createCounter = createCounter;
 exports.createHistogram = createHistogram;
 exports.createGauge = createGauge;
-const prom_client_1 = require("prom-client");
-const registry_1 = require("./registry");
+const api_1 = require("@opentelemetry/api");
 /**
  * Environment variable key for service name
  * Should match the key used in @manifest-cyber/logger-ts
@@ -48,217 +49,250 @@ exports.BUCKETS = {
     },
 };
 /**
- * Get the service name from environment or use default
+ * Cached service name to avoid repeated process.env lookups
+ */
+let cachedServiceName;
+/**
+ * Get the service name from environment or use default.
+ * Reads from process.env on each call to pick up runtime changes,
+ * falling back to explicitly set cachedServiceName or 'unknown_service'.
  */
 function getServiceName() {
-    return process.env[exports.ENV_KEY_SERVICE_NAME] || 'unknown_service';
+    // Check environment first to allow runtime changes
+    const envServiceName = process.env[exports.ENV_KEY_SERVICE_NAME];
+    if (envServiceName) {
+        return envServiceName;
+    }
+    // Fall back to explicitly set service name
+    if (cachedServiceName !== undefined) {
+        return cachedServiceName;
+    }
+    // Final fallback
+    return 'unknown_service';
+}
+/**
+ * Reset cached service name (for testing)
+ * @internal
+ */
+function resetCachedServiceName() {
+    cachedServiceName = undefined;
+}
+/**
+ * Set service name explicitly (used as fallback when environment variable is not set)
+ * @internal
+ */
+function setServiceName(name) {
+    const cleaned = name?.trim();
+    if (!cleaned) {
+        throw new Error('Service name cannot be empty or whitespace-only');
+    }
+    cachedServiceName = cleaned;
 }
 /**
  * Normalize a metric name component to be Prometheus-compatible
  *
- * Prometheus metric names must match [a-zA-Z_:][a-zA-Z0-9_:]*
+ * Prometheus/OTel metric names should match [a-zA-Z_:][a-zA-Z0-9_:]*
  * This function:
- * - Converts to lowercase (Prometheus convention)
+ * - Converts to lowercase
  * - Replaces hyphens and spaces with underscores
  * - Removes invalid characters
  * - Ensures the name starts with a letter or underscore
- *
- * @param name Name component to normalize
- * @returns Normalized name safe for Prometheus
  */
 function normalizeMetricName(name) {
-    // Convert to lowercase (Prometheus convention)
     let normalized = name.toLowerCase();
-    // Replace hyphens and spaces with underscores
     normalized = normalized.replace(/[-\s]/g, '_');
-    // Remove any characters that aren't alphanumeric, underscore, or colon
     normalized = normalized.replace(/[^a-z0-9_:]/g, '_');
-    // Ensure it starts with a letter or underscore
     if (!/^[a-z_]/.test(normalized)) {
         normalized = `_${normalized}`;
     }
     return normalized;
 }
 /**
- * Adds service_name label to existing labelNames if not already present
+ * Adds service_name attribute to provided attributes
  */
-function ensureServiceNameLabel(labelNames) {
-    const labels = labelNames ? [...labelNames] : [];
-    if (!labels.includes('service_name')) {
-        labels.unshift('service_name');
+function withServiceName(attrs) {
+    const result = { service_name: getServiceName() };
+    if (attrs) {
+        for (const [key, value] of Object.entries(attrs)) {
+            // Skip service_name to prevent overriding the enforced value
+            if (key === 'service_name') {
+                continue;
+            }
+            if (value !== undefined) {
+                result[key] = value;
+            }
+        }
     }
-    return labels;
+    return result;
 }
 /**
- * Wraps a Counter to automatically inject service_name label
+ * Wraps an OTel Counter to automatically inject service_name attribute
  */
 class ServiceAwareCounter {
-    constructor(config, serviceName) {
-        this.counter = new prom_client_1.Counter(config);
-        this.serviceName = serviceName;
+    constructor(counter) {
+        this.counter = counter;
     }
-    inc(labelsOrValue, value) {
+    inc(labelsOrValue, maybeValue) {
+        let value;
+        let labels;
         if (typeof labelsOrValue === 'number') {
-            // inc(value) signature
-            this.counter.inc({ service_name: this.serviceName }, labelsOrValue);
+            value = labelsOrValue;
+            labels = undefined;
         }
         else {
-            // inc(labels, value) signature
-            const labelsWithService = { ...labelsOrValue, service_name: this.serviceName };
-            this.counter.inc(labelsWithService, value);
+            value = typeof maybeValue === 'number' ? maybeValue : 1;
+            labels = labelsOrValue;
+        }
+        if (value < 0) {
+            throw new RangeError(`Counter increment must be non-negative, got ${value}. Counters can only increase.`);
         }
+        this.counter.add(value, withServiceName(labels));
     }
     reset() {
-        this.counter.reset();
-    }
-    remove(...labelValues) {
-        // Prepend service_name to match how inc() adds it
-        this.counter.remove(this.serviceName, ...labelValues);
+        // No-op: OTel counters cannot be reset; method kept for API compatibility
     }
 }
 /**
- * Wraps a Histogram to automatically inject service_name label
+ * Wraps an OTel Histogram to automatically inject service_name attribute
  */
 class ServiceAwareHistogram {
-    constructor(config, serviceName) {
-        this.histogram = new prom_client_1.Histogram(config);
-        this.serviceName = serviceName;
+    constructor(histogram) {
+        this.histogram = histogram;
     }
-    observe(labelsOrValue, value) {
+    observe(labelsOrValue, maybeValue) {
         if (typeof labelsOrValue === 'number') {
-            // observe(value) signature
-            this.histogram.observe({ service_name: this.serviceName }, labelsOrValue);
+            this.histogram.record(labelsOrValue, withServiceName());
         }
-        else if (value !== undefined) {
-            // observe(labels, value) signature
-            const labelsWithService = { ...labelsOrValue, service_name: this.serviceName };
-            this.histogram.observe(labelsWithService, value);
+        else if (typeof maybeValue === 'number') {
+            this.histogram.record(maybeValue, withServiceName(labelsOrValue));
         }
         else {
-            // Invalid call: labels provided but value is missing
-            throw new Error('ServiceAwareHistogram.observe() called with labels but missing value. ' +
-                'Usage: observe(value) or observe(labels, value)');
+            throw new Error('ServiceAwareHistogram.observe() called with labels but missing value. Usage: observe(value) or observe(labels, value)');
         }
     }
     reset() {
-        this.histogram.reset();
-    }
-    remove(...labelValues) {
-        // Prepend service_name to match how observe() adds it
-        this.histogram.remove(this.serviceName, ...labelValues);
+        // No-op: OTel histograms cannot be reset; method kept for API compatibility
     }
     startTimer(labels) {
-        const labelsWithService = { ...labels, service_name: this.serviceName };
-        const endTimer = this.histogram.startTimer(labelsWithService);
-        // Return wrapper to ensure service_name cannot be overridden on completion
+        const start = globalThis.performance.now();
         return (completionLabels) => {
-            const completionWithService = {
-                ...completionLabels,
-                service_name: this.serviceName,
-            };
-            return endTimer(completionWithService);
+            const duration = (globalThis.performance.now() - start) / 1000;
+            this.observe({ ...(labels || {}), ...(completionLabels || {}) }, duration);
+            return duration;
         };
     }
-    zero(labels) {
-        const labelsWithService = { ...labels, service_name: this.serviceName };
-        this.histogram.zero(labelsWithService);
+    zero(_labels) {
+        // No-op: Histograms do not support explicit zeroing in OTel
     }
 }
 /**
- * Wraps a Gauge to automatically inject service_name label
+ * Wraps an OTel UpDownCounter to emulate gauge set/inc/dec with service_name.
  */
 class ServiceAwareGauge {
-    constructor(config, serviceName) {
-        this.gauge = new prom_client_1.Gauge(config);
-        this.serviceName = serviceName;
-    }
-    addServiceLabel(labels) {
-        return { ...labels, service_name: this.serviceName };
+    constructor(upDownCounter) {
+        this.upDownCounter = upDownCounter;
+        this.values = new Map();
     }
-    inc(labelsOrValue, value) {
-        if (typeof labelsOrValue === 'number') {
-            this.gauge.inc({ service_name: this.serviceName }, labelsOrValue);
-        }
-        else {
-            this.gauge.inc(this.addServiceLabel(labelsOrValue), value);
-        }
+    /**
+     * Generate a stable key for label sets by sorting entries and serializing to JSON.
+     * Note: numeric and string label values are treated as distinct (e.g., 1 vs "1").
+     */
+    keyFromLabels(labels) {
+        const sortedEntries = Object.entries(labels).sort(([a], [b]) => a.localeCompare(b));
+        return JSON.stringify(Object.fromEntries(sortedEntries));
     }
-    dec(labelsOrValue, value) {
+    parseArgs(labelsOrValue, maybeValue, defaultValue = 1) {
         if (typeof labelsOrValue === 'number') {
-            this.gauge.dec({ service_name: this.serviceName }, labelsOrValue);
-        }
-        else {
-            this.gauge.dec(this.addServiceLabel(labelsOrValue), value);
+            return { labels: {}, value: labelsOrValue };
         }
+        return {
+            labels: labelsOrValue || {},
+            value: typeof maybeValue === 'number' ? maybeValue : defaultValue,
+        };
     }
-    set(labelsOrValue, value) {
+    inc(labelsOrValue, maybeValue) {
+        const { labels, value } = this.parseArgs(labelsOrValue, maybeValue);
+        const attrs = withServiceName(labels);
+        const key = this.keyFromLabels(attrs);
+        const previousValue = this.values.get(key) ?? 0;
+        this.values.set(key, previousValue + value);
+        this.upDownCounter.add(value, attrs);
+    }
+    dec(labelsOrValue, maybeValue) {
+        const { labels, value } = this.parseArgs(labelsOrValue, maybeValue);
+        const attrs = withServiceName(labels);
+        const key = this.keyFromLabels(attrs);
+        const previousValue = this.values.get(key) ?? 0;
+        this.values.set(key, previousValue - value);
+        this.upDownCounter.add(-value, attrs);
+    }
+    set(labelsOrValue, maybeValue) {
+        let labels;
+        let newValue;
         if (typeof labelsOrValue === 'number') {
-            this.gauge.set({ service_name: this.serviceName }, labelsOrValue);
+            labels = {};
+            newValue = labelsOrValue;
         }
-        else if (value !== undefined) {
-            this.gauge.set(this.addServiceLabel(labelsOrValue), value);
+        else if (typeof maybeValue === 'number') {
+            labels = labelsOrValue;
+            newValue = maybeValue;
         }
         else {
-            // Invalid call: labels provided but value is missing
-            throw new Error('ServiceAwareGauge.set() called with labels but missing value. ' +
-                'Usage: set(value) or set(labels, value)');
+            throw new Error('ServiceAwareGauge.set() called with labels but missing value. Usage: set(value) or set(labels, value)');
         }
+        const attrs = withServiceName(labels);
+        const key = this.keyFromLabels(attrs);
+        const previousValue = this.values.get(key) ?? 0;
+        const delta = newValue - previousValue;
+        this.values.set(key, newValue);
+        this.upDownCounter.add(delta, attrs);
     }
     setToCurrentTime(labels) {
-        this.gauge.setToCurrentTime(this.addServiceLabel(labels));
+        this.set(labels || {}, Date.now() / 1000);
     }
     startTimer(labels) {
-        const endTimer = this.gauge.startTimer(this.addServiceLabel(labels));
-        // Return wrapper to ensure service_name cannot be overridden on completion
+        const start = globalThis.performance.now();
         return (completionLabels) => {
-            return endTimer(this.addServiceLabel(completionLabels));
+            const duration = (globalThis.performance.now() - start) / 1000;
+            this.set({ ...(labels || {}), ...(completionLabels || {}) }, duration);
+            return duration;
         };
     }
     reset() {
-        this.gauge.reset();
-    }
-    remove(...labelValues) {
-        // Prepend service_name to match how set()/inc()/dec() add it
-        this.gauge.remove(this.serviceName, ...labelValues);
+        // Emit compensating deltas to zero out the underlying UpDownCounter
+        for (const [key, previousValue] of this.values.entries()) {
+            const attrs = JSON.parse(key);
+            this.upDownCounter.add(-previousValue, attrs);
+        }
+        this.values.clear();
+    }
+    remove(name) {
+        // Build labels object from name or use it directly
+        let labels;
+        if (typeof name === 'string') {
+            // If a single name is provided, treat it as the first label value
+            // This is a simplified implementation - full prom-client compatibility would need label ordering
+            labels = {};
+        }
+        else {
+            labels = name || {};
+        }
+        const attrs = withServiceName(labels);
+        const key = this.keyFromLabels(attrs);
+        const storedValue = this.values.get(key);
+        if (storedValue !== undefined) {
+            // Undo the metric contribution by subtracting the stored value
+            this.upDownCounter.add(-storedValue, attrs);
+            // Remove from the map
+            this.values.delete(key);
+        }
+        // If not present, no-op (guard against double-removal)
     }
 }
 /**
  * Creates a counter metric
- *
- * Counters are cumulative metrics that only increase.
- * Use for counting events like requests, errors, items processed, etc.
- *
- * The metric name will be automatically suffixed with '_total' if not already present.
- * A service_name label is automatically added to all observations.
- *
- * @param config Counter configuration (name, help, labelNames)
- * @returns A new Counter instance registered with the custom registry
- *
- * @example
- * ```typescript
- * import { createCounter } from '@manifest-cyber/observability-ts';
- *
- * // Simple counter - automatically suffixed with _total
- * export const requestsTotal = createCounter({
- *   name: 'http_requests',
- *   help: 'Total number of HTTP requests',
- *   labelNames: ['method', 'status'],
- * });
- *
- * // Or provide the full name (won't duplicate suffix)
- * export const requestsTotal = createCounter({
- *   name: 'http_requests_total',
- *   help: 'Total number of HTTP requests',
- *   labelNames: ['method', 'status'],
- * });
- *
- * // Later in code (service_name is automatically added):
- * requestsTotal.inc({ method: 'GET', status: '200' });
- * // Results in: http_requests_total{service_name="my-service",method="GET",status="200"}
- * ```
  */
 function createCounter(config) {
-    // Validate configuration
     if (!config.name || config.name.trim().length === 0) {
         throw new Error('Counter name is required and cannot be empty');
     }
@@ -269,83 +303,22 @@ function createCounter(config) {
         config.labelNames.some((label) => !label || label.trim().length === 0)) {
         throw new Error('All label names must be non-empty strings');
     }
-    // Normalize the metric name first
     const normalizedName = normalizeMetricName(config.name);
-    // Auto-suffix with _total if not already present (prevents duplication)
-    const name = normalizedName.endsWith('_total')
+    const fullName = normalizedName.endsWith('_total')
         ? normalizedName
         : `${normalizedName}_total`;
-    // Add service_name to labelNames
-    const labelNames = ensureServiceNameLabel(config.labelNames);
-    return new ServiceAwareCounter({
-        ...config,
-        name,
-        labelNames,
-        registers: [(0, registry_1.getRegistry)()],
-    }, getServiceName());
+    // Use the global metrics API which returns a no-op meter if not initialized.
+    // This allows builders to work without explicit initMetricsProvider() call.
+    const meter = api_1.metrics.getMeter(getServiceName());
+    const counter = meter.createCounter(fullName, {
+        description: config.help,
+    });
+    return new ServiceAwareCounter(counter);
 }
 /**
  * Creates a histogram metric
- *
- * Histograms track distributions of values, commonly used for durations.
- * They automatically track count, sum, and buckets.
- *
- * The metric name will be automatically suffixed with a unit (default: '_seconds') if not already present.
- * A service_name label is automatically added to all observations.
- *
- * **Unit detection and auto-suffixing:**
- * - If name already has a unit suffix (e.g., '_seconds', '_bytes'), it's used as-is
- * - If name lacks a unit suffix, the `unit` parameter is appended (default: 'seconds')
- * - If name has a unit AND `unit` parameter differs, a warning is logged and name's unit wins
- *
- * @param config Histogram configuration (name, help, labelNames, buckets, unit)
- * @returns A new Histogram instance registered with the custom registry
- *
- * @example
- * ```typescript
- * import { createHistogram, BUCKETS } from '@manifest-cyber/observability-ts';
- *
- * // Duration metric - automatically suffixed with _seconds (default)
- * export const requestDuration = createHistogram({
- *   name: 'http_request_duration',
- *   help: 'HTTP request duration in seconds',
- *   labelNames: ['method', 'route'],
- *   buckets: BUCKETS.DURATION.HTTP,
- * });
- * // Result: http_request_duration_seconds
- *
- * // File size metric with custom unit
- * export const fileSize = createHistogram({
- *   name: 'file_size',
- *   help: 'File size in bytes',
- *   unit: 'bytes',
- *   buckets: BUCKETS.SIZE.MEDIUM,
- * });
- * // Result: file_size_bytes
- *
- * // Provide full name (won't duplicate suffix)
- * export const fileSize2 = createHistogram({
- *   name: 'file_size_bytes',
- *   help: 'File size in bytes',
- *   buckets: BUCKETS.SIZE.MEDIUM,
- * });
- * // Result: file_size_bytes
- *
- * // Conflict scenario (logs warning, uses name's unit)
- * export const duration = createHistogram({
- *   name: 'processing_time_milliseconds',
- *   unit: 'seconds', // Warning: conflicts with _milliseconds in name
- *   buckets: BUCKETS.DURATION.FAST,
- * });
- * // Result: processing_time_milliseconds (name wins, warning logged)
- *
- * // Later in code (service_name is automatically added):
- * const duration = (Date.now() - start) / 1000;
- * requestDuration.observe({ method: 'GET', route: '/api/users' }, duration);
- * ```
  */
 function createHistogram(config) {
-    // Validate configuration
     if (!config.name || config.name.trim().length === 0) {
         throw new Error('Histogram name is required and cannot be empty');
     }
@@ -357,15 +330,21 @@ function createHistogram(config) {
         throw new Error('All label names must be non-empty strings');
     }
     if (config.buckets && (!Array.isArray(config.buckets) || config.buckets.length === 0)) {
-        throw new Error('Histogram buckets must be a non-empty array');
-    }
-    if (config.buckets &&
-        config.buckets.some((bucket) => typeof bucket !== 'number' || bucket < 0)) {
-        throw new Error('All histogram buckets must be non-negative numbers');
+        throw new Error('Histogram buckets must be a non-empty array of finite, strictly increasing numbers');
+    }
+    if (config.buckets) {
+        // Validate all buckets are finite, non-negative numbers in strictly increasing order
+        for (let i = 0; i < config.buckets.length; i++) {
+            const bucket = config.buckets[i];
+            if (typeof bucket !== 'number' || !Number.isFinite(bucket) || bucket < 0) {
+                throw new Error('All histogram buckets must be finite, non-negative numbers in strictly increasing order');
+            }
+            if (i > 0 && bucket <= config.buckets[i - 1]) {
+                throw new Error('All histogram buckets must be finite, non-negative numbers in strictly increasing order');
+            }
+        }
     }
-    // Normalize the metric name first to handle hyphens, spaces, etc.
     const normalizedBase = normalizeMetricName(config.name);
-    // Check if normalized name already has a unit suffix
     const commonUnits = [
         'seconds',
         'milliseconds',
@@ -379,7 +358,6 @@ function createHistogram(config) {
         'ratio',
         'count',
     ];
-    // Detect if normalized name already has a unit suffix and extract it
     let detectedUnit;
     for (const unit of commonUnits) {
         if (normalizedBase.endsWith(`_${unit}`)) {
@@ -387,57 +365,27 @@ function createHistogram(config) {
             break;
         }
     }
-    // Warn if there's a conflict between detected unit and provided unit parameter
     if (detectedUnit && config.unit && config.unit !== detectedUnit) {
-        console.warn(`Warning: Histogram name '${config.name}' already contains unit suffix '_${detectedUnit}', ` +
-            `but unit parameter is set to '${config.unit}'. Using unit from name: '${detectedUnit}'.`);
+        console.warn(`Warning: Histogram name '${config.name}' already contains unit suffix '_${detectedUnit}', but unit parameter is set to '${config.unit}'. Using unit from name: '${detectedUnit}'.`);
     }
-    // Determine final unit and name with suffix
-    // Priority: 1) Unit in name (if present), 2) unit parameter, 3) default 'seconds'
     const finalUnit = detectedUnit || config.unit || 'seconds';
     const name = detectedUnit ? normalizedBase : `${normalizedBase}_${finalUnit}`;
-    // Add service_name to labelNames
-    const labelNames = ensureServiceNameLabel(config.labelNames);
-    // Remove the custom 'unit' property before passing to Histogram constructor
-    const { unit: _, ...histogramConfig } = config;
-    return new ServiceAwareHistogram({
-        ...histogramConfig,
-        name,
-        labelNames,
-        registers: [(0, registry_1.getRegistry)()],
-    }, getServiceName());
+    // Use the global metrics API which returns a no-op meter if not initialized.
+    // This allows builders to work without explicit initMetricsProvider() call.
+    const meter = api_1.metrics.getMeter(getServiceName());
+    const histogram = meter.createHistogram(name, {
+        description: config.help,
+        unit: finalUnit,
+        advice: {
+            explicitBucketBoundaries: config.buckets,
+        },
+    });
+    return new ServiceAwareHistogram(histogram);
 }
 /**
  * Creates a gauge metric
- *
- * Gauges represent a value that can go up or down.
- * Use for measuring current state like memory usage, active connections, queue depth, etc.
- *
- * The metric name should follow Prometheus naming conventions.
- * A service_name label is automatically added to all observations.
- *
- * @param config Gauge configuration (name, help, labelNames)
- * @returns A new Gauge instance registered with the custom registry
- *
- * @example
- * ```typescript
- * import { createGauge } from '@manifest-cyber/observability-ts';
- *
- * // Simple gauge metric
- * export const activeConnections = createGauge({
- *   name: 'active_connections',
- *   help: 'Number of active connections',
- *   labelNames: ['type'],
- * });
- *
- * // Later in code (service_name is automatically added):
- * activeConnections.inc({ type: 'websocket' });  // increment
- * activeConnections.dec({ type: 'websocket' });  // decrement
- * activeConnections.set({ type: 'http' }, 42);   // set to specific value
- * ```
  */
 function createGauge(config) {
-    // Validate configuration
     if (!config.name || config.name.trim().length === 0) {
         throw new Error('Gauge name is required and cannot be empty');
     }
@@ -448,15 +396,14 @@ function createGauge(config) {
         config.labelNames.some((label) => !label || label.trim().length === 0)) {
         throw new Error('All label names must be non-empty strings');
     }
-    // Normalize the metric name
     const name = normalizeMetricName(config.name);
-    // Add service_name to labelNames
-    const labelNames = ensureServiceNameLabel(config.labelNames);
-    return new ServiceAwareGauge({
-        ...config,
-        name,
-        labelNames,
-        registers: [(0, registry_1.getRegistry)()],
-    }, getServiceName());
+    // Use the global metrics API which returns a no-op meter if not initialized.
+    // This allows builders to work without explicit initMetricsProvider() call.
+    const meter = api_1.metrics.getMeter(getServiceName());
+    // Use UpDownCounter to emulate a gauge (supports inc/dec/set operations)
+    const upDownCounter = meter.createUpDownCounter(name, {
+        description: config.help,
+    });
+    return new ServiceAwareGauge(upDownCounter);
 }
 //# sourceMappingURL=builders.js.map