Vipcommerce Lib Nest Halth Check

Lib de Health Check para Nest.js criada para facilitar a implementação da funcionalidade de Health Check nas aplicações.

A Lib fornece um controller interno que expõe uma rota para consulta da saúde da aplicação. Ao ocorrer mudança no estado da aplicação, notificações são enviadas para um canal do Discord, também é possível implementar listeners na aplicação monitorada que podem receber as mudanças de estado.

A construção da Lib é modular, cada recurso que será monitorado deve ser informado nas configurações do módulo da Lib, alguns módulos de monitoramento já estão disponíveis neste projeto. Módulos adicionais podem ser desenvolvidos seguindo uma interface estabelecida e utilizados para monitoramento da aplicação.

Por ser modular algumas dependências devem ser instaladas somente na aplicação que for utilizar determinado recurso, por exemplo, aplicações que utilizam Kafka devem possuir as dependências do Kafka instaladas. A Lib carrega somente o Terminus como dependência, demais módulos são utilizados somente como referência de tipo para o desenvolvimento e devem estar presentes na aplicação. Com isso, os conflitos causados por versões de dependências não devem ocorrer.

Configurações necessárias nos arquivos de Deployment

Nas configurações do Ingress adicione, em annotations:
alb.ingress.kubernetes.io/healthcheck-path: /$PREFIXO/internal/health

Onde $PREFIXO é o prefixo definido para a aplicação (A rota informada deve ser a mesma visível no Swagger)

alb.ingress.kubernetes.io/healthcheck-interval-seconds: '60'

considere o tempo necessário para resposta da aplicação, o valor padrão é 5 segundos

alb.ingress.kubernetes.io/healthcheck-timeout-seconds: 'X'

Variáveis de ambiente

Cada módulo possuí variáveis próprias.

Dica: para definir o nome do POD nas notificações do Discord, no arquivo Deployment defina a env

- name: POD_NAME
  valueFrom:
    fieldRef:
        fieldPath: metadata.name

Utilizando a Lib

import { HealthCheckModule } from 'vipcommerce-lib-nest-health-check';
import { MikroOrmHealthCheckIndicator } from 'vipcommerce-lib-nest-health-check/mikro-orm';
import { HttpPingHealthCheckIndicator } from 'vipcommerce-lib-nest-health-check/http-request';

@Global()
@Module({
  imports: [
    ....
    MikroOrmModule.forRoot(),
    HealthCheckModule.forRoot(
        MikroOrmHealthCheckIndicator, HttpPingHealthCheckIndicator
    ),
    ....
  ],
  providers: [....],
  controllers:[....],
  exports: [....]
})
export class InfrastructureModule {}

Importe o módulo principal da Lib e os Indicadores utilizados no monitoramento da aplicação.

Módulos de monitoramento

• Mikro-Orm (v 4.X)
  Para monitorar conexões do Mikro-orm v 4.x ou 5.x com apenas uma conexão utilize:

  import { MikroOrmHealthCheckIndicator } from 'vipcommerce-lib-nest-health-check/mikro-orm';

  Configurações disponíveis por variáveis de ambiente:
  HEALTH_CHECK_MIKRO_ORM_TIMEOUT = Define o tempo limite na verificação de conexão com o banco de dados

• DynamoDB
  Para monitorar conexões do DynamoDB utilize:

  import { DynamoDbHealthCheckIndicator } from 'vipcommerce-lib-nest-health-check/aws-dynamodb';

  Para o DynamoDB a conexão deve ser exportada utilizando um token DocumentClient em um módulo global da aplicação:

  import { HealthCheckModule } from 'vipcommerce-lib-nest-health-check';
  import { DynamoDbHealthCheckIndicator } from 'vipcommerce-lib-nest-health-check/aws-dynamodb';
  import { DocumentClient } from 'aws-sdk/clients/dynamodb';
    
  @Global()
  @Module({
      imports: [
      ....
          MikroOrmModule.forRoot(),
          HealthCheckModule.forRoot(DynamoDbHealthCheckIndicator),
      ....
      ],
      providers: [
      ....
      {
          provide: DocumentClient,
          useFactory: ()=>{
              return new DocumentClient(....);
          }
      }
      ....
      ],
      controllers:[....],
      exports: [....
      DocumentClient
      ....
      ]
  })
  export class InfrastructureModule {}

  Configurações disponíveis por variáveis de ambiente:
  HEALTH_CHECK_DYNAMODB_TIMEOUT = Tempo limite para obter uma resposta do dynamodb

