@zenvark/prom 1.1.1 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @zenvark/prom
 
-Prometheus metrics integration for [Zenvark Circuit Breaker](https://github.com/zenvark/zenvark).
+Prometheus metrics integration for the [Zenvark](https://www.npmjs.com/package/zenvark) circuit breaker and adaptive semaphore.
 
 ## Installation
 
@@ -40,19 +40,56 @@ const circuitBreaker = new CircuitBreaker({
 await circuitBreaker.start();
 ```
 
+For the adaptive semaphore, pass `PrometheusSemaphoreMetrics` the same way:
+
+```typescript
+import { AdaptiveSemaphore } from "zenvark";
+import { PrometheusSemaphoreMetrics } from "@zenvark/prom";
+import { register } from "prom-client";
+
+const semaphore = new AdaptiveSemaphore({
+  id: "my-provider-api",
+  redis,
+  initialLimit: 10,
+  maxLimit: 1000,
+  metrics: new PrometheusSemaphoreMetrics({
+    registry: register,
+    customLabels: { service: "my-api", environment: "production" },
+  }),
+});
+```
+
 ## Available Metrics
 
-| Metric                                 | Type      | Description                      | Labels                         |
-| -------------------------------------- | --------- | -------------------------------- | ------------------------------ |
-| `zenvark_call_duration_seconds`        | Histogram | Duration of protected calls      | `breaker_id`, `result`         |
-| `zenvark_blocked_requests_total`       | Counter   | Requests blocked by open circuit | `breaker_id`                   |
-| `zenvark_healthcheck_duration_seconds` | Histogram | Health check attempt duration    | `breaker_id`, `type`, `result` |
+### Circuit breaker
+
+| Metric                                 | Type      | Description                                  | Labels                         |
+| -------------------------------------- | --------- | -------------------------------------------- | ------------------------------ |
+| `zenvark_call_duration_seconds`        | Histogram | Duration of protected calls                  | `breaker_id`, `result`         |
+| `zenvark_blocked_requests_total`       | Counter   | Requests blocked by open circuit             | `breaker_id`                   |
+| `zenvark_healthcheck_duration_seconds` | Histogram | Health check attempt duration                | `breaker_id`, `type`, `result` |
+| `zenvark_state`                        | Gauge     | Circuit state (active state 1, all others 0) | `breaker_id`, `state`          |
+
+### Semaphore
+
+| Metric                                    | Type      | Description                                 | Labels                             |
+| ----------------------------------------- | --------- | ------------------------------------------- | ---------------------------------- |
+| `zenvark_semaphore_acquire_wait_seconds`  | Histogram | Time spent waiting for a lease              | `semaphore_id`, `class`, `result`  |
+| `zenvark_semaphore_hold_duration_seconds` | Histogram | Time a lease was held                       | `semaphore_id`, `class`, `outcome` |
+| `zenvark_semaphore_limit`                 | Gauge     | This process's view of the fleet-wide limit | `semaphore_id`                     |
+| `zenvark_semaphore_throttle_events_total` | Counter   | Caller-reported throttle events             | `semaphore_id`                     |
+
+The limit gauge is set on every process whose cached view changes, so a scrape of any instance reads the current fleet-wide limit. Sum or average across instances accordingly.
 
 ### Label Values
 
 - `breaker_id` - Circuit breaker instance identifier
 - `type` - Health check type: `recovery` or `idle`
-- `result` - Outcome: `success` or `failure`
+- `result` - Breaker call outcome (`success` or `failure`), or semaphore acquire outcome (`acquired` or `timeout`)
+- `state` - Circuit state: `closed` or `open`
+- `semaphore_id` - Semaphore instance identifier
+- `class` - Semaphore priority class (empty when acquired without a class)
+- `outcome` - Lease release outcome: `success`, `throttled` or `failure`
 - Custom labels - Additional key-value pairs from configuration
 
 ## Custom Labels

package/dist/get-or-create-metric.d.ts

@@ -1,3 +1,4 @@
-import { Counter, type CounterConfiguration, Histogram, type HistogramConfiguration, type Registry } from 'prom-client';
+import { Counter, type CounterConfiguration, Gauge, type GaugeConfiguration, Histogram, type HistogramConfiguration, type Registry } from 'prom-client';
 export declare const getOrCreateCounter: <TLabels extends string>(register: Registry, config: CounterConfiguration<TLabels>) => Counter<TLabels>;
 export declare const getOrCreateHistogram: <TLabels extends string>(register: Registry, config: HistogramConfiguration<TLabels>) => Histogram<TLabels>;
+export declare const getOrCreateGauge: <TLabels extends string>(register: Registry, config: GaugeConfiguration<TLabels>) => Gauge<TLabels>;

package/dist/get-or-create-metric.js

@@ -1,4 +1,4 @@
-import { Counter, Histogram, } from 'prom-client';
+import { Counter, Gauge, Histogram, } from 'prom-client';
 const getTypeParam = (obj) => {
     if (typeof obj === 'object' &&
         obj !== null &&
@@ -21,4 +21,11 @@ export const getOrCreateHistogram = (register, config) => {
     const existingMetric = register.getSingleMetric(config.name);
     return isHistogram(existingMetric) ? existingMetric : new Histogram(config);
 };
+const isGauge = (metric) => {
+    return metric instanceof Gauge || getTypeParam(metric) === 'gauge';
+};
+export const getOrCreateGauge = (register, config) => {
+    const existingMetric = register.getSingleMetric(config.name);
+    return isGauge(existingMetric) ? existingMetric : new Gauge(config);
+};
 //# sourceMappingURL=get-or-create-metric.js.map

package/dist/get-or-create-metric.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-or-create-metric.js","sourceRoot":"","sources":["../src/get-or-create-metric.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EAEP,SAAS,GAGV,MAAM,aAAa,CAAC;AAErB,MAAM,YAAY,GAAG,CAAC,GAAY,EAAsB,EAAE;IACxD,IACE,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,MAAM,IAAI,GAAG;QACb,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAC5B,CAAC;QACD,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,SAAS,GAAG,CAAC,MAAe,EAAqB,EAAE;IACvD,OAAO,MAAM,YAAY,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC,KAAK,SAAS,CAAC;AACzE,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,QAAkB,EAClB,MAAqC,EACnB,EAAE;IACpB,MAAM,cAAc,GAAG,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7D,OAAO,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;AAC1E,CAAC,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,MAAe,EAAuB,EAAE;IAC3D,OAAO,MAAM,YAAY,SAAS,IAAI,YAAY,CAAC,MAAM,CAAC,KAAK,WAAW,CAAC;AAC7E,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,QAAkB,EAClB,MAAuC,EACnB,EAAE;IACtB,MAAM,cAAc,GAAG,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7D,OAAO,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;AAC9E,CAAC,CAAC"}
+{"version":3,"file":"get-or-create-metric.js","sourceRoot":"","sources":["../src/get-or-create-metric.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EAEP,KAAK,EAEL,SAAS,GAGV,MAAM,aAAa,CAAC;AAErB,MAAM,YAAY,GAAG,CAAC,GAAY,EAAsB,EAAE;IACxD,IACE,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,MAAM,IAAI,GAAG;QACb,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAC5B,CAAC;QACD,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,SAAS,GAAG,CAAC,MAAe,EAAqB,EAAE;IACvD,OAAO,MAAM,YAAY,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC,KAAK,SAAS,CAAC;AACzE,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,QAAkB,EAClB,MAAqC,EACnB,EAAE;IACpB,MAAM,cAAc,GAAG,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7D,OAAO,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;AAC1E,CAAC,CAAC;AAEF,MAAM,WAAW,GAAG,CAAC,MAAe,EAAuB,EAAE;IAC3D,OAAO,MAAM,YAAY,SAAS,IAAI,YAAY,CAAC,MAAM,CAAC,KAAK,WAAW,CAAC;AAC7E,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,QAAkB,EAClB,MAAuC,EACnB,EAAE;IACtB,MAAM,cAAc,GAAG,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7D,OAAO,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;AAC9E,CAAC,CAAC;AAEF,MAAM,OAAO,GAAG,CAAC,MAAe,EAAmB,EAAE;IACnD,OAAO,MAAM,YAAY,KAAK,IAAI,YAAY,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC;AACrE,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,QAAkB,EAClB,MAAmC,EACnB,EAAE;IAClB,MAAM,cAAc,GAAG,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7D,OAAO,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;AACtE,CAAC,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { getOrCreateCounter, getOrCreateHistogram, } from './get-or-create-metric.ts';
 export { PrometheusBreakerMetrics, type PrometheusBreakerMetricsOptions, } from './prometheus-breaker-metrics.ts';
+export { PrometheusSemaphoreMetrics, type PrometheusSemaphoreMetricsOptions, } from './prometheus-semaphore-metrics.ts';

package/dist/index.js

@@ -1,3 +1,4 @@
 export { getOrCreateCounter, getOrCreateHistogram, } from "./get-or-create-metric.js";
 export { PrometheusBreakerMetrics, } from "./prometheus-breaker-metrics.js";
+export { PrometheusSemaphoreMetrics, } from "./prometheus-semaphore-metrics.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,wBAAwB,GAEzB,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,wBAAwB,GAEzB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACL,0BAA0B,GAE3B,MAAM,mCAAmC,CAAC"}

package/dist/prometheus-breaker-metrics.d.ts

@@ -1,5 +1,5 @@
 import type { Registry } from 'prom-client';
-import type { BreakerMetricsRecorder, RecordBlockedRequestParams, RecordCallParams, RecordHealthCheckParams } from 'zenvark';
+import type { BreakerMetricsRecorder, RecordBlockedRequestParams, RecordCallParams, RecordHealthCheckParams, RecordStateChangeParams } from 'zenvark';
 export type PrometheusBreakerMetricsOptions = {
     /**
      * Prometheus registry instance
@@ -19,6 +19,7 @@ export declare class PrometheusBreakerMetrics implements BreakerMetricsRecorder
     private readonly callDurationHistogram;
     private readonly blockedRequestsCounter;
     private readonly healthcheckDurationHistogram;
+    private readonly stateGauge;
     constructor(options: PrometheusBreakerMetricsOptions);
     /**
      * Initialize metrics for a circuit breaker.
@@ -38,4 +39,13 @@ export declare class PrometheusBreakerMetrics implements BreakerMetricsRecorder
      * Record healthcheck attempt
      */
     recordHealthCheck(params: RecordHealthCheckParams): void;
+    /**
+     * Record a circuit state change. Sets the active state label to 1 and all others to 0.
+     */
+    recordStateChange(params: RecordStateChangeParams): void;
+    /**
+     * Remove all state gauge series for a breaker. Called when this node loses leadership
+     * so the ex-leader's stale values disappear from scrapes.
+     */
+    clearState(breakerId: string): void;
 }

package/dist/prometheus-breaker-metrics.js

@@ -1,9 +1,11 @@
-import { getOrCreateCounter, getOrCreateHistogram, } from "./get-or-create-metric.js";
+import { CircuitState } from 'zenvark';
+import { getOrCreateCounter, getOrCreateGauge, getOrCreateHistogram, } from "./get-or-create-metric.js";
 export class PrometheusBreakerMetrics {
     customLabels;
     callDurationHistogram;
     blockedRequestsCounter;
     healthcheckDurationHistogram;
+    stateGauge;
     constructor(options) {
         const prefix = options.prefix ?? 'zenvark';
         this.customLabels = options.customLabels ?? {};
@@ -28,6 +30,12 @@ export class PrometheusBreakerMetrics {
             buckets: [0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
             registers: [options.registry],
         });
+        this.stateGauge = getOrCreateGauge(options.registry, {
+            name: `${prefix}_state`,
+            help: 'Current state of the circuit breaker. The active state label has value 1, all others 0.',
+            labelNames: ['breaker_id', 'state', ...customLabelNames],
+            registers: [options.registry],
+        });
     }
     /**
      * Initialize metrics for a circuit breaker.
@@ -70,5 +78,22 @@ export class PrometheusBreakerMetrics {
         });
         this.healthcheckDurationHistogram.observe(labels, params.durationMs / 1000);
     }
+    /**
+     * Record a circuit state change. Sets the active state label to 1 and all others to 0.
+     */
+    recordStateChange(params) {
+        for (const state of Object.values(CircuitState)) {
+            this.stateGauge.set(this.getLabels(params.breakerId, { state }), params.state === state ? 1 : 0);
+        }
+    }
+    /**
+     * Remove all state gauge series for a breaker. Called when this node loses leadership
+     * so the ex-leader's stale values disappear from scrapes.
+     */
+    clearState(breakerId) {
+        for (const state of Object.values(CircuitState)) {
+            this.stateGauge.remove(this.getLabels(breakerId, { state }));
+        }
+    }
 }
 //# sourceMappingURL=prometheus-breaker-metrics.js.map

package/dist/prometheus-breaker-metrics.js.map

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

package/dist/prometheus-semaphore-metrics.d.ts

@@ -0,0 +1,46 @@
+import type { Registry } from 'prom-client';
+import type { RecordAcquireParams, RecordLimitChangeParams, RecordReleaseParams, RecordThrottleParams, SemaphoreMetricsRecorder } from 'zenvark';
+export type PrometheusSemaphoreMetricsOptions = {
+    /**
+     * Prometheus registry instance
+     */
+    registry: Registry;
+    /**
+     * Prefix for all metric names (default: 'zenvark')
+     */
+    prefix?: string;
+    /**
+     * Custom labels to add to all metrics
+     */
+    customLabels?: Record<string, string>;
+};
+export declare class PrometheusSemaphoreMetrics implements SemaphoreMetricsRecorder {
+    private readonly customLabels;
+    private readonly acquireWaitHistogram;
+    private readonly holdDurationHistogram;
+    private readonly limitGauge;
+    private readonly throttleEventsCounter;
+    constructor(options: PrometheusSemaphoreMetricsOptions);
+    /**
+     * Initialize metrics for a semaphore.
+     * Sets the throttle counter to 0 so the metric appears in scrapes immediately.
+     */
+    initialize(id: string): void;
+    private getLabels;
+    /**
+     * Record the outcome of an acquire attempt and the time spent waiting
+     */
+    recordAcquire(params: RecordAcquireParams): void;
+    /**
+     * Record a lease release with its outcome and hold duration
+     */
+    recordRelease(params: RecordReleaseParams): void;
+    /**
+     * Record a change of the cached fleet-wide limit
+     */
+    recordLimitChange(params: RecordLimitChangeParams): void;
+    /**
+     * Record a caller-reported throttle event
+     */
+    recordThrottle(params: RecordThrottleParams): void;
+}

package/dist/prometheus-semaphore-metrics.js

@@ -0,0 +1,89 @@
+import { getOrCreateCounter, getOrCreateGauge, getOrCreateHistogram, } from "./get-or-create-metric.js";
+export class PrometheusSemaphoreMetrics {
+    customLabels;
+    acquireWaitHistogram;
+    holdDurationHistogram;
+    limitGauge;
+    throttleEventsCounter;
+    constructor(options) {
+        const prefix = options.prefix ?? 'zenvark';
+        this.customLabels = options.customLabels ?? {};
+        const customLabelNames = Object.keys(this.customLabels);
+        this.acquireWaitHistogram = getOrCreateHistogram(options.registry, {
+            name: `${prefix}_semaphore_acquire_wait_seconds`,
+            help: 'Time spent waiting for a semaphore lease in seconds, by acquire result.',
+            labelNames: ['semaphore_id', 'class', 'result', ...customLabelNames],
+            buckets: [0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+            registers: [options.registry],
+        });
+        this.holdDurationHistogram = getOrCreateHistogram(options.registry, {
+            name: `${prefix}_semaphore_hold_duration_seconds`,
+            help: 'Time a semaphore lease was held in seconds, by release outcome.',
+            labelNames: ['semaphore_id', 'class', 'outcome', ...customLabelNames],
+            buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60],
+            registers: [options.registry],
+        });
+        this.limitGauge = getOrCreateGauge(options.registry, {
+            name: `${prefix}_semaphore_limit`,
+            help: "This process's cached view of the fleet-wide semaphore limit.",
+            labelNames: ['semaphore_id', ...customLabelNames],
+            registers: [options.registry],
+        });
+        this.throttleEventsCounter = getOrCreateCounter(options.registry, {
+            name: `${prefix}_semaphore_throttle_events_total`,
+            help: 'Total number of THROTTLED releases reported by callers.',
+            labelNames: ['semaphore_id', ...customLabelNames],
+            registers: [options.registry],
+        });
+    }
+    /**
+     * Initialize metrics for a semaphore.
+     * Sets the throttle counter to 0 so the metric appears in scrapes immediately.
+     */
+    initialize(id) {
+        const labels = this.getLabels(id);
+        this.throttleEventsCounter.inc(labels, 0);
+    }
+    getLabels(semaphoreId, additionalLabels = {}) {
+        return {
+            ...this.customLabels,
+            semaphore_id: semaphoreId,
+            ...additionalLabels,
+        };
+    }
+    /**
+     * Record the outcome of an acquire attempt and the time spent waiting
+     */
+    recordAcquire(params) {
+        const labels = this.getLabels(params.id, {
+            class: params.class ?? '',
+            result: params.result,
+        });
+        this.acquireWaitHistogram.observe(labels, params.waitMs / 1000);
+    }
+    /**
+     * Record a lease release with its outcome and hold duration
+     */
+    recordRelease(params) {
+        const labels = this.getLabels(params.id, {
+            class: params.class ?? '',
+            outcome: params.outcome,
+        });
+        this.holdDurationHistogram.observe(labels, params.heldMs / 1000);
+    }
+    /**
+     * Record a change of the cached fleet-wide limit
+     */
+    recordLimitChange(params) {
+        const labels = this.getLabels(params.id);
+        this.limitGauge.set(labels, params.limit);
+    }
+    /**
+     * Record a caller-reported throttle event
+     */
+    recordThrottle(params) {
+        const labels = this.getLabels(params.id);
+        this.throttleEventsCounter.inc(labels, 1);
+    }
+}
+//# sourceMappingURL=prometheus-semaphore-metrics.js.map

package/dist/prometheus-semaphore-metrics.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenvark/prom",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Prometheus metrics for Zenvark Circuit Breaker",
   "keywords": [
     "zenvark",
@@ -54,10 +54,10 @@
     "rimraf": "^6.0.1",
     "typescript": "5.9.3",
     "vitest": "^4.0.15",
-    "zenvark": "^1.1.1"
+    "zenvark": "^1.3.0"
   },
   "peerDependencies": {
     "prom-client": "^15.0.0",
-    "zenvark": "^1.0.0"
+    "zenvark": "^1.2.0"
   }
 }