@metrics/client - npm Package Compare versions

Comparing version 2.2.0 to 2.3.0

lib/client.js

@@ -8,7 +8,12 @@ 'use strict';
 const crypto = require('crypto');
-const Metric = require('./metric');
+const Metric = require('@metrics/metric');
 
+const Counter = require('./counter');
+const Gauge = require('./gauge');
+const Summary = require('./summary');
+const Histogram = require('./histogram');
+
 const push = Symbol('push');
 
-module.exports = class Metrics extends stream.Transform {
+const MetricsClient = class MetricsClient extends stream.Transform {
     constructor({ id = undefined } = {}) {
@@ -31,3 +36,3 @@ super(
     get [Symbol.toStringTag]() {
-        return 'Metrics';
+        return 'MetricsClient';
     }
@@ -46,2 +51,42 @@
 
+    counter(options) {
+        const counter = new Counter(options);
+        counter.on('metric', metric => {
+            // eslint-disable-next-line no-param-reassign
+            metric.source = this.source;
+            this[push](metric);
+        });
+        return counter;
+    }
+
+    gauge(options) {
+        const gauge = new Gauge(options);
+        gauge.on('metric', metric => {
+            // eslint-disable-next-line no-param-reassign
+            metric.source = this.source;
+            this[push](metric);
+        });
+        return gauge;
+    }
+
+    summary(options) {
+        const summary = new Summary(options);
+        summary.on('metric', metric => {
+            // eslint-disable-next-line no-param-reassign
+            metric.source = this.source;
+            this[push](metric);
+        });
+        return summary;
+    }
+
+    histogram(options) {
+        const histogram = new Histogram(options);
+        histogram.on('metric', metric => {
+            // eslint-disable-next-line no-param-reassign
+            metric.source = this.source;
+            this[push](metric);
+        });
+        return histogram;
+    }
+
     timer(options = {}) {
@@ -53,8 +98,9 @@ const end = timeSpan();
             const metric = new Metric({
-                timestamp: Date.now() / 1000,
+                type: 5,
+                value: time,
                 ...options,
                 ...opts,
-                time,
                 meta,
             });
+            metric.source = this.source;
             this[push](metric);
@@ -65,6 +111,4 @@ };
     metric(options) {
-        const metric = new Metric({
-            timestamp: Date.now() / 1000,
-            ...options,
-        });
+        const metric = new Metric(options);
+        metric.source = this.source;
         this[push](metric);
@@ -82,1 +126,3 @@ }
 };
+
+module.exports = MetricsClient;

package.json

 {
   "name": "@metrics/client",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Streaming system independent metric production",
@@ -18,3 +18,11 @@ "main": "lib/client.js",
   "license": "MIT",
+  "keywords": [
+    "server-statistics",
+    "server-stats",
+    "statistics",
+    "metrics",
+    "monitoring"
+  ],
   "dependencies": {
+    "@metrics/metric": "^2.3.0",
     "readable-stream": "^3.1.1",
@@ -21,0 +29,0 @@ "time-span": "^2.0.0"

README.md

 # @metrics/client
 
+[![Greenkeeper badge](https://badges.greenkeeper.io/metrics-js/client.svg)](https://greenkeeper.io/)
+
 A streaming metric producer. Allows producing counters, gauges, time series in a way that is independent of your metrics system so that you can produce metrics and let consumers decide how to consume them. Additionally, you can pipe together different metrics streams before finally consuming them all in a single location.
@@ -22,7 +24,8 @@
 ```js
-client.metric({
+const counter = client.counter({
     name: 'unique_metric_name',
     description: 'Description of metric being collected',
-    value: 10,
 });
+
+counter.inc();
 ```
@@ -38,52 +41,75 @@
 
-The client supports 2 types of metric creation use cases. 1. timers (via `client.timer`) and 2. Non timers (via `client.metric`)
+The client supports 4 types of metric creation use cases.
 
--   Histograms are supported by using the timer functionality.
--   Gauges are supported via setting the `value` property.
--   Counters are implicit. ie. Each metric added can be counted by a consumer.
--   Timestamps are always generated by default for all metrics.
+-   Counters are supported via the `client.counter` method
+-   Gauges are supported via the `client.gauge` method
+-   Histograms are supported via the `client.histogram` method
+-   Summaries are supported via the `client.summary` method
 
 ## Examples
 
-_A metric to be used in a counter_
+_Creating and incrementing a counter_
 
 ```js
-client.metric({
+const counter = client.counter({
     name: 'my_counter',
     description: 'Counter description',
 });
+counter.inc();
 ```
 
-_Setting a value to be used in a gauge_
+_Creating and incrementing a gauge_
 
 ```js
-client.metric({
+const gauge = client.gauge({
     name: 'my_gauge',
     description: 'Gauge description',
-    value: 123,
 });
+gauge.set(10);
 ```
 
-_A timer to be used in a histogram_
+_Creating and incrementing a summary_
 
 ```js
-const end = client.timer({
-    name: 'my_histogram',
-    description: 'Histogram description'
+const summary = client.summary({
+    name: 'my_summary',
+    description: 'Summary description',
 });
-await something();
+summary.observe(0.123);
+```
+
+_Creating and incrementing a summary using a timer_
+
+```js
+const summary = client.summary({
+    name: 'my_summary',
+    description: 'Summary description',
+});
+const end = summary.timer();
+// ... time something
 end();
 ```
 
-_A timer to be used in a histogram and a gauge_
+_Creating and incrementing a histogram_
 
 ```js
-const end = client.timer({
-    name: 'my_histogram_gauge',
-    description: 'Histogram gauge example'
+const histogram = client.histogram({
+    name: 'my_histogram',
+    description: 'Histogram description',
 });
-await something();
-end({ value: 123 });
+histogram.observe(0.123);
 ```
 
+_Creating and incrementing a histogram using a timer_
+
+```js
+const histogram = client.histogram({
+    name: 'my_histogram',
+    description: 'Histogram description',
+});
+const end = histogram.timer();
+// ... time something
+end();
+```
+
 ## Composing metric streams
@@ -104,3 +130,7 @@
 
-client.metric({...})
+const counter = client.counter({
+    name: 'my_counter',
+    description: 'Counter description',
+});
+counter.inc();
 
@@ -116,3 +146,7 @@ module.exports.metrics = client;
 
-client.metric({...})
+const counter = client.counter({
+    name: 'my_counter',
+    description: 'Counter description',
+});
+counter.inc();
 
@@ -128,3 +162,4 @@ module.exports.metrics = client;
 
-module1.pipe(module2).pipe(consumer);
+module1.pipe(consumer);
+module2.pipe(consumer);
 ```
@@ -154,3 +189,15 @@
     _write(metric, enc, cb) {
-        this.counter.labels(metric.meta.url, metric.meta.method).inc(1);
+        let url;
+        let method;
+
+        metric.labels.forEach(obj => {
+            if (obj.name === 'url') {
+                url = obj.value;
+            }
+            if (obj.name === 'method') {
+                url = obj.value;
+            }
+        });
+
+        this.counter.labels(url, method).inc(1);
         cb();
@@ -173,5 +220,5 @@ }
 
-| name        | description                                                         | type     | default |
-| ----------- | ------------------------------------------------------------------- | -------- | ------- |
-| `id`        | A optional unique identifier of the instance of the Object.         | `string` | hash    |
+| name | description                                                 | type     | default |
+| ---- | ----------------------------------------------------------- | -------- | ------- |
+| `id` | A optional unique identifier of the instance of the Object. | `string` | hash    |
 
@@ -188,5 +235,239 @@ _Example_
 
+#### .counter(options)
+
+Creates an instance of a `Counter` class which can be used to populate the metrics stream with counter metrics.
+
+**options**
+
+| name          | description                                   | type     | default | required |
+| ------------- | --------------------------------------------- | -------- | ------- | -------- |
+| `name`        | Metric name. valid characters: a-z,A-Z,0-9,\_ | `string` | null    | `true`   |
+| `description` | Metric description                            | `string` | null    | `true`   |
+| `labels`      | Available to be used to hold label data.      | `object` | null    | `false`  |
+
+**return**: `Counter`
+
+_Example_
+
+```js
+const client = new Metrics(options);
+const counter = client.counter(options);
+```
+
+##### counter.inc(value|options, options)
+
+Method that when called will populate the metrics stream with a counter increment.
+
+| name      | description                               | type      | default | required |
+| --------- | ----------------------------------------- | --------- | ------- | -------- |
+| `value`   | Value to increment the counter by         | `integer` | `1`     | `false`  |
+| `options` | Object that can be used to specify labels | `object`  | `{}`    | `false`  |
+
+_Example_
+
+```js
+const counter = client.counter(options);
+
+counter.inc(); // increment by 1
+counter.inc(10); // increment by 10
+counter.inc({ labels: { url: 'http://finn.no' } }); // increment by 1, specify labels
+counter.inc(5, { labels: { url: 'http://finn.no' } }); // increment by 5, specify labels
+```
+
+#### .gauge(options)
+
+Creates an instance of a `Gauge` class which can be used to populate the metrics stream with gauge metrics.
+
+**options**
+
+| name          | description                                   | type     | default | required |
+| ------------- | --------------------------------------------- | -------- | ------- | -------- |
+| `name`        | Metric name. valid characters: a-z,A-Z,0-9,\_ | `string` | null    | `true`   |
+| `description` | Metric description                            | `string` | null    | `true`   |
+| `labels`      | Available to be used to hold label data.      | `object` | null    | `false`  |
+
+_Example_
+
+```js
+const client = new Metrics(options);
+const gauge = client.gauge(options);
+```
+
+##### gauge.set(value, options)
+
+Method that when called will populate the metrics stream with a gauge value.
+
+| name      | description                               | type      | default | required |
+| --------- | ----------------------------------------- | --------- | ------- | -------- |
+| `value`   | Value to set the gauge to                 | `integer` | null    | `true`   |
+| `options` | Object that can be used to specify labels | `object`  | `{}`    | `false`  |
+
+_Example_
+
+```js
+const gauge = client.gauge(options);
+
+gauge.set(10); // set to 10
+gauge.set(5, { labels: { url: 'http://finn.no' } }); // set to 5, specify labels
+```
+
+#### .histogram(options)
+
+Creates an instance of a `Histogram` class which can be used to populate the metrics stream with histogram metrics.
+
+**options**
+
+| name          | description                                   | type     | default | required |
+| ------------- | --------------------------------------------- | -------- | ------- | -------- |
+| `name`        | Metric name. valid characters: a-z,A-Z,0-9,\_ | `string` | null    | `true`   |
+| `description` | Metric description                            | `string` | null    | `true`   |
+| `meta`        | Available to be used to hold any misc data.   | `object` | null    | `false`  |
+| `labels`      | Available to be used to hold label data.      | `object` | null    | `false`  |
+
+_Example_
+
+```js
+const client = new Metrics(options);
+const histogram = client.histogram(options);
+```
+
+##### histogram.observe(value, options)
+
+Method that when called will populate the metrics stream with a histogram value.
+
+| name      | description                                        | type      | default | required |
+| --------- | -------------------------------------------------- | --------- | ------- | -------- |
+| `value`   | Value to set the gauge to                          | `integer` | null    | `true`   |
+| `options` | Object that can be used to specify labels and meta | `object`  | `{}`    | `false`  |
+
+_Example_
+
+```js
+const histogram = client.histogram(options);
+
+histogram.observe(0.001); // observe value 0.001
+histogram.observe(5, { labels: { url: 'http://finn.no' } }); // observe value 5, specify labels
+histogram.observe(0.01, {
+    meta: { buckets: [0.0001, 0.001, 0.01, 0.1, 0.5, 1, 10, 100] }, // observe 0.01, use meta to specify bucket options
+});
+```
+
+##### histogram.timer(options)
+
+Method that when called will return an end function for use in measuring the time between 2 points
+
+| name      | description                                        | type     | default | required |
+| --------- | -------------------------------------------------- | -------- | ------- | -------- |
+| `options` | Object that can be used to specify labels and meta | `object` | `{}`    | `false`  |
+
+_Examples_
+
+```js
+const histogram = client.histogram(options);
+
+const end = histogram.timer(); // start timer
+// stuff happens
+end();
+```
+
+```js
+const end = histogram.timer({ labels: { url: 'http://finn.no' } }); // start timer, set labels
+// stuff happens
+end();
+```
+
+```js
+const end = histogram.timer(); // start timer
+// stuff happens
+end({ labels: { url: 'http://finn.no' } }); // set labels in end function
+```
+
+```js
+const end = histogram.timer(meta: { buckets: [0.0001, 0.001, 0.01, 0.1, 0.5, 1, 10, 100] }); // start timer, set meta
+// stuff happens
+end();
+```
+
+#### .summary(options)
+
+Creates an instance of a `Summary` class which can be used to populate the metrics stream with summary metrics.
+
+**options**
+
+| name          | description                                   | type     | default | required |
+| ------------- | --------------------------------------------- | -------- | ------- | -------- |
+| `name`        | Metric name. valid characters: a-z,A-Z,0-9,\_ | `string` | null    | `true`   |
+| `description` | Metric description                            | `string` | null    | `true`   |
+| `meta`        | Available to be used to hold any misc data.   | `object` | null    | `false`  |
+| `labels`      | Available to be used to hold label data.      | `object` | null    | `false`  |
+
+_Example_
+
+```js
+const client = new Metrics(options);
+const summary = client.summary(options);
+```
+
+##### summary.observe(value, options)
+
+Method that when called will populate the metrics stream with a summary value.
+
+| name      | description                                        | type      | default | required |
+| --------- | -------------------------------------------------- | --------- | ------- | -------- |
+| `value`   | Value to set the summary to                        | `integer` | null    | `true`   |
+| `options` | Object that can be used to specify labels and meta | `object`  | `{}`    | `false`  |
+
+_Example_
+
+```js
+const summary = client.summary(options);
+
+summary.observe(0.001); // observe value 0.001
+summary.observe(5, { labels: { url: 'http://finn.no' } }); // observe value 5, specify labels
+summary.observe(0.01, {
+    meta: { quantiles: [0.001, 0.01, 0.5, 0.9, 0.99] }, // observe 0.01, use meta to specify quantile meta
+});
+```
+
+##### summary.timer(options)
+
+Method that when called will return an end function for use in measuring the time between 2 points
+
+| name      | description                                        | type     | default | required |
+| --------- | -------------------------------------------------- | -------- | ------- | -------- |
+| `options` | Object that can be used to specify labels and meta | `object` | `{}`    | `false`  |
+
+_Examples_
+
+```js
+const summary = client.summary(options);
+
+const end = summary.timer(); // start timer
+// stuff happens
+end();
+```
+
+```js
+const end = summary.timer({ labels: { url: 'http://finn.no' } }); // start timer, set labels
+// stuff happens
+end();
+```
+
+```js
+const end = summary.timer(); // start timer
+// stuff happens
+end({ labels: { url: 'http://finn.no' } }); // set labels in end function
+```
+
+```js
+const end = summary.timer({
+    meta: { quantiles: [0.001, 0.01, 0.5, 0.9, 0.99] },
+}); // start timer, set meta
+// stuff happens
+end();
+```
+
 #### .metric(options)
 
-Collects a metric. As a minimum, a name and description for the metric must be provided.
+Collects a generic metric. As a minimum, a name and description for the metric must be provided.
 
@@ -201,5 +482,4 @@ **options**
 | `meta`        | Available to be used to hold any misc data.      | `object`         | null    | `false`  |
+| `labels`      | Available to be used to hold label data.         | `array[object]`  | null    | `false`  |
 
-**n.b.** In practice, `meta` can be used as a way to label metrics. Use each key of the meta object as the label name and the value as the label value
-
 **return**: `void`
@@ -214,2 +494,36 @@
 
+**meta**
+
+`meta` can be used to hold any additional information you might wish to pass on to a consumer.
+It should be an object of keys and values.
+
+```js
+client.metric({
+    name: 'my_metric',
+    description: 'My HTTP timing metric',
+    meta: {
+        quantiles: [0.01, 0.1, 0.5, 0.9, 0.99],
+    },
+});
+```
+
+**labels**
+
+`labels` can be used to pass on specific label metadata to a consumer. Examples of labels are the URL or method when
+timing HTTP requests.
+
+Labels should be defined as an array of objects where each object has a `name` and `value` property.
+The `name` property describes the labels name and the `value` property describes the label's actual value.
+
+```js
+client.metric({
+    name: 'my_metric',
+    description: 'My HTTP timing metric',
+    labels: [
+        { name: 'url', value: 'http://finn.no' },
+        { name: 'method', value: 'get' },
+    ],
+});
+```
+
 #### .timer(options)
@@ -228,4 +542,2 @@
 
-**n.b.** In practice, `meta` can be used as a way to label metrics. Use each key of the meta object as the label name and the value as the label value
-
 **return**: `function` Returns an end function (see below) to be used to indicate that the timer measurement is finished.
@@ -252,4 +564,2 @@
 
-**n.b.** In practice, `meta` can be used as a way to label metrics. Use each key of the meta object as the label name and the value as the label value
-
 **return**: `void`
@@ -256,0 +566,0 @@

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

30538

increased by102.39%

Number of package files

9

increased by50%

Lines of code

310

increased by129.63%

Number of lines in readme file

577

increased by116.1%

Worsened metrics

Dependency count

3

increased by50%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Added@metrics/metric@^2.3.0

• + Added@metrics/metric@2.3.4(transitive)