• TypeORM
  Para monitorar conexões do TypeORM utilize:

  import { TypeOrmHealthCheckIndicator } from 'vipcommerce-lib-nest-health-check/type-orm';

  Configurações disponíveis por variáveis de ambiente:
  HEALTH_CHECK_TYPE_ORM_USE_NESTJS_DEFAULT_CONNECTION = para adicionar a conexão default criada pelo modulo nest automaticamente
HEALTH_CHECK_TYPE_ORM_TIMEOUT = tempo limite da conexão

  Para monitorar outras conexões, além da padrão criada pelo modulo type-orm/nestjs deve ser solicitada a instância do monitor e adicionadas as conexões desejadas.

  class Servico implements OnModuleInit{
      constructor(private readonly typeOrmHealthCheck:TypeOrmHealthCheckIndicator){}
      async onModuleInit(){
          const dataSource = new DataSource(....);
          await dataSource.initialize();
          this.typeOrmHealthCheck.addMonitor({
              name: 'conexão-extra',
              dataSource 
          })
      }
  }

  ou

  const TypeOrmFactory = {
      provide: 'TYPE_ORM_CONNECTION',
      useFactory: async ()=>{
          const dataSource = new DataSource(....);
          await dataSource.initialize();
          return dataSource;
      }
  }
  class Servico implements OnModuleInit{
      constructor(
          @Inject('TYPE_ORM_CONNECTION')
          private readonly dataSource
          private readonly typeOrmHealthCheck:TypeOrmHealthCheckIndicator){}
      async onModuleInit(){
            
          this.typeOrmHealthCheck.addMonitor({
              name: 'conexão-extra',
              dataSource: this.dataSource 
          })
      }
  }

  ou

  const TypeOrmFactory = {
      provide: 'TYPE_ORM_CONNECTION',
      inject: [TypeOrmHealthCheckIndicator]
      useFactory: async (typeOrmHealthCheck:TypeOrmHealthCheckIndicator)=>{
          const dataSource = new DataSource(....);
          await dataSource.initialize();
           this.typeOrmHealthCheck.addMonitor({
              name: 'conexão-extra',
              dataSource
          });
          return dataSource;
      }
  }

• HTTPPing
  Para monitorar conexões HTTP:

  import { HttpPingHealthCheckIndicator } from 'vipcommerce-lib-nest-health-check/http-request';

  Configurações disponíveis por variáveis de ambiente:

  HEALTH_CHECK_HTTP_URIS = uri completa dos destinos a serem monitorados, separadas por vírgula (Obrigatório informar ao menos uma).
  HEALTH_CHECK_HTTP_TIMEOUT = tempo limite da conexão 

  Também é possível adicionar urls para monitoramento programaticamente:

  @Injectable()
  class MeuServico{
      constructor(private readonly httpHealthCheck:HttpPingHealthCheckIndicator){
          this.httpHealthCheck.addMonitor({
              url: 'https://url-destino.com.br'
          })
      }
  }

• KafkaJS
  Para monitorar consumers KafkaJS:

  import { KafkaHealthCheckIndicator, KafkaConsumerHealthCollector } from 'vipcommerce-lib-nest-health-check/kafka';

  Para monitorar um consumer é preciso fazer programaticamente, solicitando a instância do KafkaHealthCheckIndicator e adicionando um objeto KafkaConsumerHealthCollector que irá coletar as informações do consumer

  @Injectable()
  class MeuServicoKafka implements OnModuleInit{
      private kafka: Kafka;
      private consumer: Consumer;
      constructor(private readonly kafkaHealthCheck:KafkaHealthCheckIndicator){}
  
      async onModuleInit(){
          this.kafka = new Kafka({....});
          this.consumer = this.kafka.consumer();
          await this.consumer.connect();
          this.kafkaHealthCheck.addMonitor({
              consumerName: 'meu-consumer-kafka',
              consumerHealthCollector: new KafkaConsumerHealthCollector(this.consumer)
          })
      }
  }

  Configurações disponíveis por variáveis de ambiente:
  HEALTH_CHECK_KAFKA_CONSUMER_TIMEOUT = tempo limite da última conexão do consumer com os brokers

