add methods to gauge-track the in-flight count of functions and promises

README.md

@@ -89,6 +89,27 @@ Used to record a value which can vary over time, like temperature.
 metrics.gauge('greenhouse_temperature', temp [, labelObject ]);
 ```
 
+#### Using a gauge to track the "in-flight count" for functions and promises
+
+Using the `.run()` and `.resolve()` methods, we can keep an instantaneous gauge of how many such functions/promises
+are currently running / waiting to resolve/reject:
+
+```
+const delayMS = 1000;
+
+const func = async () => {
+    await new Promise(resolve => setTimeout(resolve, delayMS));
+};
+
+const promise = new Promise(resolve => setTimeout(resolve, delayMS));
+
+// this gauge will have a value incremented by 1 when func begins, and decremened by 1 when func ends
+metrics.run('func_in_flight', func);
+
+// this gauge will have a value incremented by 1 when first called, and decremened by 1 when the promise resolves/rejects
+metrics.resolve('promise_in_flight', promise);
+```
+
 #### Counter
 
 Used to record increases to a monotonic counter, like requests served.

src/metrics-gatherer.ts

@@ -112,6 +112,21 @@ export class MetricsGatherer {
 		}
 	}
 
+	// increment/decrement a gauge during the runtime of a function
+	public async run(name: string, func: () => any, labels: LabelSet = {}) {
+		this.inc(name, 1, labels);
+		await func();
+		this.inc(name, -1, labels);
+	}
+
+	// increment/decrement a gauge during the runtime of a promise (wait for it to resolve)
+	public resolve(name: string, promise: Promise<any>, labels: LabelSet = {}) {
+		this.inc(name, 1, labels);
+		promise.finally(() => {
+			this.inc(name, -1, labels);
+		});
+	}
+
 	// decrement a gauge
 	public dec(name: string, val: number = 1, labels: LabelSet = {}) {
 		try {

test/index.spec.ts

@@ -44,6 +44,34 @@ describe('Gauge', () => {
 		output = metrics.output();
 		expect(/undescribed_gauge 1/.test(output)).to.be.true;
 	});
+
+	it('should track runtime of functions properly', () => {
+		let output: string;
+
+		const func = async () => {
+			await new Promise(resolve => setTimeout(resolve, 100));
+		};
+		metrics.run('func_running_gauge', func);
+		output = metrics.output();
+		expect(/func_running_gauge 1/.test(output)).to.be.true;
+		setTimeout(() => {
+			output = metrics.output();
+			expect(/func_running_gauge 0/.test(output)).to.be.true;
+		}, 200);
+	});
+
+	it('should track runtime of promises properly', () => {
+		let output: string;
+
+		const promise = new Promise(resolve => setTimeout(resolve, 100));
+		metrics.resolve('promise_running_gauge', promise);
+		output = metrics.output();
+		expect(/promise_running_gauge 1/.test(output)).to.be.true;
+		setTimeout(() => {
+			output = metrics.output();
+			expect(/promise_running_gauge 0/.test(output)).to.be.true;
+		}, 200);
+	});
 });
 
 describe('Counter', () => {