@emartech/aggregate-metric-logger 6.4.0 → 6.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emartech/aggregate-metric-logger",
-  "version": "6.4.0",
+  "version": "6.5.0",
   "description": "aggregate metrics in memory for logging",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -40,7 +40,7 @@
     "@emartech/rti-server-tools": "11.5.0",
     "@types/jest": "30.0.0",
     "dotenv-haphap": "3.1.2",
-    "eslint": "10.8.1",
+    "eslint": "10.9.0",
     "globals": "17.11.0",
     "jest": "30.4.2",
     "semantic-release": "25.0.9"

package/src/gcp-metric-collector/gcp-metric-collector.js

@@ -5,8 +5,15 @@ const { createGcpTimeSeriesPublisher } = require('../gcp-time-series-publisher/g
 const { createGcpTimeSeriesBuilder } = require('../gcp-time-series-builder/gcp-time-series-builder');
 const { createCounter } = require('../metric-types/counter/counter');
 const { createDistribution } = require('../metric-types/distribution/distribution');
+const { createGauge } = require('../metric-types/gauge/gauge');
 const { isNumber, isPlainObject } = require('lodash');
 
+const aggregatorFactories = {
+  counter: createCounter,
+  distribution: createDistribution,
+  gauge: createGauge
+};
+
 class GcpMetricCollector {
   metrics = {};
   initialized = false;
@@ -33,6 +40,18 @@ class GcpMetricCollector {
     return this.addToMetric(metricName, labels, 'distribution', value);
   }
 
+  gauge(metricName, labels = {}, value) {
+    if (!isNumber(value)) {
+      throw new Error(`${ value } is not a number`);
+    }
+
+    if (!isPlainObject(labels)) {
+      throw new Error('labels is not a plain object');
+    }
+
+    this.addToMetric(metricName, labels, 'gauge', value);
+  }
+
   start(metricName, labels = {}) {
     return { metricName, labels, start: Date.now() };
   }
@@ -55,7 +74,11 @@ class GcpMetricCollector {
     }
     const key = `${metricName}_${stringify(labels)}`;
     if (!this.metrics[key]) {
-      const aggregator = type === 'counter' ? createCounter() : createDistribution();
+      const createAggregator = aggregatorFactories[type];
+      if (!createAggregator) {
+        throw new Error(`unknown metric type: ${type}`);
+      }
+      const aggregator = createAggregator();
       this.metrics[key] = { name: metricName, labels, aggregator };
     }
     this.metrics[key].aggregator.add(value);
@@ -72,12 +95,22 @@ class GcpMetricCollector {
   }
 
   async flush() {
+    await this.publishPending();
+    this.setupNextFlush();
+  }
+
+  async shutdown() {
+    clearTimeout(this.timeoutId);
+    this.initialized = false;
+    await this.publishPending();
+  }
+
+  async publishPending() {
     const timeSeries = createGcpTimeSeriesBuilder(this.projectId).buildTimeSeries(this.metrics);
     for (const [, metric] of Object.entries(this.metrics)) {
       metric.aggregator.advanceTimer();
     }
     await createGcpTimeSeriesPublisher(this.projectId).publishTimeSeries(timeSeries);
-    this.setupNextFlush();
   }
 }
 
@@ -89,10 +122,15 @@ exports.count = (metricName, labels = {}, value = 1) =>
 exports.measure = (metricName, labels = {}, value = 1) =>
   collector.measure(metricName, labels, value);
 
+exports.gauge = (metricName, labels = {}, value) =>
+  collector.gauge(metricName, labels, value);
+
 exports.start = (metricName, labels = {}) => collector.start(metricName, labels);
 
 exports.stop = measurement => collector.stop(measurement);
 
 exports.reset = () => collector.reset();
 
+exports.shutdown = () => collector.shutdown();
+
 exports.createGcpMetricsCollector = projectId => new GcpMetricCollector(projectId);

package/src/gcp-metric-collector/gcp-metric-collector.spec.js

@@ -343,6 +343,160 @@ describe('gcpMetricCollector', () => {
     });
   });
 
