Saúde e prontidão

A maioria dos serviços Lerian implantáveis expõe os mesmos três endpoints HTTP operacionais —/health, /readyz e /version— em sua porta de aplicação principal. Orquestradores como o Kubernetes os usam para decidir quando um serviço está vivo, quando ele pode receber tráfego e qual build está em execução. Este é o contrato de sondas padrão, não uma garantia para todo serviço: alguns componentes —workers e sidecars— expõem apenas um subconjunto. A tabela de cobertura por serviço abaixo é a autoridade para as exceções.

Os endpoints de sonda

Endpoint	Método	Propósito	Status	Autenticação
`/health`	GET	Liveness. Confirma que o processo está no ar. Retorna `200` com corpo `healthy`.	`200`	Público (antes da autenticação)
`/readyz`	GET	Readiness. Confirma que toda dependência está acessível. Retorna `200` quando pronto, `503` quando alguma dependência está fora do ar ou degradada.	`200` / `503`	Público (antes da autenticação)
`/version`	GET	Informações de build. Retorna a versão em execução e os metadados de build.	`200`	Público (antes da autenticação)

As grafias são exatamente /health e /readyz — não /healthz nem /livez. As três sondas são registradas na porta de aplicação principal, antes do middleware de autenticação (são sondas públicas), e são excluídas dos logs de acesso e do tracing de requisições.

O corpo da resposta de `/readyz`

/readyz retorna um documento JSON que descreve a prontidão geral e cada verificação de dependência.

{
  "status": "healthy",
  "checks": {
    "postgres": { "status": "up", "latency_ms": 2, "tls": true },
    "redis":    { "status": "skipped", "reason": "not configured" },
    "rabbitmq": { "status": "degraded", "breaker_state": "half-open", "latency_ms": 12 }
  },
  "version": "1.2.3",
  "deployment_mode": "byoc"
}

Campo	Significado
`status`	Prontidão geral: `healthy` ou `unhealthy`.
`checks`	Uma entrada por dependência (Postgres, MongoDB, Redis, RabbitMQ, systemplane e outras).
`checks.<dep>.status`	Resultado por dependência: `up`, `down`, `degraded`, `skipped` ou `n/a`.
`checks.<dep>.latency_ms`	Latência de ida e volta da sonda em milissegundos, quando medida.
`checks.<dep>.tls`	Se a conexão com aquela dependência usa TLS.
`checks.<dep>.breaker_state`	Estado do circuit-breaker, quando um breaker protege a dependência.
`checks.<dep>.error` / `.reason`	Detalhe da falha ou o motivo pelo qual uma verificação foi ignorada. Sanitizado em `saas` e `byoc`; detalhado em `local`.
`version`	Versão em execução do serviço.
`deployment_mode`	O `DEPLOYMENT_MODE` ativo: `local`, `saas` ou `byoc`.

O vocabulário de status é um conjunto fechado:

status geral: healthy ou unhealthy.
status por verificação: up, down, degraded, skipped, n/a.

/readyz retorna HTTP 200 apenas quando o status geral é healthy. Se qualquer verificação estiver down ou degraded, ele retorna HTTP 503.

Comportamento de inicialização e desligamento

As sondas são conectadas de modo que um orquestrador nunca roteie tráfego para um serviço que não consegue atendê-lo.

Autoverificação de inicialização. /readyz retorna 503 (“server not ready”) até que o listener esteja no ar e as dependências estejam acessíveis — para que um pod em inicialização não seja adicionado prematuramente a um load balancer, mesmo que /health já responda 200.
Drenagem controlada. No SIGTERM, o serviço vira /readyz para 503 durante uma janela de drenagem (cerca de 12 segundos) enquanto /health permanece 200. Os orquestradores param de rotear novo tráfego durante a janela e, depois, o processo sai assim que o trabalho em andamento se esgota. A janela é ajustável via READYZ_DRAIN_DELAY_SEC (alguns serviços usam READYZ_DRAIN_GRACE_SECONDS).
Modo de implantação. O DEPLOYMENT_MODE ativo é refletido no corpo de /readyz. No modo saas, uma dependência acessada sem TLS reprova a verificação de prontidão (e de boot); em byoc ela é recomendada, mas não imposta.

Prontidão multi-tenant

Quando o multi-tenancy está ativado, o serviço adiciona uma sonda de prontidão por tenant, protegida por autenticação:

GET /readyz/tenant/{id}

Ela executa as verificações de prontidão contra as conexões resolvidas de um único tenant. O /readyz global reporta as verificações com escopo de tenant como n/a e aponta para a rota por tenant.

Cobertura por serviço

