Es importante tener en cuenta que este módulo se encuentra implementado en el package @tresdoce-nestjs-toolkit/paas, ya que es una funcionalidad core para el starter.

Este módulo está pensado para ser utilizado en NestJS Starter, o cualquier proyecto que utilice una configuración centralizada, siguiendo la misma arquitectura del starter.

Glosario

• Demo
• Requerimientos básicos
• Instalar dependencia
• Configuración
• Uso
• API Reference
• Changelog
• License MIT

---

Requerimientos básicos

• NestJS Starter
• Node.js v22.21.1 or higher (Download)
• YARN ≥ 1.22.22 o NPM ≥ 11.6.4
• NestJS v11.1.11 or higher (Documentación)

Instalar dependencia

npm install -S @tresdoce-nestjs-toolkit/health

yarn add @tresdoce-nestjs-toolkit/health

Dependencias internas

Este paquete requiere los siguientes paquetes del toolkit:

Paquete	Razón
@tresdoce-nestjs-toolkit/core	Tipos Typings.AppConfig, decoradores base y utilidades comunes
@tresdoce-nestjs-toolkit/tracing	Decorador @SkipTrace y contexto de OpenTelemetry

Configuración

El módulo utiliza la configuración centralizada para ejecutar los health checks correspondientes a los servicios configurados.

Siguiendo la arquitectura del NestJS Starter, la información agregada en health y services impacta directamente en el endpoint /health/readiness, así como también la presencia de configuraciones de elasticsearch, typeorm, redis y camunda.

//./src/config/configuration.ts
import { getSkipHealthChecks, Typings } from '@tresdoce-nestjs-toolkit/core';
import { registerAs } from '@nestjs/config';

export default registerAs('config', (): Typings.AppConfig => {
  return {
    //...
    health: {
      skipChecks: getSkipHealthChecks(process.env.SKIP_HEALTH_CHECKS),
      storage: {
        path: '/',
        thresholdPercent: 0.9,
      },
      memory: {
        heap: 300 * 1024 * 1024, // 300 MB en bytes
        rss: 300 * 1024 * 1024, // 300 MB en bytes
      },
    },
    services: {
      myApi: {
        url: process.env.MY_API_URL,
      },
      myApiTwo: {
        url: process.env.MY_API_TWO_URL,
        timeout: 5000,
        healthPath: '/health/liveness',
      },
    },
    //...
  };
});

Para ver en detalle todas las propiedades de la configuración, hace clic acá.

Health

skipChecks: Lista de checks a omitir en el readiness. Si no se requiere omitir ninguno, se recomienda remover la variable y su configuración.

• Type: String[]
• Values: storage | memory | elasticsearch | redis | camunda | typeorm
• Example: elasticsearch,memory

storage: Configuración para el check de disco mediante DiskHealthIndicator.checkStorage().

Propiedad	Type	Description
path	string	Ruta del sistema de archivos a monitorear (ej: '/' en Linux, 'C:\\' en Windows).
thresholdPercent	number	Porcentaje máximo de uso de disco permitido, entre 0 y 1. Ej: 0.9 equivale al 90%.

memory: Configuración para los checks de memoria mediante MemoryHealthIndicator.

Propiedad	Type	Description
heap	number	Límite en bytes para el uso del heap de Node.js (checkHeap).
rss	number	Límite en bytes para el RSS (Resident Set Size) del proceso (checkRSS).

Services

timeout: Tiempo máximo de respuesta del servicio en milisegundos.

• Type: Number
• Default: 0

healthPath: Endpoint al cual se realiza el ping check del servicio. Si no se especifica, se usa el path por defecto.

• Type: String
• Default: /health/liveness

Checks automáticos por configuración

El módulo agrega checks automáticamente al readiness si detecta las siguientes claves en la configuración centralizada:

Configuración presente	Check agregado	Key de resultado en readiness
config.database.typeorm	Ping a TypeORM con TypeOrmHealthIndicator	typeorm-<type>
config.redis	Ping a Redis vía microservicio	redis o redis-<name>
config.elasticsearch	Ping HTTP al nodo de Elasticsearch	elasticsearch
config.camunda	Ping HTTP a <camunda.baseUrl>/version	camunda

