prom-client - npm Package Compare versions

Comparing version 10.0.4 to 10.1.0

CHANGELOG.md

@@ -8,5 +8,9 @@ # Changelog
 ### Breaking
+### Changed
 ### Added
-### Changed
 
+## [10.1.0] - 2017-09-04
+### Added
+- Support aggregating metrics across workers in a Node.js cluster.
+
 ## [10.0.4] - 2017-08-22
@@ -13,0 +17,0 @@ ### Changed

index.d.ts

@@ -76,2 +76,35 @@ // Type definitions for prom-client
 
+export class AggregatorRegistry extends Registry {
+	/**
+	 * Gets aggregated metrics for all workers. The optional callback and
+	 * returned Promise resolve with the same value; either may be used.
+	 * @param {Function?} callback (err, metrics) => any
+	 * @return {Promise<string>} Promise that resolves with the aggregated
+	 *   metrics.
+	 */
+	clusterMetrics(
+		cb?: (err: Error | null, metrics?: string) => any
+	): Promise<string>;
+
+	/**
+	 * Creates a new Registry instance from an array of metrics that were
+	 * created by `registry.getMetricsAsJSON()`. Metrics are aggregated using
+	 * the method specified by their `aggregator` property, or by summation if
+	 * `aggregator` is undefined.
+	 * @param {Array} metricsArr Array of metrics, each of which created by
+	 *   `registry.getMetricsAsJSON()`.
+	 * @return {Registry} aggregated registry.
+	 */
+	static aggregate(metricsArr: Array<Object>): Registry;
+
+	/**
+	 * Sets the registry or registries to be aggregated. Call from workers to
+	 * use a registry/registries other than the default global registry.
+	 * @param {Array<Registry>|Registry} regs Registry or registries to be
+	 *   aggregated.
+	 * @return {void}
+	 */
+	static setRegistries(regs: Array<Registry> | Registry): void;
+}
+
 /**
@@ -82,2 +115,7 @@ * General metric type
 
+/**
+ * Aggregation methods, used for aggregating metrics in a Node.js cluster.
+ */
+export type Aggregator = 'omit' | 'sum' | 'first' | 'min' | 'max' | 'average';
+
 export enum MetricType {
@@ -94,2 +132,3 @@ Counter,
 	type: MetricType;
+	aggregator: Aggregator;
 }
@@ -106,2 +145,3 @@
 	registers?: Registry[];
+	aggregator?: Aggregator;
 }
@@ -165,2 +205,3 @@
 	registers?: Registry[];
+	aggregator?: Aggregator;
 }
@@ -293,2 +334,3 @@
 	registers?: Registry[];
+	aggregator?: Aggregator;
 }
@@ -387,2 +429,3 @@
 	registers?: Registry[];
+	aggregator?: Aggregator;
 }
@@ -389,0 +432,0 @@

index.js

@@ -22,1 +22,4 @@ /**
 exports.collectDefaultMetrics = require('./lib/defaultMetrics');
+
+exports.aggregators = require('./lib/metricAggregators').aggregators;
+exports.AggregatorRegistry = require('./lib/cluster');

lib/counter.js

@@ -76,2 +76,3 @@ /**
 		this.help = config.help;
+		this.aggregator = config.aggregator || 'sum';
 
@@ -104,3 +105,4 @@ config.registers.forEach(registryInstance =>
 			type,
-			values: getProperties(this.hashMap)
+			values: getProperties(this.hashMap),
+			aggregator: this.aggregator
 		};
@@ -107,0 +109,0 @@ }

lib/gauge.js

@@ -72,2 +72,3 @@ /**
 		this.help = config.help;
+		this.aggregator = config.aggregator || 'sum';
 
@@ -94,8 +95,8 @@ config.registers.forEach(registryInstance =>
 	/**
- * Increment a gauge value
- * @param {object} labels - Object with labels where key is the label key and value is label value. Can only be one level deep
- * @param {Number} value - Value to increment - if omitted, increment with 1
- * @param {(Number|Date)} timestamp - Timestamp to set the gauge to
- * @returns {void}
- */
+	 * Increment a gauge value
+	 * @param {object} labels - Object with labels where key is the label key and value is label value. Can only be one level deep
+	 * @param {Number} value - Value to increment - if omitted, increment with 1
+	 * @param {(Number|Date)} timestamp - Timestamp to set the gauge to
+	 * @returns {void}
+	 */
 	inc(labels, value, timestamp) {
@@ -106,9 +107,8 @@ inc.call(this, labels)(value, timestamp);
 	/**
-
- * Decrement a gauge value
- * @param {object} labels - Object with labels where key is the label key and value is label value. Can only be one level deep
- * @param {Number} value - Value to decrement - if omitted, decrement with 1
- * @param {(Number|Date)} timestamp - Timestamp to set the gauge to
- * @returns {void}
- */
+	 * Decrement a gauge value
+	 * @param {object} labels - Object with labels where key is the label key and value is label value. Can only be one level deep
+	 * @param {Number} value - Value to decrement - if omitted, decrement with 1
+	 * @param {(Number|Date)} timestamp - Timestamp to set the gauge to
+	 * @returns {void}
+	 */
 	dec(labels, value, timestamp) {
@@ -146,3 +146,4 @@ dec.call(this, labels)(value, timestamp);
 			type,
-			values: getProperties(this.hashMap)
+			values: getProperties(this.hashMap),
+			aggregator: this.aggregator
 		};
@@ -149,0 +150,0 @@ }

lib/histogram.js

