feat: startTimer with exemplar

CHANGELOG.md

@@ -18,6 +18,7 @@ project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 
 - Allow Pushgateway to now require job names for compatibility with Gravel Gateway.
+- Allow `histogram.startTime()` to be used with exemplars.
 
 ## [15.0.0] - 2023-10-09
 

index.d.ts

@@ -498,6 +498,19 @@ export class Histogram<T extends string = string> {
 	 */
 	startTimer(labels?: LabelValues<T>): (labels?: LabelValues<T>) => number;
 
+	/**
+	 * Start a timer with exemplar. Calling the returned function will observe the duration in
+	 * seconds in the histogram.
+	 * @param labels Object with label keys and values
+	 * @param exemplarLabels Object with label keys and values for exemplars
+	 * @return Function to invoke when timer should be stopped. The value it
+	 * returns is the timed duration.
+	 */
+	startTimer(
+		labels?: LabelValues<T>,
+		exemplarLabels?: LabelValues<T>,
+	): (labels?: LabelValues<T>, exemplarLabels?: LabelValues<T>) => number;
+
 	/**
 	 * Reset histogram values
 	 */

lib/histogram.js

@@ -24,8 +24,10 @@ class Histogram extends Metric {
 		this.type = 'histogram';
 		this.defaultLabels = {};
 		this.defaultExemplarLabelSet = {};
+		this.enableExemplars = false;
 
 		if (config.enableExemplars) {
+			this.enableExemplars = true;
 			this.observe = this.observeWithExemplar;
 		} else {
 			this.observe = this.observeWithoutExemplar;
@@ -143,6 +145,7 @@ class Histogram extends Metric {
 	/**
 	 * Start a timer that could be used to logging durations
 	 * @param {object} labels - Object with labels where key is the label key and value is label value. Can only be one level deep
+	 * @param {object} exemplarLabels - Object with labels for exemplar where key is the label key and value is label value. Can only be one level deep
 	 * @returns {function} - Function to invoke when you want to stop the timer and observe the duration in seconds
 	 * @example
 	 * var end = histogram.startTimer();
@@ -151,8 +154,10 @@ class Histogram extends Metric {
 	 * 	console.log('Duration', duration);
 	 * });
 	 */
-	startTimer(labels) {
-		return startTimer.call(this, labels)();
+	startTimer(labels, exemplarLabels) {
+		return this.enableExemplars
+			? startTimerWithExemplar.call(this, labels, exemplarLabels)()
+			: startTimer.call(this, labels)();
 	}
 
 	labels(...args) {
@@ -183,6 +188,26 @@ function startTimer(startLabels) {
 	};
 }
 
+function startTimerWithExemplar(startLabels, startExemplarLabels) {
+	return () => {
+		const start = process.hrtime();
+		return (endLabels, endExemplarLabels) => {
+			const delta = process.hrtime(start);
+			const value = delta[0] + delta[1] / 1e9;
+			this.observe({
+				labels: Object.assign({}, startLabels, endLabels),
+				value,
+				exemplarLabels: Object.assign(
+					{},
+					startExemplarLabels,
+					endExemplarLabels,
+				),
+			});
+			return value;
+		};
+	};
+}
+
 function setValuePair(labels, value, metricName, exemplar, sharedLabels = {}) {
 	return {
 		labels,

test/exemplarsTest.js

@@ -122,6 +122,64 @@ describe('Exemplars', () => {
 				}).toThrowError('Label set size must be smaller than 128 UTF-8 chars');
 			});
 
+			it('should time request, with exemplar', async () => {
+				jest.useFakeTimers('modern');
+				jest.setSystemTime(0);
+				const histogramInstance = new Histogram({
+					name: 'histogram_start_timer_exemplar_test',
+					help: 'test',
+					labelNames: ['method', 'code'],
+					enableExemplars: true,
+				});
+				const end = histogramInstance.startTimer({
+					method: 'get',
+					code: '200',
+				});
+
+				jest.advanceTimersByTime(500);
+				end();
+
+				const valuePair = getValueByLabel(
+					0.5,
+					(await histogramInstance.get()).values,
+				);
+				expect(valuePair.value).toEqual(1);
+				jest.useRealTimers();
+			});
+
+			it('should allow exemplar labels before and after timers', async () => {
+				jest.useFakeTimers('modern');
+				jest.setSystemTime(0);
+				const histogramInstance = new Histogram({
+					name: 'histogram_start_timer_exemplar_label_test',
+					help: 'test',
+					labelNames: ['method', 'code'],
+					enableExemplars: true,
+				});
+				const end = histogramInstance.startTimer(
+					{ method: 'get' },
+					{ traceId: 'trace_id_test_1' },
+				);
+
+				jest.advanceTimersByTime(500);
+				end({ code: '200' }, { spanId: 'span_id_test_1' });
+
+				const vals = (await histogramInstance.get()).values;
+				expect(getValuesByLabel(0.5, vals)[0].value).toEqual(1);
+				expect(
+					getValuesByLabel(0.5, vals)[0].exemplar.labelSet.traceId,
+				).toEqual('trace_id_test_1');
+				jest.useRealTimers();
+			});
+
+			function getValueByLabel(label, values, key) {
+				return values.reduce((acc, val) => {
+					if (val.labels && val.labels[key || 'le'] === label) {
+						acc = val;
+					}
+					return acc;
+				}, {});
+			}
 			function getValuesByLabel(label, values, key) {
 				return values.reduce((acc, val) => {
 					if (val.labels && val.labels[key || 'le'] === label) {