rochasolutions
Infraestrutura

O Que é Health Check e Como Implementar na Aplicação?

Danilo Rocha5 min de leitura

O que é health check

Health check é um endpoint da aplicação que responde se o serviço está no ar e em condição de atender requisição. Ele existe porque um processo pode estar rodando e, ainda assim, incapaz de responder de verdade: banco de dados fora, memória esgotada, dependência externa travada. O health check separa "o processo existe" de "o processo funciona".

A diferença parece pequena até o load balancer continuar enviando tráfego para uma instância presa, só porque o processo não caiu. Um health check bem feito detecta esse tipo de falha antes que o usuário sinta. Orquestradores e balanceadores consultam esse endpoint em intervalo curto, geralmente a cada poucos segundos, e usam a resposta para decidir se aquela instância continua recebendo tráfego ou se precisa reiniciar.

Liveness, readiness e startup probe: qual a diferença

Liveness responde se o processo está vivo e deveria reiniciar quando falha. Readiness responde se a instância está pronta para receber tráfego agora. Startup probe cobre o tempo de inicialização de serviços que demoram para ficar prontos, sem disparar reinício prematuro.

Confundir liveness com readiness é o erro que mais aparece em produção. Um serviço pode estar vivo, o processo responde, e ainda não estar pronto, ainda conectando ao banco, ainda aquecendo cache. Marcar isso como liveness falho reinicia o processo sem necessidade, atrasando ainda mais a inicialização. Marcar como readiness falho só tira a instância da rotação de tráfego até ela terminar de subir, o que é exatamente o comportamento certo.

Kubernetes, por exemplo, trata os três tipos de probe separadamente, cada um com sua própria rota e seu próprio critério de falha. Ambientes sem orquestrador, como uma VM atrás de um load balancer simples, geralmente simplificam para um único endpoint, mas o raciocínio por trás das três categorias continua valendo: nem todo problema pede reinício, e nem toda espera pede remoção definitiva da rotação.

Onde implementar o endpoint de health check

O endpoint de health check normalmente vive em uma rota fixa, como /health ou /healthz, fora da autenticação da API, porque quem consulta é o orquestrador, não o usuário final. Ele responde rápido, sem fazer o trabalho pesado que a aplicação faz nas rotas reais.

A resposta mínima é um código de status: 200 quando saudável, 503 quando não. Um health check mais completo retorna também um corpo JSON com o estado de cada dependência verificada, por exemplo banco de dados, cache e fila, o que ajuda a diagnosticar qual parte falhou sem precisar abrir o painel de observabilidade de aplicação imediatamente. Esse corpo detalhado é útil para o time, mas o orquestrador em geral só olha o código de status, então nunca condicione a decisão de rotear tráfego a um campo específico do JSON sem garantir que o orquestrador realmente lê esse campo.

Como implementar um health check confiável passo a passo

Implementar um health check que gera confiança de verdade, em vez de só existir para passar uma checklist, segue uma sequência simples.

  1. Crie uma rota separada da API de negócio, sem autenticação e sem efeito colateral no banco de dados.
  2. Verifique só as dependências que, se fora do ar, realmente impedem a aplicação de atender requisição: nem toda integração externa merece esse peso.
  3. Defina um timeout curto para cada verificação, porque um health check que demora mais que a própria aplicação não serve para nada.
  4. Separe liveness de readiness desde o início, mesmo em ambiente sem orquestrador hoje, para facilitar a migração quando o projeto crescer.
  5. Registre a mudança de estado do health check como evento, não como linha de log comum, para cruzar depois com o momento exato de um incidente.

Erros comuns que geram falso positivo ou falso negativo

Falso positivo é a aplicação reportar saudável quando não está. Falso negativo é reportar doente quando está tudo bem. Os dois custam caro, de formas diferentes.

O falso positivo mais comum é um health check que só verifica se o processo responde, sem checar a dependência que realmente importa. Suponha uma API que depende de um banco de dados externo: se o endpoint de health check não testa essa conexão, ele continua respondendo 200 enquanto toda escrita falha silenciosamente, e ninguém percebe até o cliente reclamar.

O falso negativo mais comum é verificar dependência demais. Um health check que falha porque um serviço de terceiro secundário está lento tira a instância de rotação sem necessidade. Se todas as instâncias dependem do mesmo serviço lento, o sistema inteiro para por um motivo que não deveria afetar o núcleo do produto. A regra prática é simples: só entra no health check a dependência sem a qual a aplicação não tem como responder à requisição principal.

Health check no pipeline de deploy

Health check e deploy contínuo resolvem metade do mesmo problema: saber se a versão nova está realmente funcionando antes de receber tráfego de produção. A verificação pós-deploy que qualquer pipeline sério faz é, na prática, uma chamada ao endpoint de health check logo depois de a nova instância subir.

Sem essa verificação, um deploy quebrado só é descoberto quando o monitoramento de erros dispara o primeiro alerta, com usuário real já afetado. Com ela, o próprio pipeline recusa a promoção da versão nova e reverte antes que alguém perceba qualquer problema.

Se o seu sistema ainda não separa liveness de readiness, ou se o deploy promove versão nova sem checar se ela respondeu de verdade, fale com a gente para revisar o pipeline antes do próximo incidente.