CHANGELOG.md

@@ -9,6 +9,27 @@ project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Breaking
 
+### Changed
+
+### Added
+
+## [13.1.0] - 2021-01-24
+
+### Changed
+
+- fix: push client attempting to write Promise (fixes [#390](https://github.com/siimon/prom-client/issues/390))
+- types: improve type checking of labels
+- fix: Summary#observe should throw when adding additional labels to labelset (fixes [#262](https://github.com/siimon/prom-client/issues/262))
+
+### Added
+
+- feat: added the ability to pass labels as an object to `labels()` and `remove()`
+- Added: More examples with commented output
+
+## [13.0.0] - 2020-12-16
+
+### Breaking
+
 - changed: The following functions are now async (return a promise):
   `registry.metrics()`
   `registry.getMetricsAsJSON()`

README.md

@@ -307,6 +307,8 @@ const gauge = new client.Gauge({
 // 1st version: Set value to 100 with "method" set to "GET" and "statusCode" to "200"
 gauge.set({ method: 'GET', statusCode: '200' }, 100);
 // 2nd version: Same effect as above
+gauge.labels({ method: 'GET', statusCode: '200' }).set(100);
+// 3nd version: And again the same effect as above
 gauge.labels('GET', '200').set(100);
 ```
 
@@ -324,6 +326,28 @@ xhrRequest(function (err, res) {
 });
 ```
 
+#### Strongly typed Labels
+
+Typescript can also enforce label names using `as const`
+
+```typescript
+import * as client from 'prom-client';
+
+const gauge = new client.Counter({
+  name: 'metric_name',
+  help: 'metric_help',
+  // add `as const` here to enforce label names
+  labelNames: ['method'] as const,
+});
+
+// Ok
+gauge.inc({ method: 1 });
+
+// this is an error since `'methods'` is not a valid `labelName`
+// @ts-expect-error
+gauge.inc({ methods: 1 });
+```
+
 #### Default Labels (segmented by registry)
 
 Static labels may be applied to every metric emitted by a registry:
@@ -457,8 +481,17 @@ gateway.pushAdd({ jobName: 'test', groupings: { key: 'value' } }, function (
   body,
 ) {});
 
-//It's possible to extend the Pushgateway with request options from nodes core http/https library
-gateway = new client.Pushgateway('http://127.0.0.1:9091', { timeout: 5000 }); //Set the request timeout to 5000ms
+// It's possible to extend the Pushgateway with request options from nodes core
+// http/https library. In particular, you might want to provide an agent so that
+// TCP connections are reused.
+gateway = new client.Pushgateway('http://127.0.0.1:9091', {
+  timeout: 5000, //Set the request timeout to 5000ms
+  agent: new http.Agent({
+    keepAlive: true,
+    keepAliveMsec: 10000,
+    maxSockets: 5,
+  }),
+});
 ```
 
 ### Bucket Generators

example/counter.js

@@ -0,0 +1,77 @@
+'use strict';
+
+// Counter
+// Single Label
+// Multiple Values
+
+const { Counter, register } = require('..');
+const c = new Counter({
+	name: 'test_counter',
+	help: 'Example of a counter',
+	labelNames: ['code'],
+});
+
+c.inc({ code: 200 });
+console.log(register.metrics());
+
+/*
+# HELP test_counter Example of a counter
+# TYPE test_counter counter
+test_counter{code="200"} 1
+*/
+
+c.inc({ code: 200 });
+console.log(register.metrics());
+
+/*
+# HELP test_counter Example of a counter
+# TYPE test_counter counter
+test_counter{code="200"} 2
+*/
+
+c.inc();
+console.log(register.metrics());
+
+/*
+# HELP test_counter Example of a counter
+# TYPE test_counter counter
+test_counter{code="200"} 2
+test_counter 1
+*/
+
+c.reset();
+console.log(register.metrics());
+
+/*
+# HELP test_counter Example of a counter
+# TYPE test_counter counter
+*/
+
+c.inc(15);
+console.log(register.metrics());
+
+/*
+# HELP test_counter Example of a counter
+# TYPE test_counter counter
+test_counter 15
+*/
+
+c.inc({ code: 200 }, 12);
+console.log(register.metrics());
+
+/*
+# HELP test_counter Example of a counter
+# TYPE test_counter counter
+test_counter 15
+test_counter{code="200"} 12
+*/
+
+c.labels('200').inc(12);
+console.log(register.metrics());
+
+/*
+# HELP test_counter Example of a counter
+# TYPE test_counter counter
+test_counter 15
+test_counter{code="200"} 24
+*/

example/default-metrics.js

@@ -0,0 +1,149 @@
+'use strict';
+
+const { collectDefaultMetrics, register } = require('..');
+
+collectDefaultMetrics({
+	timeout: 10000,
+	gcDurationBuckets: [0.001, 0.01, 0.1, 1, 2, 5], // These are the default buckets.
+});
+
+console.log(register.metrics());
+
+/*
+Output from metrics():
+
+# HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.
+# TYPE process_cpu_user_seconds_total counter
+process_cpu_user_seconds_total 0.004261
+
+# HELP process_cpu_system_seconds_total Total system CPU time spent in seconds.
+# TYPE process_cpu_system_seconds_total counter
+process_cpu_system_seconds_total 0.000547
+
+# HELP process_cpu_seconds_total Total user and system CPU time spent in seconds.
+# TYPE process_cpu_seconds_total counter
+process_cpu_seconds_total 0.004808
+
+# HELP process_start_time_seconds Start time of the process since unix epoch in seconds.
+# TYPE process_start_time_seconds gauge
+process_start_time_seconds 1585092233
+
+# HELP process_resident_memory_bytes Resident memory size in bytes.
+# TYPE process_resident_memory_bytes gauge
+process_resident_memory_bytes 37072896
+
+# HELP process_virtual_memory_bytes Virtual memory size in bytes.
+# TYPE process_virtual_memory_bytes gauge
+process_virtual_memory_bytes 576438272
+
+# HELP process_heap_bytes Process heap size in bytes.
+# TYPE process_heap_bytes gauge
+process_heap_bytes 50720768
+
+# HELP process_open_fds Number of open file descriptors.
+# TYPE process_open_fds gauge
+process_open_fds 98
+
+# HELP process_max_fds Maximum number of open file descriptors.
+# TYPE process_max_fds gauge
+process_max_fds 1048576
+
+# HELP nodejs_eventloop_lag_seconds Lag of event loop in seconds.
+# TYPE nodejs_eventloop_lag_seconds gauge
+nodejs_eventloop_lag_seconds 0
+
+# HELP nodejs_eventloop_lag_min_seconds The minimum recorded event loop delay.
+# TYPE nodejs_eventloop_lag_min_seconds gauge
+nodejs_eventloop_lag_min_seconds 9223372036.854776
+
+# HELP nodejs_eventloop_lag_max_seconds The maximum recorded event loop delay.
+# TYPE nodejs_eventloop_lag_max_seconds gauge
+nodejs_eventloop_lag_max_seconds 0
+
+# HELP nodejs_eventloop_lag_mean_seconds The mean of the recorded event loop delays.
+# TYPE nodejs_eventloop_lag_mean_seconds gauge
+nodejs_eventloop_lag_mean_seconds Nan
+
+# HELP nodejs_eventloop_lag_stddev_seconds The standard deviation of the recorded event loop delays.
+# TYPE nodejs_eventloop_lag_stddev_seconds gauge
+nodejs_eventloop_lag_stddev_seconds Nan
+
+# HELP nodejs_eventloop_lag_p50_seconds The 50th percentile of the recorded event loop delays.
+# TYPE nodejs_eventloop_lag_p50_seconds gauge
+nodejs_eventloop_lag_p50_seconds 0
+
+# HELP nodejs_eventloop_lag_p90_seconds The 90th percentile of the recorded event loop delays.
+# TYPE nodejs_eventloop_lag_p90_seconds gauge
+nodejs_eventloop_lag_p90_seconds 0
+
+# HELP nodejs_eventloop_lag_p99_seconds The 99th percentile of the recorded event loop delays.
+# TYPE nodejs_eventloop_lag_p99_seconds gauge
+nodejs_eventloop_lag_p99_seconds 0
+
+# HELP nodejs_active_handles Number of active libuv handles grouped by handle type. Every handle type is C++ class name.
+# TYPE nodejs_active_handles gauge
+
+# HELP nodejs_active_handles_total Total number of active handles.
+# TYPE nodejs_active_handles_total gauge
+nodejs_active_handles_total 0
+
+# HELP nodejs_active_requests Number of active libuv requests grouped by request type. Every request type is C++ class name.
+# TYPE nodejs_active_requests gauge
+
+# HELP nodejs_active_requests_total Total number of active requests.
+# TYPE nodejs_active_requests_total gauge
+nodejs_active_requests_total 0
+
+# HELP nodejs_heap_size_total_bytes Process heap size from Node.js in bytes.
+# TYPE nodejs_heap_size_total_bytes gauge
+nodejs_heap_size_total_bytes 5746688
+
+# HELP nodejs_heap_size_used_bytes Process heap size used from Node.js in bytes.
+# TYPE nodejs_heap_size_used_bytes gauge
+nodejs_heap_size_used_bytes 3870560
+
+# HELP nodejs_external_memory_bytes Node.js external memory size in bytes.
+# TYPE nodejs_external_memory_bytes gauge
+nodejs_external_memory_bytes 1221803
+
+# HELP nodejs_heap_space_size_total_bytes Process heap space size total from Node.js in bytes.
+# TYPE nodejs_heap_space_size_total_bytes gauge
+nodejs_heap_space_size_total_bytes{space="read_only"} 262144
+nodejs_heap_space_size_total_bytes{space="new"} 2097152
+nodejs_heap_space_size_total_bytes{space="old"} 2244608
+nodejs_heap_space_size_total_bytes{space="code"} 430080
+nodejs_heap_space_size_total_bytes{space="map"} 528384
+nodejs_heap_space_size_total_bytes{space="large_object"} 135168
+nodejs_heap_space_size_total_bytes{space="code_large_object"} 49152
+nodejs_heap_space_size_total_bytes{space="new_large_object"} 0
+
+# HELP nodejs_heap_space_size_used_bytes Process heap space size used from Node.js in bytes.
+# TYPE nodejs_heap_space_size_used_bytes gauge
+nodejs_heap_space_size_used_bytes{space="read_only"} 32808
+nodejs_heap_space_size_used_bytes{space="new"} 955440
+nodejs_heap_space_size_used_bytes{space="old"} 2231120
+nodejs_heap_space_size_used_bytes{space="code"} 165472
+nodejs_heap_space_size_used_bytes{space="map"} 353760
+nodejs_heap_space_size_used_bytes{space="large_object"} 131112
+nodejs_heap_space_size_used_bytes{space="code_large_object"} 2784
+nodejs_heap_space_size_used_bytes{space="new_large_object"} 0
+
+# HELP nodejs_heap_space_size_available_bytes Process heap space size available from Node.js in bytes.
+# TYPE nodejs_heap_space_size_available_bytes gauge
+nodejs_heap_space_size_available_bytes{space="read_only"} 0
+nodejs_heap_space_size_available_bytes{space="new"} 92016
+nodejs_heap_space_size_available_bytes{space="old"} 3608
+nodejs_heap_space_size_available_bytes{space="code"} 0
+nodejs_heap_space_size_available_bytes{space="map"} 0
+nodejs_heap_space_size_available_bytes{space="large_object"} 0
+nodejs_heap_space_size_available_bytes{space="code_large_object"} 0
+nodejs_heap_space_size_available_bytes{space="new_large_object"} 1047456
+
+# HELP nodejs_version_info Node.js version info.
+# TYPE nodejs_version_info gauge
+nodejs_version_info{version="v12.16.1",major="12",minor="16",patch="1"} 1
+
+# HELP nodejs_gc_duration_seconds Garbage collection duration by kind, one of major, minor, incremental or weakcb.
+# TYPE nodejs_gc_duration_seconds histogram
+
+*/

example/gauge.js

@@ -0,0 +1,56 @@
+'use strict';
+
+// Gauge
+// Single Label
+// Multiple Values
+
+const { Gauge, register } = require('..');
+const g = new Gauge({
+	name: 'test_gauge',
+	help: 'Example of a gauge',
+	labelNames: ['code'],
+});
+
+g.set({ code: 200 }, 5);
+console.log(register.metrics());
+/*
+# HELP test_gauge Example of a gauge
+# TYPE test_gauge gauge
+test_gauge{code="200"} 5
+ */
+
+g.set(15);
+console.log(register.metrics());
+/*
+# HELP test_gauge Example of a gauge
+# TYPE test_gauge gauge
+test_gauge{code="200"} 5
+test_gauge 15
+ */
+
+g.labels('200').inc();
+console.log(register.metrics());
+/*
+# HELP test_gauge Example of a gauge
+# TYPE test_gauge gauge
+test_gauge{code="200"} 6
+test_gauge 15
+ */
+
+g.inc();
+console.log(register.metrics());
+/*
+# HELP test_gauge Example of a gauge
+# TYPE test_gauge gauge
+test_gauge{code="200"} 6
+test_gauge 16
+ */
+
+g.set(22);
+console.log(register.metrics());
+/*
+# HELP test_gauge Example of a gauge
+# TYPE test_gauge gauge
+test_gauge{code="200"} 6
+test_gauge 22
+ */