@khaledez/nestjs-prom
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    nestjs-prom v1.x

    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

    Installation

    $ npm install --save @digikare/nestjs-prom prom-client

    How to use

    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 {}

    PromModule.forRoot options

    Here the options available for PromModule.forRoot:

    Option Type Default Description
    defaultLabels Object<string, string number> {}
    metricPath string /metrics Path to use to service metrics
    withDefaultsMetrics boolean true enable defaultMetrics provided by prom-client
    withDefaultController boolean true add internal controller to expose /metrics endpoints
    withHttpMiddleware object {} Tttp middleware options for http requests metrics
    withHttpMiddleware.enable boolean false Enable the middleware for http requests
    withHttpMiddleware.timeBuckets number[] [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 10] The time buckets wanted
    withHttpMiddleware.pathNormalizationExtraMasks RegEx[] [] The regexp mask for normalization

    Http requests

    To track the http requests metrics, simply set withHttpMiddleware.enable = true

    By default, this feature is disabled.

    import { Module } from '@nestjs/common';
    import { PromModule } from '@digikare/nestjs-prom';
    
    @Module({
      imports: [
        PromModule.forRoot({
          withHttpMiddleware: {
            enable: true,
          }
        }),
      ]
    })
    export class ApplicationModule {}

    Setup metric

    To setup a metric, the module provide multiple ways to get a metric.

    Using PromService and Dependency Injection

    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();
      }
    }

    Using Param Decorator

    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);
      }
    }
    import { GaugeMetric, PromGauge } from '@digikare/nest-prom';
    
    @Controller()
    export class AppController {
    
      @Get('/home')
      home(
        @PromGauge('app_gauge_1') gauge1: GaugeMetric,
      ) {
        gauge1.inc(); // 1
        gauge1.inc(5); // 6
        gauge1.dec(); // 5
        gauge1.dec(2); // 3
        gauge1.set(10); // 10
      }
    }

    Metric class instances

    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

    Metric method calls

    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
      }
    }

    Metric endpoint

    The default metrics endpoint is /metrics this can be changed with the metricPath option

    @Module({
      imports: [
        PromModule.forRoot({
          defaultLabels: {
            app: 'my_app',
          },
          metricPath: '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.

    API

    PromModule.forRoot() options

    Option Type Default Description
    defaultLabels Object<string, string number> {}
    metricPath string /metrics Path to use to service metrics
    withDefaultsMetrics boolean true enable defaultMetrics provided by prom-client
    withDefaultController boolean true add internal controller to expose /metrics endpoints
    withHttpMiddleware object {} To enable the http middleware for http metrics
    withHttpMiddleware.enable boolean false Enable http middleware
    withHttpMiddleware.timeBuckets number[] [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 10] The time buckets wanted
    withHttpMiddleware.pathNormalizationExtraMasks RegEx[] [] The regexp mask for normalization

    Decorators

    • @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

    Auth/security

    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.

    License

    MIT licensed

    Install

    npm i @khaledez/nestjs-prom

    DownloadsWeekly Downloads

    0

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    64.9 kB

    Total Files

    52

    Last publish

    Collaborators

    • khaledez