Health checks (Terminus)

The terminus offers hooks to react on graceful shutdowns and supports you creating proper Kubernetes readiness / liveness checks for any HTTP application. The module @nestjs/terminus integrates the terminus library with the Nest ecosystem.

Getting started

To get started with @nestjs/terminus we need to install the required dependencies.

  1. $ npm install --save @nestjs/terminus @godaddy/terminus

Setting up a health check

A health check represents a summary of health indicators. A health indicator executes a check of a service, whether it is in a healthy state or not. A health check is positive, if all the assigned health indicators are up and running. Because a lot of applications will need similar health indicators, @nestjs/terminus provides a set of predefined health indicators, such as:

  • DNSHealthIndicator
  • TypeOrmHealthIndicator
  • MongooseHealthIndicator
  • MicroserviceHealthIndicator
  • MemoryHealthIndicator
  • DiskHealthIndicator

DNS Health Check

The first step to get started with our first health check, is to setup a service which will associate health indicators to an endpoint.

  1. @@filename(terminus-options.service)
  2. import {
  3.   TerminusEndpoint,
  4.   TerminusOptionsFactory,
  5.   DNSHealthIndicator,
  6.   TerminusModuleOptions
  7. } from '@nestjs/terminus';
  8. import { Injectable } from '@nestjs/common';
  10. @Injectable()
  11. export class TerminusOptionsService implements TerminusOptionsFactory {
  12.   constructor(
  13.     private readonly dns: DNSHealthIndicator,
  14.   ) {}
  16.   createTerminusOptions(): TerminusModuleOptions {
  17.     const healthEndpoint: TerminusEndpoint = {
  18.       url: '/health',
  19.       healthIndicators: [
  20.         async () => this.dns.pingCheck('google', 'https://google.com'),
  21.       ],
  22.     };
  23.     return {
  24.       endpoints: [healthEndpoint],
  25.     };
  26.   }
  27. }
  28. @@switch
  29. import { Injectable, Dependencies } from '@nestjs/common';
  30. import { DNSHealthIndicator } from '@nestjs/terminus';
  32. @Injectable()
  33. @Dependencies(DNSHealthIndicator)
  34. export class TerminusOptionsService {
  35.   constructor(dns) {
  36.     this.dns = dns;
  37.   }
  39.   createTerminusOptions() {
  40.     const healthEndpoint = {
  41.       url: '/health',
  42.       healthIndicators: [
  43.         async () => this.dns.pingCheck('google', 'https://google.com'),
  44.       ],
  45.     };
  46.     return {
  47.       endpoints: [healthEndpoint],
  48.     };
  49.   }
  50. }

Once we have set up our TerminusOptionsService, we can import the TerminusModule into the root ApplicationModule. The TerminusOptionsService will provide the settings, which in turn will be used by the TerminusModule.

  1. @@filename(app.module)
  2. import { Module } from '@nestjs/common';
  3. import { TerminusModule } from '@nestjs/terminus';
  4. import { TerminusOptionsService } from './terminus-options.service';
  6. @Module({
  7.   imports: [
  8.     TerminusModule.forRootAsync({
  9.       useClass: TerminusOptionsService,
  10.     }),
  11.   ],
  12. })
  13. export class ApplicationModule { }

info Hint If done correctly, Nest will expose the defined health check(s), which are reachable through a GET request to the defined route. For example curl -X GET 'http://localhost:3000/health'

Custom health indicator

In some cases, the predefined health indicators provided by @nestjs/terminus do not cover all of your health check requirements. In this case you can set up a custom health indicator according to your needs.

Let’s get started by creating a service which will represent our custom health indicator. To get a basic understanding how a health indicator is structured, we will create an example DogHealthIndicator. This health indicator should have the state “up”, if every Dog object has the type goodboy, otherwise it will throw an error, which then the health indicator will be seen as “down”.

  1. @@filename(dog.health)
  2. import { Injectable } from '@nestjs/common';
  3. import { HealthCheckError } from '@godaddy/terminus';
  4. import { HealthIndicator, HealthIndicatorResult } from '@nestjs/terminus';
  6. export interface Dog {
  7.   name: string;
  8.   type: string;
  9. }
  11. @Injectable()
  12. export class DogHealthIndicator extends HealthIndicator {
  13.   private readonly dogs: Dog[] = [
  14.     { name: 'Fido', type: 'goodboy' },
  15.     { name: 'Rex', type: 'badboy' },
  16.   ];
  18.   async isHealthy(key: string): Promise<HealthIndicatorResult> {
  19.     const badboys = this.dogs.filter(dog => dog.type === 'badboy');
  20.     const isHealthy = badboys.length === 0;
  21.     const result = this.getStatus(key, isHealthy, { badboys: badboys.length });
  23.     if (isHealthy) {
  24.       return result;
  25.     }
  26.     throw new HealthCheckError('Dogcheck failed', result);
  27.   }
  28. }
  29. @@switch
  30. import { Injectable } from '@nestjs/common';
  31. import { HealthCheckError } from '@godaddy/terminus';
  33. @Injectable()
  34. export class DogHealthIndicator extends HealthIndicator {
  35.   dogs = [
  36.     { name: 'Fido', type: 'goodboy' },
  37.     { name: 'Rex', type: 'badboy' },
  38.   ];
  40.   async isHealthy(key) {
  41.     const badboys = this.dogs.filter(dog => dog.type === 'badboy');
  42.     const isHealthy = badboys.length === 0;
  43.     const result = this.getStatus(key, isHealthy, { badboys: badboys.length });
  45.     if (isHealthy) {
  46.       return result;
  47.     }
  48.     throw new HealthCheckError('Dogcheck failed', result);
  49.   }
  50. }

