lib: replace periodic gauge with a pull gauge

Author: Qard

doc/api/metrics.md

@@ -140,30 +140,29 @@ const t = dbQueryTimer.create({ query: 'SELECT * FROM users' });
 const duration = t.stop(); // Returns duration in milliseconds
 ```
 
-### `metrics.periodicGauge(name, interval, fn[, meta])`
+### `metrics.pullGauge(name, fn[, meta])`
 
 <!-- YAML
 added: REPLACEME
 -->
 
-* `name` {string} The name of the periodic gauge metric.
-* `interval` {number} The interval in milliseconds between samples.
+* `name` {string} The name of the pull gauge metric.
 * `fn` {Function} A function that returns the current value.
 * `meta` {Object} Optional metadata to attach to all reports.
-* Returns: {metrics.PeriodicGauge}
+* Returns: {metrics.PullGauge}
 
-Creates a gauge that automatically samples a value at regular intervals.
+Creates a gauge that samples a value on-demand by calling the provided function.
 
 ```mjs
-import { periodicGauge } from 'node:metrics';
+import { pullGauge } from 'node:metrics';
 import { cpuUsage } from 'node:process';
 
-const cpu = periodicGauge('cpu.usage', 5000, () => {
+const cpu = pullGauge('cpu.usage', () => {
   return cpuUsage().user;
 });
 
-// Stop sampling when no longer needed
-cpu.stop();
+// Sample the gauge when needed
+cpu.sample();
 ```
 
 ## Classes
@@ -184,7 +183,7 @@ added: REPLACEME
 
 * {string}
 
-The type of the metric (e.g., 'counter', 'gauge', 'periodicGauge',
+The type of the metric (e.g., 'counter', 'gauge', 'pullGauge',
 'timer').
 
 #### `metricReport.name`
@@ -301,7 +300,7 @@ added: REPLACEME
 
 * {string}
 
-The type of the metric (e.g., 'counter', 'gauge', 'periodicGauge',
+The type of the metric (e.g., 'counter', 'gauge', 'pullGauge',
 'timer').
 
 #### `metric.name`
@@ -659,17 +658,17 @@ const dbQueryTimer = timer('db.query.duration');
 const t = dbQueryTimer.create({ query: 'SELECT * FROM users' });
 ```
 
-### Class: `PeriodicGauge`
+### Class: `PullGauge`
 
 * Extends: {metrics.Gauge}
 
 <!-- YAML
 added: REPLACEME
 -->
 
-A gauge that automatically samples values at regular intervals.
+A gauge that samples values on-demand when the `sample()` method is called.
 
-#### `periodicGauge.metric`
+#### `pullGauge.metric`
 
 <!-- YAML
 added: REPLACEME
@@ -679,81 +678,31 @@ added: REPLACEME
 
 The underlying metric instance used for reporting.
 
-#### `periodicGauge.interval`
+#### `pullGauge.sample([meta])`
 
 <!-- YAML
 added: REPLACEME
 -->
 
-* {number}
-
-The sampling interval in milliseconds. Setting this property reschedules the timer.
-
-#### `periodicGauge.schedule()`
-
-<!-- YAML
-added: REPLACEME
--->
-
-Schedules the periodic sampling based on the configured interval. This is called
-automatically when the gauge is created, but can be called again to reschedule
-after it has been stopped.
-
-```mjs
-import { periodicGauge } from 'node:metrics';
-import { cpuUsage } from 'node:process';
-
-const cpu = periodicGauge('cpu.usage', 5000, () => {
-  return cpuUsage().user;
-});
-
-cpu.stop();
-
-// Reschedule sampling
-cpu.schedule();
-```
-
-#### `periodicGauge.stop()`
+* `meta` {Object} Additional metadata for this specific sample.
+* Returns: {number} The sampled value.
 
-<!-- YAML
-added: REPLACEME
--->
-
-Stops the periodic sampling.
+Calls the configured function to get the current value and reports it.
 
 ```mjs
-import { periodicGauge } from 'node:metrics';
+import { pullGauge } from 'node:metrics';
 import { cpuUsage } from 'node:process';
 
-const cpu = periodicGauge('cpu.usage', 5000, () => {
+const cpu = pullGauge('cpu.usage', () => {
   return cpuUsage().user;
 });
 
-// Stop sampling when no longer needed
-cpu.stop();
-```
-
-#### `periodicGauge[Symbol.dispose]()`
-
-<!-- YAML
-added: REPLACEME
--->
-
-Allows `using` syntax to automatically stop the periodic gauge when done.
-
-```mjs
-import { periodicGauge } from 'node:metrics';
-import { cpuUsage } from 'node:process';
+// Sample the gauge when needed
+const value = cpu.sample();
+console.log(`Current CPU usage: ${value}`);
 
-{
-  using cpu = periodicGauge('cpu.usage', 1000, () => {
-    return cpuUsage().user;
-  });
-
-  // Perform operations that require periodic sampling...
-
-  // Sampling is automatically stopped here
-}
+// Sample with additional metadata
+cpu.sample({ threshold: 'high' });
 ```
 
 

lib/metrics.js

@@ -6,7 +6,7 @@
  * - Counter: An increasing or decreasing value.
  * - Gauge: A snapshot of a single value in time.
  * - Timer: A duration in milliseconds.
- * - PeriodicGauge: A gauge which periodically updates its value by calling a function.
+ * - PullGauge: A gauge which updates its value by calling a function when sampled.
  * # TODO(qard):
  * - Histograms
  * - Distributions/Summaries
@@ -32,7 +32,6 @@ const {
     ERR_INVALID_ARG_VALUE,
   },
 } = require('internal/errors');
-const { setInterval, clearInterval } = require('internal/timers');
 
 const {
   channel,
@@ -117,7 +116,7 @@ class MetricReport {
     return {
       counter: 'c',
       gauge: 'g',
-      periodicGauge: 'g',
+      pullGauge: 'g',
       timer: 'ms',
     }[type];
   }
@@ -421,96 +420,34 @@ class Timer extends Gauge {
 }
 
 /**
- * A gauge which periodically updates its value by calling a function and
- * setting the value to the result.
+ * A gauge which updates its value by calling a function when sampled.
  */
-class PeriodicGauge extends Gauge {
-  #timer;
-  #interval;
+class PullGauge extends Gauge {
   #fn;
 
   /**
-   * Construct a new periodic gauge.
+   * Construct a new pull gauge.
    * @param {Metric} metric The metric to report to.
-   * @param {number} interval The interval in milliseconds to update the gauge.
-   * @param {Function} fn The function to call to update the gauge.
+   * @param {Function} fn The function to call to get the gauge value.
    */
-  constructor(metric, interval, fn) {
+  constructor(metric, fn) {
     super(metric);
 
-    if (typeof interval !== 'number' || interval <= 0) {
-      throw new ERR_INVALID_ARG_TYPE('interval', ['number'], interval);
-    }
     if (typeof fn !== 'function') {
       throw new ERR_INVALID_ARG_TYPE('fn', ['function'], fn);
     }
 
-    this.#timer = undefined;
-    this.#interval = interval;
     this.#fn = fn;
-
-    this.schedule();
-  }
-
-  /**
-   * Schedule the update timer.
-   */
-  schedule() {
-    this.stop();
-
-    this.#timer = setInterval(() => {
-      this.reset(this.#fn());
-    }, this.interval);
-
-    // Don't keep the process alive just for this timer.
-    this.#timer.unref();
-  }
-
-  /**
-   * The interval in milliseconds at which to update the value. If changed,
-   * the timer will be rescheduled.
-   * @property {number} interval
-   */
-  set interval(interval) {
-    if (typeof interval !== 'number' || interval <= 0) {
-      throw new ERR_INVALID_ARG_TYPE('interval', ['number'], interval);
-    }
-    this.#interval = interval;
-    this.schedule();
-  }
-  get interval() {
-    return this.#interval;
   }
 
   /**
-   * Stop the periodic gauge.
-   */
-  stop() {
-    if (this.#timer !== undefined) {
-      clearInterval(this.#timer);
-      this.#timer = undefined;
-    }
-  }
-
-  /**
-   * Reference the timer to prevent to loop from exiting.
-   */
-  ref() {
-    this.#timer?.ref();
-  }
-
-  /**
-   * Unreference the timer to allow the loop to exit.
-   */
-  unref() {
-    this.#timer?.unref();
-  }
-
-  /**
-   * Support `using` syntax to automatically stop the periodic gauge when done.
+   * Sample the gauge by calling the function and reporting the value.
+   * @param {object} [meta] Additional metadata to include with the report.
    */
-  [SymbolDispose]() {
-    this.stop();
+  sample(meta) {
+    const value = this.#fn();
+    this.reset(value, meta);
+    return value;
   }
 }
 
@@ -561,7 +498,7 @@ function timer(name, meta) {
 const metricTypes = {
   counter: Counter,
   gauge: Gauge,
-  periodicGauge: PeriodicGauge,
+  pullGauge: PullGauge,
   timer: Timer,
 };
 
@@ -619,28 +556,27 @@ function metric(type, name, meta) {
 }
 
 /**
- * Create a periodic gauge metric.
- * @param {string} name The name of the periodic gauge.
- * @param {number} interval The interval in milliseconds to update the gauge.
- * @param {Function} fn The function to call to update the gauge.
+ * Create a pull gauge metric.
+ * @param {string} name The name of the pull gauge.
+ * @param {Function} fn The function to call to get the gauge value.
  * @param {object} [meta] Additional metadata to include with the report.
- * @returns {PeriodicGauge} The periodic gauge metric.
+ * @returns {PullGauge} The pull gauge metric.
  */
-const periodicGauge = direct('periodicGauge');
+const pullGauge = direct('pullGauge');
 
 module.exports = {
   MetricReport,
   Metric,
   Gauge,
   Counter,
   Timer,
-  PeriodicGauge,
+  PullGauge,
   TimerFactory,
 
 
   counter,
   gauge,
   metric,
-  periodicGauge,
+  pullGauge,
   timer,
 };