@@ -67,2 +67,3 @@ /**
 		this.help = config.help;
+		this.aggregator = config.aggregator || 'sum';
 
@@ -117,3 +118,4 @@ this.upperBounds = config.buckets;
 			type,
-			values
+			values,
+			aggregator: this.aggregator
 		};
@@ -120,0 +122,0 @@ }

lib/metrics/eventLoopLag.js

@@ -19,3 +19,4 @@ 'use strict';
 		help: 'Lag of event loop in seconds.',
-		registers: registry ? [registry] : undefined
+		registers: registry ? [registry] : undefined,
+		aggregator: 'average'
 	});
@@ -22,0 +23,0 @@

lib/metrics/processStartTime.js

@@ -12,3 +12,4 @@ 'use strict';
 		help: 'Start time of the process since unix epoch in seconds.',
-		registers: registry ? [registry] : undefined
+		registers: registry ? [registry] : undefined,
+		aggregator: 'omit'
 	});
@@ -15,0 +16,0 @@ let isSet = false;

lib/metrics/version.js

@@ -14,3 +14,4 @@ 'use strict';
 		labelNames: ['version', 'major', 'minor', 'patch'],
-		registers: registry ? [registry] : undefined
+		registers: registry ? [registry] : undefined,
+		aggregator: 'first'
 	});
@@ -17,0 +18,0 @@ let isSet = false;

lib/summary.js

@@ -68,2 +68,3 @@ /**
 		this.help = config.help;
+		this.aggregator = config.aggregator || 'sum';
 
@@ -115,3 +116,4 @@ this.percentiles = config.percentiles;
 			type,
-			values
+			values,
+			aggregator: this.aggregator
 		};
@@ -118,0 +120,0 @@ }

lib/util.js

@@ -92,1 +92,19 @@ 'use strict';
 };
+
+class Grouper extends Map {
+	/**
+	 * Adds the `value` to the `key`'s array of values.
+	 * @param {*} key Key to set.
+	 * @param {*} value Value to add to `key`'s array.
+	 * @returns {undefined} undefined.
+	 */
+	add(key, value) {
+		if (this.has(key)) {
+			this.get(key).push(value);
+		} else {
+			this.set(key, [value]);
+		}
+	}
+}
+
+exports.Grouper = Grouper;

package.json

 {
   "name": "prom-client",
-  "version": "10.0.4",
+  "version": "10.1.0",
   "description": "Client for prometheus",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

@@ -7,4 +7,14 @@ # Prometheus client for node.js [![Build Status](https://travis-ci.org/siimon/prom-client.svg?branch=master)](https://travis-ci.org/siimon/prom-client) [![Build status](https://ci.appveyor.com/api/projects/status/k2e0gwonkcee3lp9/branch/master?svg=true)](https://ci.appveyor.com/project/siimon/prom-client/branch/master)
 
-See example folder for a sample usage. The library does not bundle any web framework, to expose the metrics just return the metrics() function in the registry.
+See example folder for a sample usage. The library does not bundle any web framework, to expose the metrics just return the `metrics()` function in the registry.
 
+#### Usage with Node.js's `cluster` module
+
+Node.js's `cluster` module spawns multiple processes and hands off socket connections to those workers. Returning metrics from a worker's local registry will only reveal that individual worker's metrics, which is generally undesirable. To solve this, you can aggregate all of the workers' metrics in the master process. See `example/cluster.js` for an example.
+
+Default metrics use sensible aggregation methods. Custom metrics are summed across workers by default. To use a different aggregation method, set the `aggregator` property in the metric config to one of 'sum', 'first', 'min', 'max', 'average' or 'omit'. (See `lib/metrics/version.js` for an example.)
+
+If you need to expose metrics about an individual worker, you can include a value that is unique to the worker (such as the worker ID or process ID) in a label. (See `example/server.js` for an example using `worker_${cluster.worker.id}` as a label value.)
+
+Metrics are aggregated from the global registry by default. To use a different registry, call `client.AggregatorRegistry.setRegistries(registryOrArrayOfRegistries)` from the worker processes.
+
 ### API
@@ -252,3 +262,3 @@
 
-Registry has a merge function that enables you to expose multiple registries on the same endpoint. If the same metric name exists in both registries, an error will be thrown.
+Registry has a `merge` function that enables you to expose multiple registries on the same endpoint. If the same metric name exists in both registries, an error will be thrown.
 
@@ -266,2 +276,11 @@ ```js
 
+If you want to use multiple or non-default registries with the Node.js `cluster` module, you will need to set the registry/registries to aggregate from:
+
+```js
+const AggregatorRegistry = client.AggregatorRegistry;
+AggregatorRegistry.setRegistries(registry);
+// or for multiple registries:
+AggregatorRegistry.setRegistries([registry1, registry2]);
+```
+
 #### Register
@@ -286,2 +305,18 @@
 
+##### Cluster metrics
+
+You can get aggregated metrics for all workers in a node.js cluster with `register.clusterMetrics()`. This method both returns a promise and accepts a callback, both of which resolve with a metrics string suitable for Prometheus to consume.
+
+```js
+register.clusterMetrics()
+	.then(metrics => { /* ... */ })
+	.catch(err => { /* ... */ });
+
+// - or -
+
+register.clusterMetrics((err, metrics) => {
+	// ...
+});
+```
+
 #### Pushgateway
@@ -288,0 +323,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

99115

increased by12.91%

Number of package files

31

increased by6.9%

Lines of code

2460

increased by13.68%

Number of lines in readme file

364

increased by10.64%

No dependency changes