O Que é Health Check e Como Implementar na Aplicação?
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.
- Crie uma rota separada da API de negócio, sem autenticação e sem efeito colateral no banco de dados.
- 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.
- 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.
- Separe liveness de readiness desde o início, mesmo em ambiente sem orquestrador hoje, para facilitar a migração quando o projeto crescer.
- 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.