The next thing we need to do is registering the health indicator as a provider.

  1. @@filename(app.module)
  2. import { Module } from '@nestjs/common';
  3. import { TerminusModule } from '@nestjs/terminus';
  4. import { TerminusOptionsService } from './terminus-options.service';
  5. import { DogHealthIndicator } from './dog.health';
  7. @Module({
  8.   imports: [
  9.     TerminusModule.forRootAsync({
  10.       imports: [ApplicationModule],
  11.       useClass: TerminusOptionsService,
  12.     }),
  13.   ],
  14.   providers: [DogHealthIndicator],
  15.   exports: [DogHealthIndicator],
  16. })
  17. export class ApplicationModule { }

info Hint In a real world application the DogHealthIndicator should be provided in a separate module, for example DogsModule, which then will be imported by the ApplicationModule. But keep in mind to add the DogHealthIndicator to the exports array of the DogModule and add the DogModule in imports array of the TerminusModule.forRootAsync() parameter object.

The last required thing to do is to add the now available health indicator in the required health check endpoint. For that we go back to our TerminusOptionsService and implement it to the /health endpoint.

  1. @@filename(terminus-options.service)
  2. import {
  3.   TerminusEndpoint,
  4.   TerminusOptionsFactory,
  5.   DNSHealthIndicator,
  6.   TerminusModuleOptions
  7. } from '@nestjs/terminus';
  8. import { Injectable } from '@nestjs/common';
  9. import { DogHealthIndicator } from './dog.health';
  11. @Injectable()
  12. export class TerminusOptionsService implements TerminusOptionsFactory {
  13.   constructor(
  14.     private readonly dogHealthIndicator: DogHealthIndicator
  15.   ) {}
  17.   createTerminusOptions(): TerminusModuleOptions {
  18.     const healthEndpoint: TerminusEndpoint = {
  19.       url: '/health',
  20.       healthIndicators: [
  21.         async () => this.dogHealthIndicator.isHealthy('dog'),
  22.       ],
  23.     };
  24.     return {
  25.       endpoints: [healthEndpoint],
  26.     };
  27.   }
  28. }
  29. @@switch
  30. import { DogHealthIndicator } from './dog.health';
  31. import { Injectable, Dependencies } from '@nestjs/common';
  33. @Injectable()
  34. @Dependencies(DogHealthIndicator)
  35. export class TerminusOptionsService {
  36.   constructor(dogHealthIndicator) {
  37.     this.dogHealthIndicator = dogHealthIndicator;
  38.   }
  40.   createTerminusOptions() {
  41.     const healthEndpoint = {
  42.       url: '/health',
  43.       healthIndicators: [
  44.         async () => this.dogHealthIndicator.isHealthy('dog'),
  45.       ],
  46.     };
  47.     return {
  48.       endpoints: [healthEndpoint],
  49.     };
  50.   }
  51. }

If everything has been done correctly, the /health endpoint should respond with a 503 response code and the following data.

  1. {
  2.   "status": "error",
  3.   "error": {
  4.     "dog": {
  5.       "status": "down",
  6.       "badboys": 1
  7.     }
  8.   }
  9. }

You can view working examples in the @nestjs/terminus repository.

Custom Logger

The Terminus module automatically logs every error during a health check request. By default, it will use the globally defined Nest logger.You can read more about the global logger in the Logger chapter.In some cases, you want to handle the logs of Terminus explicitly. In this case, the TerminusModule.forRoot[Async] function offers an optionfor a custom logger.

  2. TerminusModule.forRootAsync({
  3.   logger: (message: string, error: Error) => console.error(message, error),
  4.   endpoints: [
  5.     ...
  6.   ]
  7. })

The logger can also be disabled by setting the logger option to null.

  2. TerminusModule.forRootAsync({
  3.   logger: null,
  4.   endpoints: [
  5.     ...
  6.   ]
  7. })