+  describe('gauge', () => {
+    it('should send a single gauge value in next flush period', () => {
+      const now = new Date('2026-08-25T12:03:17+00:00');
+      const oneMinuteInMillis = 60 * 1000;
+      jest.useFakeTimers().setSystemTime(now);
+      stubCreateTimeSeries();
+
+      gcpMetricCollector.gauge('job_delay', { programId: 'A' }, 42);
+
+      expect(getPublishedMetrics()).toEqual([]);
+
+      jest.advanceTimersByTime(oneMinuteInMillis);
+
+      expect(getPublishedMetrics()).toEqual([
+        [
+          {
+            resource: {
+              labels: {
+                project_id: 'dummy-project'
+              },
+              type: 'global'
+            },
+            name: 'job_delay',
+            labels: { programId: 'A' },
+            value: { doubleValue: 42 },
+            startTime: now.getTime() + oneMinuteInMillis,
+            endTime: now.getTime() + oneMinuteInMillis,
+            metricKind: 'GAUGE',
+            valueType: 'doubleValue'
+          }
+        ]
+      ]);
+    });
+
+    it('should keep only the last value within a flush period', async () => {
+      stubCreateTimeSeries();
+
+      gcpMetricCollector.gauge('job_delay', { programId: 'A' }, 5);
+      gcpMetricCollector.gauge('job_delay', { programId: 'A' }, 9);
+      gcpMetricCollector.gauge('job_delay', { programId: 'A' }, 3);
+
+      jest.advanceTimersByTime(60 * 1000 + 1);
+      await flushPromises();
+
+      expect(getPublishedMetrics()).toMatchObject([
+        [{ name: 'job_delay', labels: { programId: 'A' }, value: { doubleValue: 3 } }]
+      ]);
+    });
+
+    it('should send a separate metric for each label combo', async () => {
+      stubCreateTimeSeries();
+
+      gcpMetricCollector.gauge('job_delay', { programId: 'A' }, 1);
+      gcpMetricCollector.gauge('job_delay', { programId: 'B' }, 2);
+
+      jest.advanceTimersByTime(60 * 1000 + 1);
+      await flushPromises();
+
+      expect(getPublishedMetrics()).toMatchObject([
+        [
+          { name: 'job_delay', labels: { programId: 'A' }, value: { doubleValue: 1 } },
+          { name: 'job_delay', labels: { programId: 'B' }, value: { doubleValue: 2 } }
+        ]
+      ]);
+    });
+
+    it('should send metric for given gcp project id', () => {
+      stubCreateTimeSeries();
+
+      gcpMetricCollector
+        .createGcpMetricsCollector('test-project')
+        .gauge('job_delay', { programId: 'A' }, 42);
+
+      jest.advanceTimersByTime(60 * 1000 + 1);
+
+      expect(getPublishedMetrics()).toEqual([
+        [
+          expect.objectContaining({
+            resource: {
+              labels: {
+                project_id: 'test-project'
+              },
+              type: 'global'
+            }
+          })
+        ]
+      ]);
+    });
+
+    it('should go silent and not republish a stale value when no new value is set', async () => {
+      stubCreateTimeSeries();
+
+      gcpMetricCollector.gauge('job_delay', { programId: 'A' }, 42);
+
+      jest.advanceTimersByTime(60 * 1000 + 1);
+      await flushPromises();
+
+      jest.advanceTimersByTime(60 * 1000 + 1);
+      await flushPromises();
+
+      expect(getPublishedMetrics()).toMatchObject([
+        [{ name: 'job_delay', labels: { programId: 'A' }, value: { doubleValue: 42 } }]
+      ]);
+    });
+
+    it('should publish a fresh value after a silent period', async () => {
+      stubCreateTimeSeries();
+
+      gcpMetricCollector.gauge('job_delay', { programId: 'A' }, 42);
+
+      jest.advanceTimersByTime(60 * 1000 + 1);
+      await flushPromises();
+
+      jest.advanceTimersByTime(60 * 1000 + 1);
+      await flushPromises();
+
+      gcpMetricCollector.gauge('job_delay', { programId: 'A' }, 9);
+
+      jest.advanceTimersByTime(60 * 1000 + 1);
+      await flushPromises();
+
+      expect(getPublishedMetrics()).toMatchObject([
+        [{ value: { doubleValue: 42 } }],
+        [{ value: { doubleValue: 9 } }]
+      ]);
+    });
+
+    it('should not publish metrics if metric logger is not enabled', async () => {
+      process.env.METRIC_LOGGER_ENABLED = 'false';
+      stubCreateTimeSeries();
+
+      gcpMetricCollector.gauge('job_delay', { programId: 'A' }, 42);
+      jest.advanceTimersByTime(60 * 1000 + 1);
+
+      expect(getPublishedMetrics()).toEqual([]);
+    });
+
+    it('should validate labels parameter whether it is an object', async () => {
+      process.env.METRIC_LOGGER_ENABLED = 'false';
+
+      expect(() => {
+        gcpMetricCollector.gauge('irrelevant', new Error('not a plain object'), 42);
+      }).toThrow(new Error('labels is not a plain object'));
+    });
+
+    it('should validate value parameter whether it is a number', async () => {
+      process.env.METRIC_LOGGER_ENABLED = 'false';
+
+      expect(() => {
+        gcpMetricCollector.gauge('irrelevant', {}, '42');
+      }).toThrow(new Error('42 is not a number'));
+    });
+  });
+
   describe('start', () => {
     it('should return a measurement object with the given tag, params and start time', () => {
       const fakeCurrentTimestamp = 2323434543;
@@ -383,4 +537,50 @@ describe('gcpMetricCollector', () => {
       ]);
     });
   });
