gRPC Health Checking: monitore serviços Node.js

gRPC Health Checking no Node.js implementa um protocolo padrão para informar se um serviço está pronto para receber chamadas. Balanceadores, sidecars e orquestradores podem consultar o método Check ou acompanhar mudanças com Watch.

Um processo estar vivo não significa que está saudável. Ele pode ter perdido banco, configuração obrigatória ou capacidade de processar novas requisições. Health checking separa vida do processo, prontidão e estado de dependências.

Protocolo padrão

O serviço oficial usa o pacote grpc.health.v1:

service Health {
  rpc Check(HealthCheckRequest) returns (HealthCheckResponse);
  rpc Watch(HealthCheckRequest) returns (stream HealthCheckResponse);
}

message HealthCheckRequest {
  string service = 1;
}

A resposta pode ser SERVING, NOT_SERVING, UNKNOWN ou SERVICE_UNKNOWN.

Estado por serviço

Uma aplicação pode publicar estado global e por serviço:

const healthState = new Map([
  ['', 'SERVING'],
  ['catalog.v1.CatalogService', 'SERVING'],
  ['billing.v1.BillingService', 'NOT_SERVING']
]);

A string vazia representa a saúde geral do servidor.

Implementando Check

function check(call, callback) {
  const service = call.request.service ?? '';
  const status = healthState.get(service);

  if (!status) {
    return callback({
      code: grpc.status.NOT_FOUND,
      message: 'Serviço desconhecido'
    });
  }

  callback(null, { status });
}

Use os valores numéricos ou enums gerados pelo Protobuf conforme a biblioteca carregada.

Readiness versus liveness

Liveness responde se o processo está funcionando e pode se recuperar. Readiness indica se deve receber tráfego. Uma falha temporária de banco normalmente torna o serviço não pronto, mas não exige reiniciar o processo imediatamente.

Não verifique tudo em cada chamada

Executar query, chamada HTTP e acesso ao Redis em todo health check cria carga e pode amplificar incidentes. Mantenha um estado atualizado por verificações periódicas com timeout e jitter.

setInterval(async () => {
  const databaseOk = await checkDatabaseWithTimeout();
  healthState.set(
    'catalog.v1.CatalogService',
    databaseOk ? 'SERVING' : 'NOT_SERVING'
  );
}, 5000).unref();

Startup

Inicie como NOT_SERVING. Carregue configuração, conecte dependências, aqueça caches essenciais e somente depois marque SERVING.

healthState.set('', 'NOT_SERVING');
await initializeApplication();
healthState.set('', 'SERVING');

Shutdown

Ao receber SIGTERM, marque NOT_SERVING antes de drenar chamadas:

process.once('SIGTERM', async () => {
  healthState.set('', 'NOT_SERVING');
  healthState.set('catalog.v1.CatalogService', 'NOT_SERVING');
  await drainServer();
});

Isso ajuda o balanceador a parar de enviar novas chamadas enquanto as existentes terminam.

Watch

O método Watch mantém um stream e envia mudanças:

function watch(call) {
  const service = call.request.service ?? '';

  const send = status => call.write({ status });
  send(healthState.get(service) ?? 'SERVICE_UNKNOWN');

  const unsubscribe = healthEvents.subscribe(service, send);

  call.on('cancelled', unsubscribe);
  call.on('close', unsubscribe);
}

Respeite backpressure e remova listeners ao encerrar para evitar vazamentos.

Dependências obrigatórias e opcionais

Nem toda falha deve tirar o serviço do ar. Se o cache falhar e existe fallback para banco, o serviço pode continuar pronto, mas degradado. Se o banco principal é obrigatório, marque não pronto.

Estado degradado

O protocolo padrão não possui DEGRADED. Use métricas e dashboards para degradação, mantendo SERVING quando a operação principal ainda atende ao contrato.

Timeouts

Cada verificação de dependência precisa de timeout curto. Um health checker travado não deve bloquear a atualização do estado.

await Promise.race([
  database.query('SELECT 1'),
  timeout(200)
]);

Histerese

Uma única falha transitória pode não justificar remover a instância. Exija algumas falhas consecutivas para marcar NOT_SERVING e alguns sucessos para recuperar.

if (failedChecks >= 3) setNotServing();
if (successfulChecks >= 2) setServing();

Isso reduz flapping, mas aumenta tempo de detecção. Ajuste conforme o sistema.

Kubernetes

O Kubernetes pode usar probes gRPC nativas em versões compatíveis. Configure porta, serviço e thresholds. A probe deve consultar readiness, enquanto liveness deve ser conservadora.

Consulte Kubernetes Probes no Node.js.

Load balancers

Alguns clientes gRPC suportam health checking integrado. Confirme se o resolver e a política de balanceamento utilizam o protocolo, ou configure o balanceador externo.

Segurança

Health endpoints não devem expor nomes de hosts, versões de banco, stack traces ou credenciais. O status padrão é suficiente para balanceamento.

Em redes não confiáveis, use TLS. Decida se o método exige autenticação; probes internas podem usar identidade técnica.

Observabilidade

Monitore:

• estado atual por serviço;
• mudanças de estado;
• duração das verificações;
• dependência causadora;
• flapping;
• tempo de startup;
• tempo de drenagem;
• chamadas Check e streams Watch ativos.

Não use health como monitoramento completo

Health checking decide roteamento, não substitui SLO, métricas, traces e alertas. Uma instância pode responder SERVING e ainda ter latência ruim.

Testes

• estado inicial não pronto;
• transição após startup;
• serviço desconhecido;
• dependência obrigatória falha;
• dependência opcional falha;
• histerese;
• Watch recebe mudanças;
• listener removido no cancelamento;
• SIGTERM marca não pronto antes do shutdown.

Erros comuns

• sempre retornar SERVING;
• consultar todas as dependências em cada Check;
• liveness dependente de serviço externo;
• vazar detalhes internos;
• não marcar NOT_SERVING no shutdown;
• flapping sem histerese;
• Watch com listeners vazando;
• confundir health com monitoramento.

Conclusão

gRPC Health Checking no Node.js fornece uma interface padronizada para balanceadores e orquestradores. O valor está em representar prontidão real sem transformar cada probe em uma bateria cara de testes.

Mantenha estado atualizado, diferencie dependências obrigatórias e opcionais, use histerese e marque não pronto antes de drenar. Combine o protocolo com métricas e SLOs para observar qualidade, não apenas disponibilidade binária.

Consulte o protocolo oficial de health checking do gRPC e o guia oficial de health checking.