Cada uno de estos checks puede omitirse individualmente usando health.skipChecks.

Uso

Importar HealthModule en el módulo principal de la aplicación.

//./src/app.module.ts
import { HealthModule } from '@tresdoce-nestjs-toolkit/health';

@Module({
  imports: [
    //...
    HealthModule,
    //...
  ],
  //...
})
export class AppModule {}

Para visualizar las respuestas de los endpoints, navegar a /health/liveness y /health/readiness.

Liveness

Schema: <http|https>://<server_url><:port>/<app-context>/health/liveness
Example: http://localhost:8080/v1/health/liveness

El endpoint de liveness verifica que el proceso de Node.js está en ejecución. No depende de servicios externos.

Response

{
  "status": "up"
}

Readiness

Schema: <http|https>://<server_url><:port>/<app-context>/health/readiness
Example: http://localhost:8080/v1/health/readiness

El endpoint de readiness ejecuta todos los health checks configurados. Las claves de cada servicio en services aparecen con el prefijo service- en la respuesta.

Response exitosa

{
  "status": "ok",
  "info": {
    "service-myApi": {
      "status": "up"
    },
    "service-myApiTwo": {
      "status": "up"
    }
  },
  "error": {},
  "details": {
    "service-myApi": {
      "status": "up"
    },
    "service-myApiTwo": {
      "status": "up"
    }
  }
}

Response con error

{
  "status": "error",
  "info": {
    "service-myApi": {
      "status": "up"
    }
  },
  "error": {
    "service-myApiTwo": {
      "status": "down",
      "message": "connect ECONNREFUSED myApiTwo.example.com"
    }
  },
  "details": {
    "service-myApi": {
      "status": "up"
    },
    "service-myApiTwo": {
      "status": "down",
      "message": "connect ECONNREFUSED myApiTwo.example.com"
    }
  }
}

Response con checks adicionales (storage, memory, typeorm)

{
  "status": "ok",
  "info": {
    "storage": {
      "status": "up"
    },
    "memory_heap": {
      "status": "up"
    },
    "memory_rss": {
      "status": "up"
    },
    "typeorm-postgres": {
      "status": "up"
    },
    "service-myApi": {
      "status": "up"
    }
  },
  "error": {},
  "details": {
    "storage": {
      "status": "up"
    },
    "memory_heap": {
      "status": "up"
    },
    "memory_rss": {
      "status": "up"
    },
    "typeorm-postgres": {
      "status": "up"
    },
    "service-myApi": {
      "status": "up"
    }
  }
}

Excluir rutas de salud en middlewares

Para evitar que los middlewares globales (autenticación, logging, etc.) intercepten las rutas de health, se puede usar el array controllersExcludes exportado por el módulo:

//./src/app.module.ts
import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
import { HealthModule, controllersExcludes } from '@tresdoce-nestjs-toolkit/health';
import { SomeMiddleware } from './some.middleware';

@Module({
  imports: [HealthModule],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(SomeMiddleware)
      .exclude(...controllersExcludes)
      .forRoutes('*');
  }
}

El array controllersExcludes contiene las rutas GET /health/liveness y GET /health/readiness.

API Reference

Constantes exportadas

Constante	Valor	Descripción
DEFAULT_SERVICE_LIVENESS_PATH	'/health/liveness'	Path por defecto usado en el ping check de servicios cuando no se especifica healthPath.
controllersExcludes	RouteInfo[]	Array con las rutas de liveness y readiness, útil para excluirlas de middlewares globales.

HealthModule

Módulo global que registra los controllers de liveness y readiness, e inyecta la configuración centralizada mediante el token CONFIG_OPTIONS.

Endpoints

Método	Ruta	Descripción
GET	/health/liveness	Retorna { status: 'up' } si el proceso está vivo.
GET	/health/readiness	Ejecuta todos los health checks configurados.

Changelog

Todos los cambios notables de este paquete se documentarán en el archivo Changelog.

---