Todo serviço abaixo expõe /health (liveness) e /readyz (readiness) em sua porta principal. A tabela lista as portas padrão, a sonda multi-tenant onde ela se aplica e os dois desvios de caminho.

Produto / serviço	Porta principal	Liveness	Readiness	Readyz multi-tenant	Observações
Ledger do Midaz	3002	`/health`	`/readyz`	—	Também `/version`. Sem `/metrics` (push OTLP).
Tracer	4020	`/health`	`/readyz`	—	`/version`, `/metrics`. Seam gRPC de reserva opcional (desativado por padrão).
Reporter (API)	4005	`/health`	`/readyz`	—	`/version`. Roda quando `RUN_MODE=api`.
Reporter (worker)	4006	`/health`	`/readyz`	—	Servidor de saúde dedicado do worker (`RUN_MODE=worker`).
Flowker (API)	4021	`/health`	`/readyz`	—	`/metrics`, `/version`.
Flowker (worker)	4022	`/health`	`/readyz`	—	Porta de saúde do worker.
Flowker (sidecar validador de XSD)	8081	`/health`	—	—	Apenas liveness.
Fetcher (manager)	4006	`/health`	`/readyz`	Sim	`/metrics`.
Fetcher (worker)	4007	`/health`	`/readyz`	Sim	`/metrics`. Servidor de saúde dedicado do worker.
Matcher	4018	`/health`	`/readyz`	—	`/version`. Expõe a API de administração do systemplane.
Lender	8080	`/health`	`/readyz`	—	`/version`. Os receptores de webhook expõem seus próprios `/health` e `/readyz`. API de administração do systemplane.
Access Manager	4000 (auth), 8000 (authorizer)	`/health`	`/readyz`	—	Dois servidores, cada um com suas próprias sondas.
Fees	4002	`/health`	`/readyz`	—	Parte do Midaz; implantável de forma independente.
Pix — Direto, via JD	8080	`/health`	`/readyz`	Sim	`/metrics`, `/version`. API de administração do systemplane.
Pix — Indireto, via BTG	4014	`/health`	`/readyz` (+ `/ready`)	—	Desvio: a API responde adicionalmente a `/ready` junto de `/readyz`. Multicomponente (API mais workers).
Switch Pix	Varia (componente dedicado)	`/health`	`/readyz`	—	Por adaptador; o systemplane roda como um componente implantável separado.
TED — via JD	4027	`/health`, `/health/live`	`/readyz`, `/health/ready`	—	Desvio: expõe adicionalmente `/health/live` e `/health/ready`. API de administração do systemplane.
Boleto e pagamento de contas — via BTG	8080	`/health`	`/readyz`	Sim	Multicomponente.
CCS	4030 (HTTP), 7001 (gRPC)	`/health`	`/readyz`	Sim	`/metrics`, `/version`. API de administração do systemplane.
STA	4028	`/health`	`/readyz`	Sim	`/metrics`, `/version`. API de administração do systemplane.
SISBAJUD	4029	`/health`	`/readyz`	Sim	`/metrics`, `/version`. API de administração do systemplane.
SLC	4111	`/health`	`/readyz`	Sim	`/metrics`, `/version`. API de administração do systemplane.
SPI	8080	`/health`	`/readyz`	—	API de administração do systemplane.
SPB	Varia	`/health`	`/readyz`	—	API de administração do systemplane.
SILOC	Varia	`/health`	`/readyz`	—	—
Consignado	8080	`/health`	`/readyz`	Sim	`/metrics`, `/version`. API de administração do systemplane.
Troca de arquivos SPB (BC Correios)	9090	`/health` (Live)	`/readyz` (Ready)	—	Desvio: `/health` mapeia para o handler de liveness (Live) e `/readyz` para o handler de readiness (Ready). API de administração do systemplane (catálogo).

Readyz multi-tenant é marcado como Sim onde o serviço registra GET /readyz/tenant/{id}; ele aparece quando o multi-tenancy está ativado. Um — significa que nenhuma sonda por tenant dedicada está registrada para aquele serviço.As portas são padrões de compose/.env.example e podem ser sobrescritas por implantação — veja Portas de rede padrão. Varia marca um serviço cuja porta padrão depende da configuração de implantação.

Visão geral

Fundamentos de integração

Estabilidade e qualidade

Saúde e prontidão

Os endpoints de sonda

O corpo da resposta de `/readyz`

Comportamento de inicialização e desligamento

Prontidão multi-tenant

Cobertura por serviço

​Os endpoints de sonda

​O corpo da resposta de /readyz

​Comportamento de inicialização e desligamento

​Prontidão multi-tenant

​Cobertura por serviço

Os endpoints de sonda

O corpo da resposta de `/readyz`

Comportamento de inicialização e desligamento

Prontidão multi-tenant

Cobertura por serviço