> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Saúde e prontidão
> O contrato de sondas de liveness, readiness e versão exposto por todo serviço Lerian — os endpoints `/health`, `/readyz` e `/version`, seus formatos de resposta, o comportamento de inicialização e desligamento, e a cobertura por serviç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](#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.
```json theme={null}
{
"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..status` | Resultado por dependência: `up`, `down`, `degraded`, `skipped` ou `n/a`. |
| `checks..latency_ms` | Latência de ida e volta da sonda em milissegundos, quando medida. |
| `checks..tls` | Se a conexão com aquela dependência usa TLS. |
| `checks..breaker_state` | Estado do circuit-breaker, quando um breaker protege a dependência. |
| `checks..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`](/pt/reference/byoc-configuration#modo-de-implantação-e-tls) 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](/pt/reference/byoc-configuration#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](/pt/reference/systemplane/overview). |
| 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](/pt/reference/default-network-ports). `Varia` marca um serviço cuja porta padrão depende da configuração de implantação.