@pawells/nestjs-prometheus 1.0.0-dev.3052c75
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +290 -0
- package/build/LICENSE +21 -0
- package/build/README.md +290 -0
- package/build/controllers/metrics.controller.d.ts +84 -0
- package/build/controllers/metrics.controller.d.ts.map +1 -0
- package/build/controllers/metrics.controller.js +117 -0
- package/build/controllers/metrics.controller.js.map +1 -0
- package/build/index.d.ts +23 -0
- package/build/index.d.ts.map +1 -0
- package/build/index.js +23 -0
- package/build/index.js.map +1 -0
- package/build/package.json +63 -0
- package/build/prometheus.exporter.d.ts +187 -0
- package/build/prometheus.exporter.d.ts.map +1 -0
- package/build/prometheus.exporter.js +380 -0
- package/build/prometheus.exporter.js.map +1 -0
- package/build/prometheus.module.d.ts +89 -0
- package/build/prometheus.module.d.ts.map +1 -0
- package/build/prometheus.module.js +122 -0
- package/build/prometheus.module.js.map +1 -0
- package/build/test-setup.d.ts +2 -0
- package/build/test-setup.d.ts.map +1 -0
- package/build/test-setup.js +4 -0
- package/build/test-setup.js.map +1 -0
- package/package.json +80 -0
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import { Response } from 'express';
|
|
2
|
+
import { PrometheusExporter } from '../prometheus.exporter.js';
|
|
3
|
+
/**
|
|
4
|
+
* Metrics HTTP controller
|
|
5
|
+
*
|
|
6
|
+
* Exposes a `/metrics` endpoint that returns metrics in Prometheus text format
|
|
7
|
+
* (version 0.0.4). This endpoint is typically scraped by Prometheus servers
|
|
8
|
+
* or other monitoring systems.
|
|
9
|
+
*
|
|
10
|
+
* Endpoint: `GET /metrics`
|
|
11
|
+
*
|
|
12
|
+
* Response Headers:
|
|
13
|
+
* - `Content-Type: text/plain; version=0.0.4; charset=utf-8`
|
|
14
|
+
* - `X-Robots-Tag: noindex, nofollow` — prevents search engine indexing
|
|
15
|
+
*
|
|
16
|
+
* Security:
|
|
17
|
+
* - Protected by MetricsGuard from @pawells/nestjs-shared
|
|
18
|
+
* - Respects optional METRICS_API_KEY environment variable
|
|
19
|
+
* - No auth required if METRICS_API_KEY is not set
|
|
20
|
+
*
|
|
21
|
+
* @example
|
|
22
|
+
* ```
|
|
23
|
+
* GET /metrics
|
|
24
|
+
*
|
|
25
|
+
* Response:
|
|
26
|
+
* 200 OK
|
|
27
|
+
* Content-Type: text/plain; version=0.0.4; charset=utf-8
|
|
28
|
+
* X-Robots-Tag: noindex, nofollow
|
|
29
|
+
*
|
|
30
|
+
* # HELP http_request_duration_seconds Duration of HTTP requests in seconds
|
|
31
|
+
* # TYPE http_request_duration_seconds histogram
|
|
32
|
+
* http_request_duration_seconds_bucket{le="0.001",...} 0
|
|
33
|
+
* ...
|
|
34
|
+
* ```
|
|
35
|
+
*/
|
|
36
|
+
export declare class MetricsController {
|
|
37
|
+
private readonly exporter;
|
|
38
|
+
constructor(exporter: PrometheusExporter);
|
|
39
|
+
/**
|
|
40
|
+
* Get all metrics in Prometheus text format
|
|
41
|
+
*
|
|
42
|
+
* Returns the current state of all metrics in Prometheus text format (version 0.0.4).
|
|
43
|
+
* Metrics include:
|
|
44
|
+
* - Node.js default metrics (process CPU, memory, event loop, GC, file descriptors)
|
|
45
|
+
* - Custom metrics registered with InstrumentationRegistry
|
|
46
|
+
*
|
|
47
|
+
* Process:
|
|
48
|
+
* 1. MetricsGuard checks METRICS_API_KEY if configured
|
|
49
|
+
* 2. PrometheusExporter.getMetrics() is called to flush pending values and retrieve metrics
|
|
50
|
+
* 3. Response is sent with Prometheus text format (version 0.0.4)
|
|
51
|
+
*
|
|
52
|
+
* Authentication (via MetricsGuard):
|
|
53
|
+
* - If METRICS_API_KEY is set: requires Bearer token, X-API-Key header, or ?key= query param
|
|
54
|
+
* - If METRICS_API_KEY is not set: all requests are allowed
|
|
55
|
+
*
|
|
56
|
+
* Response Headers:
|
|
57
|
+
* - Content-Type: text/plain; version=0.0.4; charset=utf-8
|
|
58
|
+
* - X-Robots-Tag: noindex, nofollow
|
|
59
|
+
*
|
|
60
|
+
* @param response - Express response object
|
|
61
|
+
* @returns Promise that resolves when response is sent
|
|
62
|
+
*
|
|
63
|
+
* @example
|
|
64
|
+
* ```
|
|
65
|
+
* GET /metrics HTTP/1.1
|
|
66
|
+
* Authorization: Bearer secret-api-key
|
|
67
|
+
*
|
|
68
|
+
* HTTP/1.1 200 OK
|
|
69
|
+
* Content-Type: text/plain; version=0.0.4; charset=utf-8
|
|
70
|
+
* X-Robots-Tag: noindex, nofollow
|
|
71
|
+
*
|
|
72
|
+
* # HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.
|
|
73
|
+
* # TYPE process_cpu_user_seconds_total counter
|
|
74
|
+
* process_cpu_user_seconds_total 0.123456
|
|
75
|
+
*
|
|
76
|
+
* # HELP process_resident_memory_bytes Resident memory size in bytes.
|
|
77
|
+
* # TYPE process_resident_memory_bytes gauge
|
|
78
|
+
* process_resident_memory_bytes 52428800
|
|
79
|
+
* ...
|
|
80
|
+
* ```
|
|
81
|
+
*/
|
|
82
|
+
getMetrics(response: Response): Promise<void>;
|
|
83
|
+
}
|
|
84
|
+
//# sourceMappingURL=metrics.controller.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"metrics.controller.d.ts","sourceRoot":"","sources":["../../src/controllers/metrics.controller.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBACa,iBAAiB;IAE5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,kBAAkB;IAG9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IAKU,UAAU,CAAQ,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAIjE"}
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
|
|
2
|
+
var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
|
|
3
|
+
if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
|
|
4
|
+
else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
|
|
5
|
+
return c > 3 && r && Object.defineProperty(target, key, r), r;
|
|
6
|
+
};
|
|
7
|
+
var __metadata = (this && this.__metadata) || function (k, v) {
|
|
8
|
+
if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
|
|
9
|
+
};
|
|
10
|
+
var __param = (this && this.__param) || function (paramIndex, decorator) {
|
|
11
|
+
return function (target, key) { decorator(target, key, paramIndex); }
|
|
12
|
+
};
|
|
13
|
+
import { Controller, Get, Header, Res, UseGuards } from '@nestjs/common';
|
|
14
|
+
import { MetricsGuard } from '@pawells/nestjs-shared';
|
|
15
|
+
import { PrometheusExporter } from '../prometheus.exporter.js';
|
|
16
|
+
/**
|
|
17
|
+
* Metrics HTTP controller
|
|
18
|
+
*
|
|
19
|
+
* Exposes a `/metrics` endpoint that returns metrics in Prometheus text format
|
|
20
|
+
* (version 0.0.4). This endpoint is typically scraped by Prometheus servers
|
|
21
|
+
* or other monitoring systems.
|
|
22
|
+
*
|
|
23
|
+
* Endpoint: `GET /metrics`
|
|
24
|
+
*
|
|
25
|
+
* Response Headers:
|
|
26
|
+
* - `Content-Type: text/plain; version=0.0.4; charset=utf-8`
|
|
27
|
+
* - `X-Robots-Tag: noindex, nofollow` — prevents search engine indexing
|
|
28
|
+
*
|
|
29
|
+
* Security:
|
|
30
|
+
* - Protected by MetricsGuard from @pawells/nestjs-shared
|
|
31
|
+
* - Respects optional METRICS_API_KEY environment variable
|
|
32
|
+
* - No auth required if METRICS_API_KEY is not set
|
|
33
|
+
*
|
|
34
|
+
* @example
|
|
35
|
+
* ```
|
|
36
|
+
* GET /metrics
|
|
37
|
+
*
|
|
38
|
+
* Response:
|
|
39
|
+
* 200 OK
|
|
40
|
+
* Content-Type: text/plain; version=0.0.4; charset=utf-8
|
|
41
|
+
* X-Robots-Tag: noindex, nofollow
|
|
42
|
+
*
|
|
43
|
+
* # HELP http_request_duration_seconds Duration of HTTP requests in seconds
|
|
44
|
+
* # TYPE http_request_duration_seconds histogram
|
|
45
|
+
* http_request_duration_seconds_bucket{le="0.001",...} 0
|
|
46
|
+
* ...
|
|
47
|
+
* ```
|
|
48
|
+
*/
|
|
49
|
+
let MetricsController = class MetricsController {
|
|
50
|
+
exporter;
|
|
51
|
+
constructor(exporter) {
|
|
52
|
+
this.exporter = exporter;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Get all metrics in Prometheus text format
|
|
56
|
+
*
|
|
57
|
+
* Returns the current state of all metrics in Prometheus text format (version 0.0.4).
|
|
58
|
+
* Metrics include:
|
|
59
|
+
* - Node.js default metrics (process CPU, memory, event loop, GC, file descriptors)
|
|
60
|
+
* - Custom metrics registered with InstrumentationRegistry
|
|
61
|
+
*
|
|
62
|
+
* Process:
|
|
63
|
+
* 1. MetricsGuard checks METRICS_API_KEY if configured
|
|
64
|
+
* 2. PrometheusExporter.getMetrics() is called to flush pending values and retrieve metrics
|
|
65
|
+
* 3. Response is sent with Prometheus text format (version 0.0.4)
|
|
66
|
+
*
|
|
67
|
+
* Authentication (via MetricsGuard):
|
|
68
|
+
* - If METRICS_API_KEY is set: requires Bearer token, X-API-Key header, or ?key= query param
|
|
69
|
+
* - If METRICS_API_KEY is not set: all requests are allowed
|
|
70
|
+
*
|
|
71
|
+
* Response Headers:
|
|
72
|
+
* - Content-Type: text/plain; version=0.0.4; charset=utf-8
|
|
73
|
+
* - X-Robots-Tag: noindex, nofollow
|
|
74
|
+
*
|
|
75
|
+
* @param response - Express response object
|
|
76
|
+
* @returns Promise that resolves when response is sent
|
|
77
|
+
*
|
|
78
|
+
* @example
|
|
79
|
+
* ```
|
|
80
|
+
* GET /metrics HTTP/1.1
|
|
81
|
+
* Authorization: Bearer secret-api-key
|
|
82
|
+
*
|
|
83
|
+
* HTTP/1.1 200 OK
|
|
84
|
+
* Content-Type: text/plain; version=0.0.4; charset=utf-8
|
|
85
|
+
* X-Robots-Tag: noindex, nofollow
|
|
86
|
+
*
|
|
87
|
+
* # HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.
|
|
88
|
+
* # TYPE process_cpu_user_seconds_total counter
|
|
89
|
+
* process_cpu_user_seconds_total 0.123456
|
|
90
|
+
*
|
|
91
|
+
* # HELP process_resident_memory_bytes Resident memory size in bytes.
|
|
92
|
+
* # TYPE process_resident_memory_bytes gauge
|
|
93
|
+
* process_resident_memory_bytes 52428800
|
|
94
|
+
* ...
|
|
95
|
+
* ```
|
|
96
|
+
*/
|
|
97
|
+
async getMetrics(response) {
|
|
98
|
+
const metrics = await this.exporter.getMetrics();
|
|
99
|
+
response.send(metrics);
|
|
100
|
+
}
|
|
101
|
+
};
|
|
102
|
+
__decorate([
|
|
103
|
+
Get('metrics'),
|
|
104
|
+
UseGuards(MetricsGuard),
|
|
105
|
+
Header('Content-Type', 'text/plain; version=0.0.4; charset=utf-8'),
|
|
106
|
+
Header('X-Robots-Tag', 'noindex, nofollow'),
|
|
107
|
+
__param(0, Res()),
|
|
108
|
+
__metadata("design:type", Function),
|
|
109
|
+
__metadata("design:paramtypes", [Object]),
|
|
110
|
+
__metadata("design:returntype", Promise)
|
|
111
|
+
], MetricsController.prototype, "getMetrics", null);
|
|
112
|
+
MetricsController = __decorate([
|
|
113
|
+
Controller(),
|
|
114
|
+
__metadata("design:paramtypes", [PrometheusExporter])
|
|
115
|
+
], MetricsController);
|
|
116
|
+
export { MetricsController };
|
|
117
|
+
//# sourceMappingURL=metrics.controller.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"metrics.controller.js","sourceRoot":"","sources":["../../src/controllers/metrics.controller.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEzE,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEI,IAAM,iBAAiB,GAAvB,MAAM,iBAAiB;IAEX;IADlB,YACkB,QAA4B;QAA5B,aAAQ,GAAR,QAAQ,CAAoB;IAC3C,CAAC;IAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IAKU,AAAN,KAAK,CAAC,UAAU,CAAQ,QAAkB;QAChD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;QACjD,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;CACD,CAAA;AAJa;IAJZ,GAAG,CAAC,SAAS,CAAC;IACd,SAAS,CAAC,YAAY,CAAC;IACvB,MAAM,CAAC,cAAc,EAAE,0CAA0C,CAAC;IAClE,MAAM,CAAC,cAAc,EAAE,mBAAmB,CAAC;IACnB,WAAA,GAAG,EAAE,CAAA;;;;mDAG7B;AAvDW,iBAAiB;IAD7B,UAAU,EAAE;qCAGgB,kBAAkB;GAFlC,iBAAiB,CAwD7B"}
|
package/build/index.d.ts
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @pawells/nestjs-prometheus — Prometheus metrics exporter for NestJS
|
|
3
|
+
*
|
|
4
|
+
* Integrates with @pawells/nestjs-shared InstrumentationRegistry to export metrics
|
|
5
|
+
* in Prometheus text format via a GET /metrics endpoint.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```typescript
|
|
9
|
+
* import { PrometheusModule } from '@pawells/nestjs-prometheus';
|
|
10
|
+
*
|
|
11
|
+
* @Module({
|
|
12
|
+
* imports: [PrometheusModule.forRoot()],
|
|
13
|
+
* })
|
|
14
|
+
* export class AppModule {}
|
|
15
|
+
* // Metrics are now available at: GET /metrics
|
|
16
|
+
* ```
|
|
17
|
+
*
|
|
18
|
+
* @packageDocumentation
|
|
19
|
+
*/
|
|
20
|
+
export { PrometheusExporter } from './prometheus.exporter.js';
|
|
21
|
+
export { PrometheusModule } from './prometheus.module.js';
|
|
22
|
+
export { MetricsController } from './controllers/metrics.controller.js';
|
|
23
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC"}
|
package/build/index.js
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @pawells/nestjs-prometheus — Prometheus metrics exporter for NestJS
|
|
3
|
+
*
|
|
4
|
+
* Integrates with @pawells/nestjs-shared InstrumentationRegistry to export metrics
|
|
5
|
+
* in Prometheus text format via a GET /metrics endpoint.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```typescript
|
|
9
|
+
* import { PrometheusModule } from '@pawells/nestjs-prometheus';
|
|
10
|
+
*
|
|
11
|
+
* @Module({
|
|
12
|
+
* imports: [PrometheusModule.forRoot()],
|
|
13
|
+
* })
|
|
14
|
+
* export class AppModule {}
|
|
15
|
+
* // Metrics are now available at: GET /metrics
|
|
16
|
+
* ```
|
|
17
|
+
*
|
|
18
|
+
* @packageDocumentation
|
|
19
|
+
*/
|
|
20
|
+
export { PrometheusExporter } from './prometheus.exporter.js';
|
|
21
|
+
export { PrometheusModule } from './prometheus.module.js';
|
|
22
|
+
export { MetricsController } from './controllers/metrics.controller.js';
|
|
23
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC"}
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@pawells/nestjs-prometheus",
|
|
3
|
+
"displayName": "@pawells/nestjs-prometheus",
|
|
4
|
+
"version": "1.0.0-dev.3052c75",
|
|
5
|
+
"description": "NestJS Prometheus metrics module with endpoint controller",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"main": "./build/index.js",
|
|
8
|
+
"types": "./build/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./build/index.d.ts",
|
|
12
|
+
"import": "./build/index.js"
|
|
13
|
+
}
|
|
14
|
+
},
|
|
15
|
+
"scripts": {
|
|
16
|
+
"build": "tsc --project tsconfig.build.json",
|
|
17
|
+
"typecheck": "tsc --noEmit",
|
|
18
|
+
"lint": "eslint src/",
|
|
19
|
+
"lint:fix": "eslint src/ --fix",
|
|
20
|
+
"test": "vitest run",
|
|
21
|
+
"test:coverage": "vitest --coverage",
|
|
22
|
+
"pipeline": "yarn typecheck && yarn lint && yarn test && yarn build"
|
|
23
|
+
},
|
|
24
|
+
"peerDependencies": {
|
|
25
|
+
"@nestjs/common": ">=10.0.0",
|
|
26
|
+
"@nestjs/config": ">=3.0.0",
|
|
27
|
+
"@nestjs/core": ">=10.0.0",
|
|
28
|
+
"@nestjs/throttler": ">=5.0.0",
|
|
29
|
+
"@opentelemetry/api": ">=1.0.0",
|
|
30
|
+
"class-transformer": ">=0.5.0",
|
|
31
|
+
"class-validator": ">=0.14.0",
|
|
32
|
+
"compression": ">=1.0.0",
|
|
33
|
+
"csrf-csrf": ">=3.0.0",
|
|
34
|
+
"express": ">=4.0.0",
|
|
35
|
+
"helmet": ">=7.0.0",
|
|
36
|
+
"joi": ">=17.0.0",
|
|
37
|
+
"prom-client": ">=15.0.0",
|
|
38
|
+
"rxjs": ">=7.0.0",
|
|
39
|
+
"xss": ">=1.0.0"
|
|
40
|
+
},
|
|
41
|
+
"dependencies": {
|
|
42
|
+
"@pawells/nestjs-shared": "^1.0.0"
|
|
43
|
+
},
|
|
44
|
+
"engines": {
|
|
45
|
+
"node": ">=22.0.0"
|
|
46
|
+
},
|
|
47
|
+
"packageManager": "yarn@4.12.0",
|
|
48
|
+
"author": "Aaron Wells <69355326+PhillipAWells@users.noreply.github.com>",
|
|
49
|
+
"license": "MIT",
|
|
50
|
+
"repository": {
|
|
51
|
+
"type": "git",
|
|
52
|
+
"url": "https://github.com/PhillipAWells/nestjs-common"
|
|
53
|
+
},
|
|
54
|
+
"files": [
|
|
55
|
+
"build/",
|
|
56
|
+
"README.md",
|
|
57
|
+
"LICENSE"
|
|
58
|
+
],
|
|
59
|
+
"publishConfig": {
|
|
60
|
+
"access": "public"
|
|
61
|
+
},
|
|
62
|
+
"module": "./index.js"
|
|
63
|
+
}
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
import type { IMetricsExporter, MetricDescriptor, MetricValue } from '@pawells/nestjs-shared';
|
|
2
|
+
/**
|
|
3
|
+
* Prometheus metrics exporter implementation
|
|
4
|
+
*
|
|
5
|
+
* Implements the IMetricsExporter interface for Prometheus pull-based metrics collection.
|
|
6
|
+
* Uses prom-client library to manage Prometheus instruments (Counter, Gauge, Histogram)
|
|
7
|
+
* and exports metrics in Prometheus text format on demand.
|
|
8
|
+
*
|
|
9
|
+
* Architecture:
|
|
10
|
+
* - **Event-based buffering**: Metric values are buffered as they are recorded
|
|
11
|
+
* - **Pull-based export**: Flushes all pending values when `/metrics` endpoint is scraped
|
|
12
|
+
* - **Atomic swaps**: Uses atomic array swaps during flush to prevent concurrent data loss
|
|
13
|
+
* - **Bounded memory**: Limits pending values to 1000 per metric to prevent unbounded growth
|
|
14
|
+
* - **Node.js defaults**: Automatically collects Node.js process metrics (CPU, memory, GC, etc.)
|
|
15
|
+
*
|
|
16
|
+
* Type mapping:
|
|
17
|
+
* - `counter` → prom-client Counter (monotonically increasing)
|
|
18
|
+
* - `gauge` → prom-client Gauge (point-in-time value)
|
|
19
|
+
* - `updown_counter` → prom-client Gauge (can increase or decrease)
|
|
20
|
+
* - `histogram` → prom-client Histogram (distribution with buckets)
|
|
21
|
+
*
|
|
22
|
+
* @example
|
|
23
|
+
* ```typescript
|
|
24
|
+
* const exporter = new PrometheusExporter();
|
|
25
|
+
* registry.registerExporter(exporter);
|
|
26
|
+
*
|
|
27
|
+
* // Later, get metrics for Prometheus scrape endpoint
|
|
28
|
+
* const prometheusMetrics = await exporter.getMetrics();
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
31
|
+
export declare class PrometheusExporter implements IMetricsExporter {
|
|
32
|
+
/**
|
|
33
|
+
* This exporter buffers metric values as they are recorded and flushes
|
|
34
|
+
* them into prom-client instruments on each pull (getMetrics)
|
|
35
|
+
*/
|
|
36
|
+
readonly supportsEventBased = true;
|
|
37
|
+
/**
|
|
38
|
+
* This exporter supports pull-based metric retrieval
|
|
39
|
+
*/
|
|
40
|
+
readonly supportsPull = true;
|
|
41
|
+
/**
|
|
42
|
+
* Prom-client Registry instance for managing instruments
|
|
43
|
+
* @private
|
|
44
|
+
*/
|
|
45
|
+
private readonly registry;
|
|
46
|
+
/**
|
|
47
|
+
* Cache of created prom-client instruments (Counter, Histogram, Gauge)
|
|
48
|
+
* Keyed by metric name
|
|
49
|
+
* @private
|
|
50
|
+
*/
|
|
51
|
+
private readonly instruments;
|
|
52
|
+
/**
|
|
53
|
+
* Pending metric values to be flushed into prom-client instruments on next getMetrics()
|
|
54
|
+
* Keyed by metric name
|
|
55
|
+
* @private
|
|
56
|
+
*/
|
|
57
|
+
private readonly pending;
|
|
58
|
+
/**
|
|
59
|
+
* Running totals for updown_counter metrics (persistent across scrapes)
|
|
60
|
+
* Keyed by metric name, then by normalized label key
|
|
61
|
+
* @private
|
|
62
|
+
*/
|
|
63
|
+
private readonly gaugeValues;
|
|
64
|
+
/**
|
|
65
|
+
* Maximum number of pending metric values per metric before culling oldest entries
|
|
66
|
+
* Prevents unbounded memory growth if metrics are recorded much faster than pulled
|
|
67
|
+
* @private
|
|
68
|
+
*/
|
|
69
|
+
private static readonly MAX_PENDING_PER_METRIC;
|
|
70
|
+
/**
|
|
71
|
+
* Logger instance for warnings and errors
|
|
72
|
+
*/
|
|
73
|
+
private readonly logger;
|
|
74
|
+
/**
|
|
75
|
+
* Normalize label keys to handle consistent ordering regardless of insertion order
|
|
76
|
+
* @private
|
|
77
|
+
*/
|
|
78
|
+
private static normalizeLabelKey;
|
|
79
|
+
/**
|
|
80
|
+
* Create a new PrometheusExporter instance
|
|
81
|
+
*
|
|
82
|
+
* Initializes a prom-client Registry and starts collecting Node.js default metrics
|
|
83
|
+
* (process CPU, memory, event loop, garbage collection, etc.).
|
|
84
|
+
*/
|
|
85
|
+
constructor();
|
|
86
|
+
/**
|
|
87
|
+
* Called when a metric descriptor is registered in InstrumentationRegistry
|
|
88
|
+
*
|
|
89
|
+
* Pre-creates the corresponding prom-client instrument (Counter, Gauge, or Histogram)
|
|
90
|
+
* based on the descriptor's type. The created instrument is cached for future use.
|
|
91
|
+
* Initializes an empty pending array for the metric to buffer future recorded values.
|
|
92
|
+
*
|
|
93
|
+
* Type mapping:
|
|
94
|
+
* - `counter` → Counter (incremented by value via inc())
|
|
95
|
+
* - `histogram` → Histogram (observed via observe())
|
|
96
|
+
* - `gauge` or `updown_counter` → Gauge (set via set())
|
|
97
|
+
*
|
|
98
|
+
* @param descriptor - The metric descriptor being registered
|
|
99
|
+
* @throws Error if descriptor type is not supported
|
|
100
|
+
*
|
|
101
|
+
* @example
|
|
102
|
+
* ```typescript
|
|
103
|
+
* exporter.onDescriptorRegistered({
|
|
104
|
+
* name: 'http_request_duration_seconds',
|
|
105
|
+
* type: 'histogram',
|
|
106
|
+
* help: 'Request duration in seconds',
|
|
107
|
+
* labelNames: ['method', 'route', 'status_code'],
|
|
108
|
+
* buckets: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1],
|
|
109
|
+
* });
|
|
110
|
+
* ```
|
|
111
|
+
*/
|
|
112
|
+
onDescriptorRegistered(descriptor: MetricDescriptor): void;
|
|
113
|
+
/**
|
|
114
|
+
* Buffer a metric value to be flushed on next getMetrics() call
|
|
115
|
+
*
|
|
116
|
+
* Values are buffered rather than immediately recorded into prom-client.
|
|
117
|
+
* They are applied to the appropriate instrument during the next pull (getMetrics) call.
|
|
118
|
+
*
|
|
119
|
+
* Buffering behavior:
|
|
120
|
+
* - Values are appended to the pending array for the metric
|
|
121
|
+
* - If the pending array exceeds MAX_PENDING_PER_METRIC (1000), oldest entries are culled
|
|
122
|
+
* - If the metric descriptor was not registered first, a warning is logged and value is dropped
|
|
123
|
+
*
|
|
124
|
+
* @param value - The metric value to buffer
|
|
125
|
+
*
|
|
126
|
+
* @example
|
|
127
|
+
* ```typescript
|
|
128
|
+
* exporter.onMetricRecorded({
|
|
129
|
+
* descriptor: { name: 'http_request_duration_seconds' },
|
|
130
|
+
* value: 0.125,
|
|
131
|
+
* labels: { method: 'GET', status_code: '200' },
|
|
132
|
+
* timestamp: performance.now(),
|
|
133
|
+
* });
|
|
134
|
+
* ```
|
|
135
|
+
*/
|
|
136
|
+
onMetricRecorded(value: MetricValue): void;
|
|
137
|
+
/**
|
|
138
|
+
* Retrieve all metrics in Prometheus text format
|
|
139
|
+
*
|
|
140
|
+
* Flushes all pending metric values into prom-client instruments, then returns
|
|
141
|
+
* the complete metrics output in Prometheus text format (version 0.0.4).
|
|
142
|
+
*
|
|
143
|
+
* Flush process:
|
|
144
|
+
* 1. For each metric, atomically swap the pending array with a fresh empty array
|
|
145
|
+
* 2. Apply all pending values to the corresponding instrument:
|
|
146
|
+
* - Counter: increment by value
|
|
147
|
+
* - Histogram: observe value
|
|
148
|
+
* - Gauge: set to value
|
|
149
|
+
* 3. Skip any values where the instrument was not pre-created (shouldn't happen)
|
|
150
|
+
* 4. Return the serialized metrics from the registry
|
|
151
|
+
*
|
|
152
|
+
* Includes Node.js default metrics and all custom metrics registered with descriptors.
|
|
153
|
+
*
|
|
154
|
+
* @returns Promise resolving to metrics in Prometheus text format (version 0.0.4)
|
|
155
|
+
* @throws Error if metrics generation fails (logged but re-thrown)
|
|
156
|
+
*
|
|
157
|
+
* @example
|
|
158
|
+
* ```typescript
|
|
159
|
+
* const prometheusMetrics = await exporter.getMetrics();
|
|
160
|
+
* // Returns:
|
|
161
|
+
* // # HELP http_request_duration_seconds Duration of HTTP requests in seconds
|
|
162
|
+
* // # TYPE http_request_duration_seconds histogram
|
|
163
|
+
* // http_request_duration_seconds_bucket{le="0.001",...} 0
|
|
164
|
+
* // http_request_duration_seconds_bucket{le="0.01",...} 5
|
|
165
|
+
* ```
|
|
166
|
+
*/
|
|
167
|
+
getMetrics(): Promise<string>;
|
|
168
|
+
/**
|
|
169
|
+
* Shutdown the exporter and clean up resources
|
|
170
|
+
*
|
|
171
|
+
* Clears the prom-client registry and releases all internal state:
|
|
172
|
+
* - registry.clear() — removes all instruments
|
|
173
|
+
* - instruments.clear() — removes cached instrument references
|
|
174
|
+
* - pending.clear() — discards any buffered but unflushed metric values
|
|
175
|
+
*
|
|
176
|
+
* Called by PrometheusModule during application shutdown (onApplicationShutdown).
|
|
177
|
+
*
|
|
178
|
+
* @returns Promise that resolves when shutdown is complete
|
|
179
|
+
*
|
|
180
|
+
* @example
|
|
181
|
+
* ```typescript
|
|
182
|
+
* await exporter.shutdown();
|
|
183
|
+
* ```
|
|
184
|
+
*/
|
|
185
|
+
shutdown(): Promise<void>;
|
|
186
|
+
}
|
|
187
|
+
//# sourceMappingURL=prometheus.exporter.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"prometheus.exporter.d.ts","sourceRoot":"","sources":["../src/prometheus.exporter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBACa,kBAAmB,YAAW,gBAAgB;IAC1D;;;OAGG;IACH,SAAgB,kBAAkB,QAAQ;IAE1C;;OAEG;IACH,SAAgB,YAAY,QAAQ;IAEpC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IAEpC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmE;IAE/F;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmC;IAE/D;;;;OAIG;IAEH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAQ;IAEtD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IAEnC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAKhC;;;;;OAKG;;IAYH;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACI,sBAAsB,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAgEjE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACI,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAiBjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACU,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAqG1C;;;;;;;;;;;;;;;;OAgBG;IAEU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAMtC"}
|