@prairielearn/opentelemetry 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @prairielearn/opentelemetry
 
+## 1.8.0
+
+### Minor Changes
+
+- 5ae096ba7: Add `createObservableValueGauges()` function
+
 ## 1.7.0
 
 ### Minor Changes

package/README.md

@@ -102,3 +102,20 @@ await instrumentedWithMetrics(meter, 'operation.name', async () => {
   }
 });
 ```
+
+To capture statistics about a constantly changing value (for instance, the size of a database connection pool), you can use `createObservableValueGauges`. This will "observe" your chosen value on a regular interval and collect the min/max/average of that value for each metrics collection interval.
+
+```ts
+import { metrics, createObservableValueGauges } from '@prairielearn/opentelemetry';
+
+const meter = metrics.getMeter('meter-name');
+createObservableValueGauges(
+  meter,
+  'db.pool.size',
+  {
+    // The interval that your value will be observed, in milliseconds.
+    interval: 1000,
+  },
+  () => pool.size
+);
+```

package/dist/index.d.ts

@@ -2,4 +2,4 @@ export { trace, metrics, context, SpanStatusCode, ValueType } from '@opentelemet
 export { suppressTracing } from '@opentelemetry/core';
 export { init, shutdown } from './init';
 export { instrumented } from './tracing';
-export { instrumentedWithMetrics, getCounter, getUpDownCounter, getHistogram, getObservableCounter, getObservableUpDownCounter, getObservableGauge, } from './metrics';
+export { instrumentedWithMetrics, getCounter, getUpDownCounter, getHistogram, getObservableCounter, getObservableUpDownCounter, getObservableGauge, createObservableValueGauges, createObservableValueGaugesOptions, } from './metrics';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getObservableGauge = exports.getObservableUpDownCounter = exports.getObservableCounter = exports.getHistogram = exports.getUpDownCounter = exports.getCounter = exports.instrumentedWithMetrics = exports.instrumented = exports.shutdown = exports.init = exports.suppressTracing = exports.ValueType = exports.SpanStatusCode = exports.context = exports.metrics = exports.trace = void 0;
+exports.createObservableValueGauges = exports.getObservableGauge = exports.getObservableUpDownCounter = exports.getObservableCounter = exports.getHistogram = exports.getUpDownCounter = exports.getCounter = exports.instrumentedWithMetrics = exports.instrumented = exports.shutdown = exports.init = exports.suppressTracing = exports.ValueType = exports.SpanStatusCode = exports.context = exports.metrics = exports.trace = void 0;
 var api_1 = require("@opentelemetry/api");
 Object.defineProperty(exports, "trace", { enumerable: true, get: function () { return api_1.trace; } });
 Object.defineProperty(exports, "metrics", { enumerable: true, get: function () { return api_1.metrics; } });
@@ -22,4 +22,5 @@ Object.defineProperty(exports, "getHistogram", { enumerable: true, get: function
 Object.defineProperty(exports, "getObservableCounter", { enumerable: true, get: function () { return metrics_1.getObservableCounter; } });
 Object.defineProperty(exports, "getObservableUpDownCounter", { enumerable: true, get: function () { return metrics_1.getObservableUpDownCounter; } });
 Object.defineProperty(exports, "getObservableGauge", { enumerable: true, get: function () { return metrics_1.getObservableGauge; } });
+Object.defineProperty(exports, "createObservableValueGauges", { enumerable: true, get: function () { return metrics_1.createObservableValueGauges; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,0CAAwF;AAA/E,4FAAA,KAAK,OAAA;AAAE,8FAAA,OAAO,OAAA;AAAE,8FAAA,OAAO,OAAA;AAAE,qGAAA,cAAc,OAAA;AAAE,gGAAA,SAAS,OAAA;AAC3D,4CAAsD;AAA7C,uGAAA,eAAe,OAAA;AAExB,+BAAwC;AAA/B,4FAAA,IAAI,OAAA;AAAE,gGAAA,QAAQ,OAAA;AACvB,qCAAyC;AAAhC,uGAAA,YAAY,OAAA;AACrB,qCAQmB;AAPjB,kHAAA,uBAAuB,OAAA;AACvB,qGAAA,UAAU,OAAA;AACV,2GAAA,gBAAgB,OAAA;AAChB,uGAAA,YAAY,OAAA;AACZ,+GAAA,oBAAoB,OAAA;AACpB,qHAAA,0BAA0B,OAAA;AAC1B,6GAAA,kBAAkB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,0CAAwF;AAA/E,4FAAA,KAAK,OAAA;AAAE,8FAAA,OAAO,OAAA;AAAE,8FAAA,OAAO,OAAA;AAAE,qGAAA,cAAc,OAAA;AAAE,gGAAA,SAAS,OAAA;AAC3D,4CAAsD;AAA7C,uGAAA,eAAe,OAAA;AAExB,+BAAwC;AAA/B,4FAAA,IAAI,OAAA;AAAE,gGAAA,QAAQ,OAAA;AACvB,qCAAyC;AAAhC,uGAAA,YAAY,OAAA;AACrB,qCAUmB;AATjB,kHAAA,uBAAuB,OAAA;AACvB,qGAAA,UAAU,OAAA;AACV,2GAAA,gBAAgB,OAAA;AAChB,uGAAA,YAAY,OAAA;AACZ,+GAAA,oBAAoB,OAAA;AACpB,qHAAA,0BAA0B,OAAA;AAC1B,6GAAA,kBAAkB,OAAA;AAClB,sHAAA,2BAA2B,OAAA"}

package/dist/metrics.d.ts

@@ -6,3 +6,23 @@ export declare function getObservableCounter(meter: Meter, name: string, options
 export declare function getObservableUpDownCounter(meter: Meter, name: string, options?: MetricOptions): ObservableUpDownCounter<import("@opentelemetry/api").Attributes>;
 export declare function getObservableGauge(meter: Meter, name: string, options?: MetricOptions): ObservableGauge<import("@opentelemetry/api").Attributes>;
 export declare function instrumentedWithMetrics<T>(meter: Meter, name: string, fn: () => Promise<T> | T): Promise<T>;
+export interface createObservableValueGaugesOptions extends MetricOptions {
+    interval: number;
+}
+/**
+ * Creates a set of gauges that track the min, max, and average of a value over
+ * time. The value is observed on a regular interval.
+ *
+ * The provided {@link name} is used as the base name for the three gauges. The
+ * names of the individual gauges are:
+ *
+ * - `${name}.min`
+ * - `${name}.max`
+ * - `${name}.avg`
+ */
+export declare function createObservableValueGauges(meter: Meter, name: string, options: createObservableValueGaugesOptions, observe: () => number): Promise<{
+    minGauge: ObservableGauge<import("@opentelemetry/api").Attributes>;
+    maxGauge: ObservableGauge<import("@opentelemetry/api").Attributes>;
+    averageGauge: ObservableGauge<import("@opentelemetry/api").Attributes>;
+    stop: () => void;
+}>;

package/dist/metrics.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.instrumentedWithMetrics = exports.getObservableGauge = exports.getObservableUpDownCounter = exports.getObservableCounter = exports.getUpDownCounter = exports.getCounter = exports.getHistogram = void 0;
+exports.createObservableValueGauges = exports.instrumentedWithMetrics = exports.getObservableGauge = exports.getObservableUpDownCounter = exports.getObservableCounter = exports.getUpDownCounter = exports.getCounter = exports.getHistogram = void 0;
 const api_1 = require("@opentelemetry/api");
 const histogramCache = new WeakMap();
 const counterCache = new WeakMap();
@@ -64,4 +64,58 @@ async function instrumentedWithMetrics(meter, name, fn) {
     }
 }
 exports.instrumentedWithMetrics = instrumentedWithMetrics;
+/**
+ * Creates a set of gauges that track the min, max, and average of a value over
+ * time. The value is observed on a regular interval.
+ *
+ * The provided {@link name} is used as the base name for the three gauges. The
+ * names of the individual gauges are:
+ *
+ * - `${name}.min`
+ * - `${name}.max`
+ * - `${name}.avg`
+ */
+async function createObservableValueGauges(meter, name, options, observe) {
+    const { interval, ...metricOptions } = options;
+    let min = 0;
+    let max = 0;
+    let sum = 0;
+    let count = 0;
+    // Observe the value on a regular interval. Black-hole any errors.
+    const intervalId = setInterval(() => {
+        Promise.resolve(observe())
+            .then((value) => {
+            min = count == 0 ? value : Math.min(min, value);
+            max = Math.max(max, value);
+            sum += value;
+            count += 1;
+        })
+            .catch(() => { });
+    }, interval);
+    // Don't let this keep the process alive.
+    intervalId.unref();
+    const minGauge = getObservableGauge(meter, `${name}.min`, metricOptions);
+    const maxGauge = getObservableGauge(meter, `${name}.max`, metricOptions);
+    const averageGauge = getObservableGauge(meter, `${name}.avg`, {
+        ...metricOptions,
+        // Average is always a double, even if the observed value is an int.
+        valueType: api_1.ValueType.DOUBLE,
+    });
+    minGauge.addCallback((observableResult) => {
+        observableResult.observe(min);
+        min = 0;
+    });
+    maxGauge.addCallback((observableResult) => {
+        observableResult.observe(max);
+        max = 0;
+    });
+    averageGauge.addCallback((observableResult) => {
+        const avg = sum / count;
+        observableResult.observe(avg);
+        sum = 0;
+        count = 0;
+    });
+    return { minGauge, maxGauge, averageGauge, stop: () => clearInterval(intervalId) };
+}
+exports.createObservableValueGauges = createObservableValueGauges;
 //# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prairielearn/opentelemetry",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "main": "dist/index.js",
   "scripts": {
     "build": "tsc",
@@ -8,7 +8,7 @@
     "test": "mocha --no-config --require ts-node/register src/**/*.test.ts"
   },
   "dependencies": {
-    "@grpc/grpc-js": "^1.8.8",
+    "@grpc/grpc-js": "^1.8.11",
     "@opentelemetry/api": "^1.4.0",
     "@opentelemetry/core": "^1.9.1",
     "@opentelemetry/exporter-jaeger": "^1.9.1",
@@ -34,7 +34,7 @@
     "@prairielearn/tsconfig": "*",
     "@types/chai": "^4.3.4",
     "@types/mocha": "^10.0.1",
-    "@types/node": "^18.11.18",
+    "@types/node": "^18.14.2",
     "chai": "^4.3.7",
     "mocha": "^10.2.0",
     "ts-node": "^10.9.1",

package/src/index.ts

@@ -11,4 +11,6 @@ export {
   getObservableCounter,
   getObservableUpDownCounter,
   getObservableGauge,
+  createObservableValueGauges,
+  createObservableValueGaugesOptions,
 } from './metrics';

package/src/metrics.ts

@@ -91,3 +91,77 @@ export async function instrumentedWithMetrics<T>(
     histogram.record(performance.now() - start);
   }
 }
+
+export interface createObservableValueGaugesOptions extends MetricOptions {
+  interval: number;
+}
+
+/**
+ * Creates a set of gauges that track the min, max, and average of a value over
+ * time. The value is observed on a regular interval.
+ *
+ * The provided {@link name} is used as the base name for the three gauges. The
+ * names of the individual gauges are:
+ *
+ * - `${name}.min`
+ * - `${name}.max`
+ * - `${name}.avg`
+ */
+export async function createObservableValueGauges(
+  meter: Meter,
+  name: string,
+  options: createObservableValueGaugesOptions,
+  observe: () => number
+) {
+  const { interval, ...metricOptions } = options;
+
+  let min = 0;
+  let max = 0;
+  let sum = 0;
+  let count = 0;
+
+  // Observe the value on a regular interval. Black-hole any errors.
+  const intervalId = setInterval(() => {
+    Promise.resolve(observe())
+      .then((value) => {
+        min = count == 0 ? value : Math.min(min, value);
+        max = Math.max(max, value);
+        sum += value;
+        count += 1;
+      })
+      .catch(() => {});
+  }, interval);
+
+  // Don't let this keep the process alive.
+  intervalId.unref();
+
+  const minGauge = getObservableGauge(meter, `${name}.min`, metricOptions);
+  const maxGauge = getObservableGauge(meter, `${name}.max`, metricOptions);
+  const averageGauge = getObservableGauge(meter, `${name}.avg`, {
+    ...metricOptions,
+    // Average is always a double, even if the observed value is an int.
+    valueType: ValueType.DOUBLE,
+  });
+
+  minGauge.addCallback((observableResult) => {
+    observableResult.observe(min);
+
+    min = 0;
+  });
+
+  maxGauge.addCallback((observableResult) => {
+    observableResult.observe(max);
+
+    max = 0;
+  });
+
+  averageGauge.addCallback((observableResult) => {
+    const avg = sum / count;
+    observableResult.observe(avg);
+
+    sum = 0;
+    count = 0;
+  });
+
+  return { minGauge, maxGauge, averageGauge, stop: () => clearInterval(intervalId) };
+}