Skip to content

Commit e844876

Browse files
digitalsadhudigitalsadhu
authored
Merge pull request #77 from metrics-js/types
Add type definitions for the client and fix some stuff in the readme
2 parents a848a80 + 63f82b6 commit e844876

File tree

3 files changed

+180
-40
lines changed

3 files changed

+180
-40
lines changed

‎README.md‎

Lines changed: 40 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,7 @@ class Consumer extends Writable {
190190
let url;
191191
let method;
192192

193-
metric.labels.forEach(obj => {
193+
metric.labels.forEach((obj) => {
194194
if (obj.name === 'url') {
195195
url = obj.value;
196196
}
@@ -315,12 +315,12 @@ Creates an instance of a `Histogram` class which can be used to populate the met
315315

316316
**options**
317317

318-
| name | description | type | default | required |
319-
| ------------- | --------------------------------------------- | -------- | ------- | -------- |
320-
| `name` | Metric name. valid characters: a-z,A-Z,0-9,\_ | `string` | null | `true` |
321-
| `description` | Metric description | `string` | null | `true` |
322-
| `meta` | Available to be used to hold any misc data. | `object` | null | `false` |
323-
| `labels` | Available to be used to hold label data. | `object` | null | `false` |
318+
| name | description | type | default | required |
319+
| ------------- | --------------------------------------------- | ---------- | ------- | -------- |
320+
| `name` | Metric name. valid characters: a-z,A-Z,0-9,\_ | `string` | null | `true` |
321+
| `description` | Metric description | `string` | null | `true` |
322+
| `buckets` | Set custom buckets | `number[]` | null | `false` |
323+
| `labels` | Available to be used to hold label data. | `object` | null | `false` |
324324

325325
_Example_
326326

@@ -333,10 +333,10 @@ const histogram = client.histogram(options);
333333

334334
Method that when called will populate the metrics stream with a histogram value.
335335

336-
| name | description | type | default | required |
337-
| --------- | -------------------------------------------------- | --------- | ------- | -------- |
338-
| `value` | Value to set the gauge to | `integer` | null | `true` |
339-
| `options` | Object that can be used to specify labels and meta | `object` | `{}` | `false` |
336+
| name | description | type | default | required |
337+
| --------- | ----------------------------------------------------- | --------- | ------- | -------- |
338+
| `value` | Value to set the gauge to | `integer` | null | `true` |
339+
| `options` | Object that can be used to specify labels and buckets | `object` | `{}` | `false` |
340340

341341
_Example_
342342

@@ -345,18 +345,19 @@ const histogram = client.histogram(options);
345345

346346
histogram.observe(0.001); // observe value 0.001
347347
histogram.observe(5, { labels: { url: 'http://finn.no' } }); // observe value 5, specify labels
348-
histogram.observe(0.01, {
349-
meta: { buckets: [0.0001, 0.001, 0.01, 0.1, 0.5, 1, 10, 100] }, // observe 0.01, use meta to specify bucket options
350-
});
348+
histogram.observe(
349+
0.01,
350+
{ buckets: [0.0001, 0.001, 0.01, 0.1, 0.5, 1, 10, 100] }, // observe 0.01, set buckets
351+
);
351352
```
352353

353354
##### histogram.timer(options)
354355

355356
Method that when called will return an end function for use in measuring the time between 2 points
356357

357-
| name | description | type | default | required |
358-
| --------- | -------------------------------------------------- | -------- | ------- | -------- |
359-
| `options` | Object that can be used to specify labels and meta | `object` | `{}` | `false` |
358+
| name | description | type | default | required |
359+
| --------- | ----------------------------------------------------- | -------- | ------- | -------- |
360+
| `options` | Object that can be used to specify labels and buckets | `object` | `{}` | `false` |
360361

361362
_Examples_
362363

@@ -381,7 +382,9 @@ end({ labels: { url: 'http://finn.no' } }); // set labels in end function
381382
```
382383

383384
```js
384-
const end = histogram.timer(meta: { buckets: [0.0001, 0.001, 0.01, 0.1, 0.5, 1, 10, 100] }); // start timer, set meta
385+
const end = histogram.timer({
386+
buckets: [0.0001, 0.001, 0.01, 0.1, 0.5, 1, 10, 100],
387+
}); // start timer, set buckets
385388
// stuff happens
386389
end();
387390
```
@@ -392,12 +395,12 @@ Creates an instance of a `Summary` class which can be used to populate the metri
392395

393396
**options**
394397

395-
| name | description | type | default | required |
396-
| ------------- | --------------------------------------------- | -------- | ------- | -------- |
397-
| `name` | Metric name. valid characters: a-z,A-Z,0-9,\_ | `string` | null | `true` |
398-
| `description` | Metric description | `string` | null | `true` |
399-
| `meta` | Available to be used to hold any misc data. | `object` | null | `false` |
400-
| `labels` | Available to be used to hold label data. | `object` | null | `false` |
398+
| name | description | type | default | required |
399+
| ------------- | --------------------------------------------- | ---------- | ------- | -------- |
400+
| `name` | Metric name. valid characters: a-z,A-Z,0-9,\_ | `string` | null | `true` |
401+
| `description` | Metric description | `string` | null | `true` |
402+
| `quantiles` | Set custom quantiles | `number[]` | null | `false` |
403+
| `labels` | Available to be used to hold label data. | `object` | null | `false` |
401404

402405
_Example_
403406

@@ -410,10 +413,10 @@ const summary = client.summary(options);
410413

411414
Method that when called will populate the metrics stream with a summary value.
412415

413-
| name | description | type | default | required |
414-
| --------- | -------------------------------------------------- | --------- | ------- | -------- |
415-
| `value` | Value to set the summary to | `integer` | null | `true` |
416-
| `options` | Object that can be used to specify labels and meta | `object` | `{}` | `false` |
416+
| name | description | type | default | required |
417+
| --------- | ------------------------------------------------------- | --------- | ------- | -------- |
418+
| `value` | Value to set the summary to | `integer` | null | `true` |
419+
| `options` | Object that can be used to specify labels and quantiles | `object` | `{}` | `false` |
417420

418421
_Example_
419422

@@ -422,18 +425,19 @@ const summary = client.summary(options);
422425

423426
summary.observe(0.001); // observe value 0.001
424427
summary.observe(5, { labels: { url: 'http://finn.no' } }); // observe value 5, specify labels
425-
summary.observe(0.01, {
426-
meta: { quantiles: [0.001, 0.01, 0.5, 0.9, 0.99] }, // observe 0.01, use meta to specify quantile meta
427-
});
428+
summary.observe(
429+
0.01,
430+
{ quantiles: [0.001, 0.01, 0.5, 0.9, 0.99] }, // observe 0.01, use meta to specify quantile meta
431+
);
428432
```
429433

430434
##### summary.timer(options)
431435

432436
Method that when called will return an end function for use in measuring the time between 2 points
433437

434-
| name | description | type | default | required |
435-
| --------- | -------------------------------------------------- | -------- | ------- | -------- |
436-
| `options` | Object that can be used to specify labels and meta | `object` | `{}` | `false` |
438+
| name | description | type | default | required |
439+
| --------- | ------------------------------------------------------- | -------- | ------- | -------- |
440+
| `options` | Object that can be used to specify labels and quantiles | `object` | `{}` | `false` |
437441

438442
_Examples_
439443

@@ -458,9 +462,7 @@ end({ labels: { url: 'http://finn.no' } }); // set labels in end function
458462
```
459463

460464
```js
461-
const end = summary.timer({
462-
meta: { quantiles: [0.001, 0.01, 0.5, 0.9, 0.99] },
463-
}); // start timer, set meta
465+
const end = summary.timer({ quantiles: [0.001, 0.01, 0.5, 0.9, 0.99] }); // start timer, set meta
464466
// stuff happens
465467
end();
466468
```
@@ -576,7 +578,7 @@ _Example_
576578

577579
```js
578580
const client = new Metrics();
579-
client.on('drop', metric => {
581+
client.on('drop', (metric) => {
580582
console.log('dropped metric', metric);
581583
});
582584
```

‎client.d.ts‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
import { EventEmitter } from 'events';
2+
import { Transform, TransformOptions } from 'readable-stream';
3+
import { MetricOptions } from '@metrics/metric';
4+
5+
interface BaseMetricsOptions {
6+
/**
7+
* Valid characters: `a-zA-Z0-9_`
8+
*/
9+
name: string;
10+
description: string;
11+
labels?: Record<string, string | number | boolean | null>;
12+
}
13+
14+
export interface MetricsCounter extends EventEmitter {
15+
/**
16+
* Increment the counter
17+
*
18+
* @example <caption>Increment by 1</caption>
19+
* counter.inc();
20+
* @example <caption>Increment by 10</caption>
21+
* counter.inc(10);
22+
* @example <caption>Increment by 1 with labels</caption>
23+
* counter.inc({ labels: { url: 'https://www.mysite.com' } });
24+
* @example <caption>Increment by 10 with labels</caption>
25+
* counter.inc(10, { labels: { url: 'https://www.mysite.com' } });
26+
*/
27+
inc(
28+
value?: number | BaseMetricsOptions,
29+
options?: Pick<BaseMetricsOptions, 'labels'>,
30+
): void;
31+
}
32+
33+
export interface MetricsGauge extends EventEmitter {
34+
set(value: number, options?: Pick<BaseMetricsOptions, 'labels'>): void;
35+
}
36+
37+
export interface MetricsHistogramOptions extends BaseMetricsOptions {
38+
buckets?: number[];
39+
}
40+
41+
export type EndTimer = (options?: Pick<BaseMetricsOptions, 'labels'>) => void;
42+
43+
export interface MetricsHistogram extends EventEmitter {
44+
/**
45+
* When called, will popupale the metrics stream with a histogram value.
46+
*
47+
* @param value
48+
* @param options
49+
*/
50+
observe(
51+
value: number,
52+
options?: Pick<MetricsHistogramOptions, 'labels' | 'buckets'>,
53+
): void;
54+
/**
55+
* Measure time between two points.
56+
*
57+
* @example <caption>Measure time between two points</caption>
58+
* const end = histogram.timer();
59+
* // some stuff happens
60+
* end();
61+
* @example <caption>Measure time between two points with labels</caption>
62+
* const end = histogram.timer({ labels: { url: 'https://www.mysite.com' } });
63+
* // some stuff happens
64+
* end();
65+
* @example <caption>Measure time between two points with labels in the end function</caption>
66+
* const end = histogram.timer();
67+
* // some stuff happens
68+
* end({ labels: { url: 'https://www.mysite.com' } });
69+
* @example <caption>Set custom buckets</caption>
70+
* const end = histogram.timer({ buckets: [0.1, 0.5, 1, 2, 5] });
71+
* // some stuff happens
72+
* end();
73+
*/
74+
timer(
75+
options?: Pick<MetricsHistogramOptions, 'labels' | 'buckets'>,
76+
): EndTimer;
77+
}
78+
79+
export interface MetricsSummaryOptions extends BaseMetricsOptions {
80+
quantiles?: number[];
81+
}
82+
83+
export interface MetricsSummary extends EventEmitter {
84+
/**
85+
* When called, will popupale the metrics stream with a histogram value.
86+
*
87+
* @param value
88+
* @param options
89+
*/
90+
observe(
91+
value: number,
92+
options?: Pick<MetricsSummaryOptions, 'labels' | 'quantiles'>,
93+
): void;
94+
/**
95+
* Measure time between two points.
96+
*
97+
* @example <caption>Measure time between two points</caption>
98+
* const end = summary.timer();
99+
* // some stuff happens
100+
* end();
101+
* @example <caption>Measure time between two points with labels</caption>
102+
* const end = summary.timer({ labels: { url: 'https://www.mysite.com' } });
103+
* // some stuff happens
104+
* end();
105+
* @example <caption>Measure time between two points with labels in the end function</caption>
106+
* const end = summary.timer();
107+
* // some stuff happens
108+
* end({ labels: { url: 'https://www.mysite.com' } });
109+
* @example <caption>Set custom buckets</caption>
110+
* const end = summary.timer({ quantiles: [0.001, 0.01, 0.5, 0.9, 0.99] });
111+
* // some stuff happens
112+
* end();
113+
*/
114+
timer(
115+
options?: Pick<MetricsSummaryOptions, 'labels' | 'quantiles'>,
116+
): EndTimer;
117+
}
118+
119+
export interface MetricsClientOptions extends TransformOptions {
120+
/**
121+
* An optional unique identifier of the MetricsClient instance.
122+
* A random ID will be generated if not provided.
123+
*/
124+
id?: string;
125+
}
126+
127+
export default class MetricsClient extends Transform {
128+
constructor(options?: MetricsClientOptions);
129+
130+
counter(options: BaseMetricsOptions): MetricsCounter;
131+
gauge(options: BaseMetricsOptions): MetricsGauge;
132+
histogram(options: MetricsHistogramOptions): MetricsHistogram;
133+
summary(options: BaseMetricsOptions): MetricsHistogram;
134+
metric(options: MetricOptions): void;
135+
timer(options: MetricOptions): (options?: Partial<MetricOptions>) => void;
136+
}

‎package.json‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
{
22
"name": "@metrics/client",
3-
"version": "2.5.0",
3+
"version": "2.5.1",
44
"description": "A streaming metric producer. Allows producing counters, gauges, histograms and summaries in a way that is independent of your metrics system.",
55
"main": "lib/client.js",
6+
"types": "client.d.ts",
67
"files": [
7-
"lib"
8+
"lib",
9+
"client.d.ts"
810
],
911
"scripts": {
1012
"bench": "node benchmark/benchmark.js",

0 commit comments

Comments
 (0)