Heartbeat do integrador-client e alerta de silêncio¶

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-10

O que é¶

Cada instalação do integrador-client (jar on-premise, uma por cliente) manda um heartbeat no startup e a cada 60 min ao integrador-server do próprio cliente, que carimba o cliente_id e o repassa ao central em POST /api/integrador/heartbeat. O central guarda o estado atual da instalação (integrador_instancias, uma linha por cliente), e o SilencioJob alerta no GlitchTip do central quando uma instalação passa de 6 horas úteis sem sinal (07:00–22:00, seg–sex, sem feriado nacional). O porquê está na decisão 0028; o contrato, no api-rest.

A aba Deploy do central-ui mostra as instalações (cliente, versão, fluxos, último heartbeat, situação) e tem o botão Parar de acompanhar.

Configuração¶

Onde	Env	Valor
central-backend — os dois recursos (jar e native)	`CENTRAL_API_TOKEN`	segredo gerado (`openssl rand -hex 32`); Secret no Coolify
integrador-server de cada cliente com integrador-client	`CENTRAL_API_TOKEN`	o mesmo valor do central
integrador-server de cada cliente com integrador-client	`CLIENTE_ID`	o `clientes.cliente_id` do cliente (ex. `maxsul`) — nunca o nome de exibição

Sem CENTRAL_API_TOKEN o central não sobe em prod (IntegradorTokenGuard; o rolling deploy mantém o container anterior no ar). O cliente_id tem de existir em clientes — senão o central responde 422 e loga WARN heartbeat recusado: cliente_id … não existe em clientes. A configuração do lado do integrador-server está no deploy do integrador-server.

Verificação¶

# lista as instalações (JWT xadm_admin do central-ui)
curl -s https://central-backend.xadm.biz/api/admin/integradores \
  -H "Authorization: Bearer <JWT xadm_admin>" | jq .

A instalação aparece sozinha no 1º startup do integrador-client com heartbeat. No log do central, o 1º heartbeat de um cliente sai como INFO integrador-client <cliente> registrado (versão …, fluxos …).

Como ler o alerta¶

Uma issue por cliente no projeto do central no GlitchTip, com a tag cliente=<cliente_id> e a mensagem integrador-client <cliente> sem heartbeat há <X,Y>h úteis (último: <data/hora local>, versão <v>, fluxos <f>). O mesmo texto sai em WARN no log do central.
Um evento por episódio de silêncio. O próximo heartbeat encerra o episódio (log INFO integrador-client <cliente> voltou (silêncio desde …)); o silêncio seguinte manda um evento novo na mesma issue.
Causas prováveis: máquina do cliente desligada, jar parado ou travado, Java trocado, .properties quebrado, ou o integrador-server do cliente fora do ar (aí o write-back também parou).

Resolver × ignorar a issue. Resolvida, ela reabre no episódio seguinte (e notifica). Ignorada, fica muda para sempre — escolha do operador, só para instalação que vai continuar parada.

A notificação depende da regra do projeto do central ser por evento — ver provedor GlitchTip.

Parar de acompanhar¶

Instalação desativada de propósito (cliente saiu, máquina trocada de vez): botão Parar de acompanhar na linha da aba Deploy do central-ui (só aparece em silencioso e cliente_inativo). Com a UI fora:

curl -s -o /dev/null -w '%{http_code}\n' -X DELETE \
  https://central-backend.xadm.biz/api/admin/integradores/<cliente_id> \
  -H "Authorization: Bearer <JWT xadm_admin>"
# → 204 (com ou sem a linha — é idempotente)

Apagar não desliga: se o jar ainda roda, o próximo heartbeat (até 1h) recria a linha. Para desligar de verdade, heartbeat.intervaloMinutos=0 no .properties do client.

Cliente desativado no central (clientes.active = false) não precisa disso: a linha aparece como cliente_inativo e o job não alerta.

Problemas comuns¶

Sintoma	Causa	Ação
central não sobe após deploy; log `CENTRAL_API_TOKEN vazio em prod`	env ausente no recurso	cadastrar nos dois recursos do central
`WARN heartbeat recusado: cliente_id X não existe em clientes`	`CLIENTE_ID` errado no integrador-server, ou cliente não cadastrado	corrigir o `CLIENTE_ID` (chave minúscula) ou cadastrar o cliente
instalação nunca aparece; integrador-server com ERROR `heartbeat_recusado`	`CENTRAL_API_TOKEN` diferente nos dois lados (`401` no central)	igualar o valor
linha `silencioso` que não volta	jar parado na máquina do cliente	ver o log do integrador-client na máquina; se desativado de propósito, parar de acompanhar