Health Check Endpoint

Expõe o estado de uma API e de cada dependência para quem a opera: /live e /ready para o orquestrador, /health com o detalhe por dependência, e /metrics com os mesmos dados como gauges do Prometheus para dashboard e alerta. Cada dependência é classificada — crítica derruba o /ready, opcional só degrada — e cada check tem timeout próprio e um limite de latência acima do qual passa a contar como degradado.

passos: 6
arquivos: 5
testes: 0
tecnologias: 7

Infraestrutura realTypeScriptBunElysiaPostgreSQLRedisRabbitMQDocker

Cenário Relações Comparar

Baixar cartão

Cenário

A API de pagamentos depende do PostgreSQL (sem ele não há pagamento), do Redis (cache: sem ele lê do banco) e do RabbitMQ (fila de notificações: sem ela as notificações esperam). Com o Redis fora ou a fila apagada, /health responde 207 e a instância segue no balanceamento. Com o PostgreSQL fora, /ready responde 503 e a instância sai do balanceamento, mas /live segue 200 e ela não é reiniciada. O /metrics mostra cada dependência como 1, 0,5 ou 0 e a latência de cada check.

Planta

Fluxo

6/6

6 passos — reproduza para seguir o fluxo

chamada
resposta ou assíncrono
falha
passo
toque num nó para focar
Outras plantas de fluxo

Como funciona

6 passos

Liveness e readiness por endpoint.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

/health+6

/metrics+3

run+2

degraded+2

/ready+2

timeoutMs+1

Health Check

cacheTtlMs+1

Health Check

01
Cada check declara critical, timeoutMs, degradedAboveMs e run, sobre conexões que a API já tem
02
checkStatusOf: falha de check crítico é critical; qualquer outra falha, ou sucesso mais lento que degradedAboveMs, é degraded
03
/ready roda só o PostgreSQL; /health e /metrics rodam os três; o pior status define o HTTP (200, 207 ou 503)
04
O check do RabbitMQ usa um canal descartável na conexão existente: um checkQueue que falha fecha só esse canal, nunca o de publicação
05
healthMetricsText publica health_check_status e health_check_latency_ms por dependência
06
Os resultados ficam em cache por cacheTtlMs, para os probes não virarem carga sobre uma dependência já degradada

Trade-offs

O que se ganha, o que se paga

4 vantagenscada ganho tem um preço4 custos

Vantagens

Orquestrador, operação e Prometheus leem o mesmo estado
Latência alta vira sinal antes de virar falha
Dependência opcional fora não tira a instância do ar
Canal descartável isola o check do tráfego real

Custos

Um endpoint a mais para proteger de exposição pública
degradedAboveMs precisa ser calibrado por dependência
Classificar crítico × opcional errado derruba ou mantém a instância indevidamente
Um canal aberto e fechado a cada check do broker

apps/observability/health-check-endpoint

5 arquivos

src/

probe_health.tsPlugin com /live, /startup, /ready, /health e /metrics, timeout, limite de latência e cache
api_health.tsChecks de PostgreSQL, Redis e RabbitMQ sobre as conexões da API
config_health.tsConfiguração validada do ambiente
demo.tsdemoTudo no ar, Redis fora, fila apagada e PostgreSQL fora