+
+  describe('shutdown', () => {
+    it('should flush pending metrics immediately', async () => {
+      stubCreateTimeSeries();
+
+      gcpMetricCollector.gauge('job_delay', { programId: 'A' }, 42);
+
+      expect(getPublishedMetrics()).toEqual([]);
+
+      await gcpMetricCollector.shutdown();
+
+      expect(getPublishedMetrics()).toMatchObject([
+        [{ name: 'job_delay', labels: { programId: 'A' }, value: { doubleValue: 42 } }]
+      ]);
+    });
+
+    it('should not schedule another flush after shutdown', async () => {
+      stubCreateTimeSeries();
+      const collector = gcpMetricCollector.createGcpMetricsCollector('test-project');
+      const publishPendingSpy = jest.spyOn(collector, 'publishPending');
+
+      collector.gauge('job_delay', { programId: 'A' }, 42);
+      await collector.shutdown();
+
+      jest.advanceTimersByTime(60 * 1000 + 1);
+      await flushPromises();
+
+      expect(publishPendingSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('should resume flushing on the next metric after shutdown', async () => {
+      stubCreateTimeSeries();
+
+      gcpMetricCollector.gauge('job_delay', { programId: 'A' }, 42);
+      await gcpMetricCollector.shutdown();
+
+      gcpMetricCollector.gauge('job_delay', { programId: 'A' }, 9);
+      jest.advanceTimersByTime(60 * 1000 + 1);
+      await flushPromises();
+
+      expect(getPublishedMetrics()).toMatchObject([
+        [{ value: { doubleValue: 42 } }],
+        [{ value: { doubleValue: 9 } }]
+      ]);
+    });
+  });
 });

package/src/gcp-time-series-builder/gcp-time-series-builder.js

@@ -7,30 +7,35 @@ class GcpTimeSeriesBuilder {
     this.projectId = projectId ?? process.env.MONITORING_PROJECT_ID;
   }
   buildTimeSeries(metrics) {
-    return Object.values(metrics).map(metric => {
-      const state = metric.aggregator.getState();
-      return {
-        metric: {
-          type: `custom.googleapis.com/${metric.name}`,
-          labels: { ...metric.labels, hostname: process.env.HOSTNAME }
-        },
-        resource: {
-          type: 'global',
-          labels: { project_id: this.projectId }
-        },
-        points: [
-          {
-            interval: {
-              startTime: { seconds: state.startTime / 1000 },
-              endTime: { seconds: state.endTime / 1000 }
-            },
-            value: state.value
-          }
-        ],
-        metricKind: state.metricKind,
-        valueType: state.valueType
-      };
-    });
+    return Object.values(metrics)
+      .filter(
+        metric =>
+          typeof metric.aggregator.hasValue !== 'function' || metric.aggregator.hasValue()
+      )
+      .map(metric => {
+        const state = metric.aggregator.getState();
+        return {
+          metric: {
+            type: `custom.googleapis.com/${metric.name}`,
+            labels: { ...metric.labels, hostname: process.env.HOSTNAME }
+          },
+          resource: {
+            type: 'global',
+            labels: { project_id: this.projectId }
+          },
+          points: [
+            {
+              interval: {
+                startTime: { seconds: state.startTime / 1000 },
+                endTime: { seconds: state.endTime / 1000 }
+              },
+              value: state.value
+            }
+          ],
+          metricKind: state.metricKind,
+          valueType: state.valueType
+        };
+      });
   }
 }
 

