Skip to content

Commit 84f1429

Browse files
wkillerudwkillerud
authored
docs: deduplicate reference documentation
1 parent acd07b5 commit 84f1429

File tree

1 file changed

+4
-230
lines changed

1 file changed

+4
-230
lines changed

‎README.md‎

Lines changed: 4 additions & 230 deletions
Original file line numberDiff line numberDiff line change
@@ -1,237 +1,11 @@
11
# @metrics/guard
22

3-
Module to guard against excessive metric permutation creation in a metric stream.
4-
5-
[![Dependencies](https://img.shields.io/david/metrics-js/guard.svg)](https://david-dm.org/metrics-js/guard)
63
[![GitHub Actions status](https://github.com/metrics-js/guard/workflows/Run%20Lint%20and%20Tests/badge.svg)](https://github.com/metrics-js/guard/actions?query=workflow%3A%22Run+Lint+and+Tests%22)
74
[![Known Vulnerabilities](https://snyk.io/test/github/metrics-js/guard/badge.svg?targetFile=package.json)](https://snyk.io/test/github/metrics-js/guard?targetFile=package.json)
85

6+
Module to guard against excessive metric permutation creation in a metric stream.
97

10-
## Installation
11-
12-
```bash
13-
$ npm install @metrics/guard
14-
```
15-
16-
## Example
17-
18-
Guard a metric stream.
19-
20-
```js
21-
const Collector = require('someMetricCollector');
22-
const Client = require('@metrics/client');
23-
const Guard = require('@metrics/guard');
24-
25-
const collector = new Collector();
26-
const client = new Client();
27-
const guard = new Guard();
28-
29-
guard.on('warn', (info) => {
30-
console.log(`WARN: ${info} is creating a growing number of permutations`);
31-
});
32-
33-
guard.on('drop', (metric) => {
34-
console.log(`CRITICAL: ${metric.name} has created to many permutations. Metric is dropped.`);
35-
});
36-
37-
client.pipe(guard).pipe(collector);
38-
39-
const counter = client.counter({
40-
name: 'my_counter',
41-
description: 'Counter description',
42-
});
43-
44-
for (let i = 0; i < 10000; i++) {
45-
counter.inc({ labels: { index: i } });
46-
}
47-
```
48-
49-
## Description
50-
51-
Metrics, in general, should be created and curated with care to make sure one
52-
collects metrics which give value without causing system drainage. It is
53-
effortless to produce excessive amounts of metrics from an application, which
54-
in a worst-case scenario can bring both the application and the metric system
55-
to a halt.
56-
57-
As an example; a widespread mistake when creating metrics in a web application
58-
is to count the number of requests to a route which contains a user ID and
59-
pass the URL on as a label to the metric.
60-
61-
```js
62-
const client = new Client();
63-
const app = express();
64-
65-
const counter = client.counter({
66-
name: 'http_requests',
67-
description: 'Number of HTTP requests',
68-
});
69-
70-
app.get('/home/#id', (req, res) => {
71-
counter.inc({ labels: { url: req.originalUrl } });
72-
res.send(`Hello ${req.params.id}`)
73-
});
74-
```
75-
76-
The above will in some metric systems generate a new permutation of the metric
77-
for each unique URL and since the URL contain users IDs one can potentially
78-
generate a massive amount of permutations.
79-
80-
In other words; the above is something one should avoid. But it's a common
81-
mistake to do.
82-
83-
This module guards against excessive metric and permutation creation in a metric
84-
stream. If a mistake, such as the one above, is made, this module will guard
85-
against a bad metric filling up the metric stream.
86-
87-
### Permutation threshold
88-
89-
Labels on a metric is the normal culprit to excessive metric permutation creation,
90-
since labels are normally a permutation of the metric.
91-
92-
Due to this, the guard monitors the amount of permutations of a metric and if a
93-
threshold of permutations is exceeded the guard will drop the metric from the
94-
metric stream and emit a `drop` event.
95-
96-
Prior to a metric exceeding the threshold, the guard will start emitting
97-
a `warn` event that the metric is growing close to the threshold. At this point
98-
the metric is still pushed forward on the metric stream.
99-
100-
The above events can be used to log bad metrics or alert developers to take
101-
action.
102-
103-
### Metrics threshold
104-
105-
It also might be that an application is just reporting too many different metrics.
106-
107-
This guard will also monitor the amount of unique metrics and will start emitting
108-
a `warn` event when a threshold of allowed unique metrics is exceeded.
109-
110-
Metrics will not be dropped due to this.
111-
112-
## Constructor
113-
114-
Create a new Guard instance.
115-
116-
```js
117-
const Guard = require('@metrics/guard');
118-
const guard = new Guard(options);
119-
```
120-
121-
### options (optional)
122-
123-
An Object containing misc configuration. The following values can be provided:
124-
125-
* **permutationThreshold** - `Number` - Threshold of how many permutations of a metrics which should be allowed. Default: 1000.
126-
* **metricsThreshold** - `Number` - Threshold of how many unique metrics which should be allowed. Default: 60.
127-
* **enabled** - `Boolean` - If the guard should be enabled or not. Default: `true`.
128-
* **id** - `String` - Give the instanse a unique identifier. Default: `hash`
129-
130-
The Guard instance inherit from Transform Stream. Due to this the instance also
131-
take all config parameters which the Transform Stream does.
132-
133-
Please see the [documentation of Transform Streams](https://nodejs.org/api/stream.html#stream_duplex_and_transform_streams) for further documentation.
134-
135-
## API
136-
137-
The Guard instance have the following API:
138-
139-
### .getMetrics()
140-
141-
Get a list off the names of all the metrics which has been registered by the
142-
guard.
143-
144-
```js
145-
const guard = new Guard();
146-
guard.getMetrics();
147-
```
148-
149-
Returns an `Array`.
150-
151-
### .getLabels(name)
152-
153-
Get a list off all the different labels on a metrics which has been registered
154-
by the guard.
155-
156-
```js
157-
const guard = new Guard();
158-
guard.getLabels('foo');
159-
```
160-
161-
This method take the following arguments:
162-
163-
* **name** - The name of the metric to retrieve labels from. Required.
164-
165-
Returns an `Array` with label `Objects`.
166-
167-
### .reset()
168-
169-
Resets the guard. All collected info about the metric stream is dropped.
170-
171-
```js
172-
const guard = new Guard();
173-
guard.reset();
174-
```
175-
176-
## Events
177-
178-
The Guard instance inherit from Transform Stream. Due to this the instance emits all
179-
the events which Transform Stream does when the streaming feature is used.
180-
181-
Please see the [documentation of Transform Streams](https://nodejs.org/api/stream.html#stream_duplex_and_transform_streams) for further documentation.
182-
183-
In addition to this, the following events are emitted:
184-
185-
### warn
186-
187-
Emitted prior to when permutation threshold is exceeded or when the metrics
188-
threshold is exceeded.
189-
190-
```js
191-
const guard = new Guard();
192-
guard.on('warn', (type, info) => {
193-
if (type === 'metrics') {
194-
console.log(`WARN: application has over ${info} unique metrics`);
195-
}
196-
197-
if (type === 'permutation') {
198-
console.log(`WARN: ${info} is creating a growing number of permutations`);
199-
}
200-
});
201-
```
202-
203-
### drop
204-
205-
Emitted when a permutation threshold is exceeded or when a circular stream has
206-
been detected.
207-
208-
```js
209-
const guard = new Guard();
210-
guard.on('drop', (metric) => {
211-
console.log(`CRITICAL: Metric with the name ${metric.name} is dropped.`);
212-
});
213-
```
214-
215-
## License
216-
217-
The MIT License (MIT)
218-
219-
Copyright (c) 2019 Trygve Lie
220-
221-
Permission is hereby granted, free of charge, to any person obtaining a copy
222-
of this software and associated documentation files (the "Software"), to deal
223-
in the Software without restriction, including without limitation the rights
224-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
225-
copies of the Software, and to permit persons to whom the Software is
226-
furnished to do so, subject to the following conditions:
227-
228-
The above copyright notice and this permission notice shall be included in all
229-
copies or substantial portions of the Software.
8+
## Usage
2309

231-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
232-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
233-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
234-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
235-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
236-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
237-
SOFTWARE.
10+
- [Getting started with MetricsJS](https://metrics-js.github.io/introduction/getting-started/).
11+
- [Reference documentaiton for `@metrics/guard`](https://metrics-js.github.io/reference/guard/).

0 commit comments

Comments
 (0)