Notificação de mudança de status

Quando ocorrerem mudanças na saúde da aplicação, as notificações são enviadas para um webhook do Discord.
Eventos que geram notificação:

• Primeira verificação de health check
• Aplicação entrou em estado de erro
• Aplicação recuperou-se do estado de erro
• Aplicação sendo desligada

Configurações disponíveis por variáveis de ambiente:

DISABLE_HEALTH_CHECK_DISCORD_NOTIFICATION = desabilita as notificações no discord ('true')  
DISCORD_WEB_HOOK_URL = URL do webhook, obrigatória se as notificações não forem desativadas    
DISABLE_NOTIFICATION_ON_FIRST_HEALTH_CHECK = desativa a notificação da primeira verificação de halth check da aplicação  
HEALTH_CHECK_TO_MENTION_DISCORD = Ids do Discord que serão mencionados nas mensagens, separados por vírgula  
APP_NAME = Nome da aplicação que será exibido no Discord  
POD_NAME = Nome/Identificador do POD em execução  

Criando um indicador personalizado

Pode ser necessário monitorar uma dependência não implementada nesta Lib, para aproveitar a mesma estrutura de monitoramento é possível criar um indicador de health check personalizado e utilizá-lo no módulo de health check.

import { HealthCheckModule,IHealthCheckIndicator  } from 'vipcommerce-lib-nest-health-check';

class MonitorPersonalizadoDeDependencias implements IHealthCheckIndicator {
    checkHealth(): HealthIndicatorFunction[] {
        return [
            ()=> this.monitorarDependencia();
        ]
    }

    async monitorarDependencia(): Promise<HealthIndicatorResult>{
        ....
        return {
            status: 'ok',
            details: {
                'dependencia1': 'up'
            }
        }
    }
}

@Global()
@Module({
    imports: [
    ....
        HealthCheckModule.forRoot(MonitorPersonalizadoDeDependencias),
    ...
    ]
})
export class InfraModule {}

Criando um componente de notificação personalizado

Caso a aplicação precise reagir às mudanças na saúde da aplicação é possível criar componentes especializados.

import { HealthCheckModule,IHealthCheckEventsListener,HealthCheckEventListener  } from 'vipcommerce-lib-nest-health-check';
@HealthCheckEventListener()
export class NotificarTelegram implements IHealthCheckEventsListener{
    constructor(private readonly telegramService: TelegramService){}

    onHealthError(healthCheckResult: HealthCheckResult): Promise<void>{
        ....
        await this.telegramService.enviar('Erro na aplicação', healthCheckResult);
    }
    onHealthRecovery(healthCheckResult: HealthCheckResult): Promise<void> {
        ....
        await this.telegramService.enviar('Aplicação recuperou estado de erro', healthCheckResult);
    }
    onFirstHealthStatus(healthCheckResult: HealthCheckResult): Promise<void> {
        ....
        await this.telegramService.enviar('Primeira verificação na aplicação', healthCheckResult);
    }
    onApplicationShuttingDown(healthCheckResult: HealthCheckResult): Promise<void> {
        ....
        ....
        await this.telegramService.enviar('Aplicação desligando', healthCheckResult);
    }
}


@Global()
@Module({
    imports: [
    ....
        HealthCheckModule.forRoot(MonitorPersonalizadoDeDependencias),
    ...
    ],
    providers:[
        NotificarTelegram
    ]
})
export class InfraModule {}

Contribuindo para o desenvolvimento

Cada novo indicador deve ser criado na pasta health-check-indicators, seguindo a interface IHealthCheckIndicator do core.
Os novos indicadores devem ser exportados no package.json no item "exports" e sua definição de tipos para suporte ao typescript em "typesVersions".

{
    ....
    "exports": {
    ....
    "./novo-indicador": "./lib/health-check-indicators/novo-indicador/index.js"
  },
  "typesVersions": {
    "*": {
      ....
      "novo-indicador": [
        "./lib/health-check-indicators/novo-indicador"
      ]
    }
  },
    ....
}