A prometheus module for Nest.
BREAKING CHANGE
nestjs-prom v0.2.x has been moved to stable/0.2 branch.
To migrate from v0.2 to v1.x please see Migrate from 0.2.x to 1.x
$ npm install --save @digikare/nestjs-prom prom-client
Import PromModule
into the root ApplicationModule
import { Module } from '@nestjs/common';
import { PromModule } from '@digikare/nestjs-prom';
@Module({
imports: [
PromModule.forRoot({
defaultLabels: {
app: 'my_app',
version: 'x.y.z',
}
}),
]
})
export class ApplicationModule {}
Here the options available for PromModule.forRoot:
key | type | default | details |
---|---|---|---|
defaultLabels | object | {} |
The defaults labels to apply on every counter |
useHttpCounterMiddleware | boolean | true |
Create automatically http_requests_total counter |
withDefaultController | boolean | true |
Enable default controller to handle /metrics endpoint |
withDefaultsMetrics | boolean | true |
Enable defaults metrics for nodejs (call collectDefaultMetrics() ) |
withGlobalInterceptor | boolean | true |
Enable interceptor to catch uncatched exception thrown by your app on an endpoint |
To setup a metric, the module provide multiple ways to get a metric.
By using PromService
service with DI to get a metric.
@Injectable()
export class MyService {
private readonly _counter: CounterMetric;
private readonly _gauge: GaugeMetric,
private readonly _histogram: HistogramMetric,
private readonly _summary: SummaryMetric,
constructor(
private readonly promService: PromService,
) {
this._counter = this.promService.getCounter({ name: 'my_counter' });
}
doSomething() {
this._counter.inc(1);
}
reset() {
this._counter.reset();
}
}
You have the following decorators:
@PromCounter()
@PromGauge()
@PromHistogram()
@PromSummary()
Below how to use it
import { CounterMetric, PromCounter } from '@digikare/nest-prom';
@Controller()
export class AppController {
@Get('/home')
home(
@PromCounter('app_counter_1_inc') counter1: CounterMetric,
@PromCounter({ name: 'app_counter_2_inc', help: 'app_counter_2_help' }) counter2: CounterMetric,
) {
counter1.inc(1);
counter2.inc(2);
}
@Get('/home2')
home2(
@PromCounter({ name: 'app_counter_2_inc', help: 'app_counter_2_help' }) counter: CounterMetric,
) {
counter.inc(2);
}
}
If you want to counthow many instance of a specific class has been created:
@PromInstanceCounter()
export class MyClass {
}
Will generate a counter called: app_MyClass_instances_total
If you want to increment a counter on each call of a specific method:
@Injectable()
export class MyService {
@PromMethodCounter()
doMyStuff() {
}
}
Will generate a counter called: app_MyService_doMyStuff_calls_total
and auto increment on each call
You can use that to monitor an endpoint
@Controller()
export class AppController {
@Get()
@PromMethodCounter() // will generate `app_AppController_root_calls_total` counter
root() {
// do your stuff
}
@Get('/login')
@PromMethodCounter({ name: 'app_login_endpoint_counter' }) // set the counter name
login() {
// do your stuff
}
}
The default metrics endpoint is /metrics
this can be changed with the customUrl option
@Module({
imports: [
PromModule.forRoot({
defaultLabels: {
app: 'my_app',
},
customUrl: 'custom/uri',
}),
],
})
export class MyModule
Now your metrics can be found at /custom/uri
.
PS: If you have a global prefix, the path will be
{globalPrefix}/metrics
for the moment.
withDefaultsMetrics: boolean (default true)
enable defaultMetrics provided by prom-clientwithDefaultController: boolean (default true)
add internal controller to expose /metrics endpointsuseHttpCounterMiddleware: boolean (default false)
register http_requests_total counter
@PromInstanceCounter()
Class decorator, create and increment on each instance created@PromMethodCounter()
Method decorator, create and increment each time the method is called@PromCounter()
Param decorator, create/find counter metric@PromGauge()
Param decorator, create/find gauge metric@PromHistogram()
Param decorator, create/find histogram metric@PromSummary()
Param decorator, create/find summary metric
I do not provide any auth/security for /metrics
endpoints.
This is not the aim of this module, but depending of the auth strategy, you can
apply a middleware on /metrics
to secure it.
- Update readme
- Gauge
- Histogram
- Summary
- Manage registries
- Adding example on how to secure
/metrics
endpoint- secret
- jwt
MIT licensed