package/src/index.d.ts

@@ -4,6 +4,12 @@ export function count(
   value?: number
 ): void;
 
+export function gauge(
+  metricName: string,
+  labels: MetricLabels,
+  value: number
+): void;
+
 export function measure(
   metricName: string,
   labels?: MetricLabels,
@@ -19,6 +25,8 @@ export function stop(
   measurement: MetricTimerObject
 ): void;
 
+export function shutdown(): Promise<void>;
+
 export type MetricLabels = {
   [key: string]: string | number | null | undefined
 };

package/src/index.js

@@ -4,8 +4,10 @@ const gcpMetricCollector = require('./gcp-metric-collector/gcp-metric-collector'
 
 module.exports = {
   count: gcpMetricCollector.count,
+  gauge: gcpMetricCollector.gauge,
   measure: gcpMetricCollector.measure,
   start: gcpMetricCollector.start,
   stop: gcpMetricCollector.stop,
+  shutdown: gcpMetricCollector.shutdown,
   createGcpMetricsCollector: gcpMetricCollector.createGcpMetricsCollector
 };

package/src/metric-types/gauge/gauge.js

@@ -0,0 +1,20 @@
+'use strict';
+
+exports.createGauge = () => {
+  let value = null;
+
+  return {
+    getState: () => ({
+      startTime: Date.now(),
+      endTime: Date.now(),
+      metricKind: 'GAUGE',
+      valueType: 'doubleValue',
+      value: { doubleValue: value }
+    }),
+    add: newValue => (value = newValue),
+    advanceTimer: () => {
+      value = null;
+    },
+    hasValue: () => value !== null
+  };
+};

package/src/metric-types/gauge/gauge.spec.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const { createGauge } = require('./gauge');
+
+describe('gauge', () => {
+  it('should return an empty gauge if no value was set', () => {
+    const now = new Date();
+    jest.useFakeTimers().setSystemTime(now);
+    const gauge = createGauge();
+
+    expect(gauge.getState()).toEqual({
+      startTime: now.getTime(),
+      endTime: now.getTime(),
+      metricKind: 'GAUGE',
+      valueType: 'doubleValue',
+      value: { doubleValue: null }
+    });
+    expect(gauge.hasValue()).toBe(false);
+  });
+
+  it('should return the same startTime and endTime as it is an instantaneous point', () => {
+    jest.useFakeTimers().setSystemTime(new Date(8880));
+    const gauge = createGauge();
+
+    expect(gauge.getState().startTime).toBe(gauge.getState().endTime);
+  });
+
+  it('should store the value when it is set', () => {
+    const gauge = createGauge();
+
+    gauge.add(42);
+
+    expect(gauge.getState()).toMatchObject({ value: { doubleValue: 42 } });
+    expect(gauge.hasValue()).toBe(true);
+  });
+
+  it('should keep only the last value when multiple values are set', () => {
+    const gauge = createGauge();
+
+    gauge.add(5);
+    gauge.add(9);
+    gauge.add(3);
+
+    expect(gauge.getState()).toMatchObject({ value: { doubleValue: 3 } });
+  });
+
+  it('should support fractional values', () => {
+    const gauge = createGauge();
+
+    gauge.add(1.5);
+
+    expect(gauge.getState()).toMatchObject({ value: { doubleValue: 1.5 } });
+  });
+
+  it('should reset the value on advanceTimer call', () => {
+    const gauge = createGauge();
+
+    gauge.add(7);
+    gauge.advanceTimer();
+
+    expect(gauge.getState()).toMatchObject({ value: { doubleValue: null } });
+    expect(gauge.hasValue()).toBe(false);
+  });
+
+  it('should store a new value after advanceTimer call', () => {
+    const gauge = createGauge();
+
+    gauge.add(7);
+    gauge.advanceTimer();
+    gauge.add(2);
+
+    expect(gauge.getState()).toMatchObject({ value: { doubleValue: 2 } });
+    expect(gauge.hasValue()).toBe(true);
+  });
+
+  it('should return current time as endTime', () => {
+    jest.useFakeTimers().setSystemTime(new Date(880));
+    const gauge = createGauge();
+
+    jest.advanceTimersByTime(20);
+
+    expect(gauge.getState()).toMatchObject({ endTime: 900 });
+  });
+});