> ## 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.
# Salud y readiness
> El contrato de sondas de liveness, readiness y versión que expone cada servicio de Lerian: los endpoints `/health`, `/readyz` y `/version`, sus formas de respuesta, el comportamiento de arranque y apagado, y la cobertura por servicio.
La mayoría de los servicios desplegables de Lerian exponen los mismos tres endpoints HTTP operativos —`/health`, `/readyz` y `/version`— en su puerto de aplicación principal. Los orquestadores como Kubernetes los usan para decidir cuándo un servicio está activo, cuándo puede recibir tráfico y qué build se está ejecutando. Este es el contrato de sondas estándar, no una garantía para cada servicio: algunos componentes —workers y sidecars— exponen solo un subconjunto. La [tabla de cobertura por servicio](#cobertura-por-servicio) de abajo es la autoridad para las excepciones.
## Los endpoints de sonda
| Endpoint | Método | Propósito | Estado | Auth |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ----------------------- |
| `/health` | GET | **Liveness.** Confirma que el proceso está activo. Devuelve `200` con el cuerpo `healthy`. | `200` | Pública (antes de auth) |
| `/readyz` | GET | **Readiness.** Confirma que todas las dependencias son alcanzables. Devuelve `200` cuando está listo, `503` cuando alguna dependencia está caída o degradada. | `200` / `503` | Pública (antes de auth) |
| `/version` | GET | **Información de build.** Devuelve la versión en ejecución y los metadatos de build. | `200` | Pública (antes de auth) |
La grafía es exactamente `/health` y `/readyz`, no `/healthz` ni `/livez`. Las tres sondas se registran en el puerto de aplicación principal, **antes** del middleware de autenticación (son sondas públicas), y se excluyen de los logs de acceso y del rastreo de peticiones.
## El cuerpo de respuesta de `/readyz`
`/readyz` devuelve un documento JSON que describe la readiness general y cada comprobación de dependencia.
```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` | Readiness general: `healthy` o `unhealthy`. |
| `checks` | Una entrada por dependencia (Postgres, MongoDB, Redis, RabbitMQ, systemplane y otras). |
| `checks..status` | Resultado por dependencia: `up`, `down`, `degraded`, `skipped` o `n/a`. |
| `checks..latency_ms` | Latencia de ida y vuelta de la sonda en milisegundos, cuando se mide. |
| `checks..tls` | Si la conexión a esa dependencia usa TLS. |
| `checks..breaker_state` | Estado del circuit breaker, cuando un breaker antecede a la dependencia. |
| `checks..error` / `.reason` | Detalle del fallo o el motivo por el que se omitió una comprobación. Saneado en `saas` y `byoc`; detallado en `local`. |
| `version` | Versión del servicio en ejecución. |
| `deployment_mode` | El [`DEPLOYMENT_MODE`](/es/reference/byoc-configuration#modo-de-despliegue-y-tls) activo: `local`, `saas` o `byoc`. |
**El vocabulario de estado** es un conjunto cerrado:
* `status` general: `healthy` o `unhealthy`.
* `status` por comprobación: `up`, `down`, `degraded`, `skipped`, `n/a`.
`/readyz` devuelve HTTP `200` solo cuando el estado general es `healthy`. Si **cualquier** comprobación es `down` o `degraded`, devuelve HTTP `503`.
## Comportamiento de arranque y apagado
Las sondas están cableadas para que un orquestador nunca enrute tráfico a un servicio que no puede atenderlo.
* **Autoprueba de arranque.** `/readyz` devuelve `503` ("server not ready") hasta que el listener está activo y las dependencias son alcanzables, de modo que un pod que está arrancando no se añade prematuramente a un balanceador de carga, aunque `/health` ya responda `200`.
* **Drenaje ordenado.** Ante un `SIGTERM`, el servicio cambia `/readyz` a `503` durante una ventana de drenaje (unos 12 segundos) mientras `/health` sigue en `200`. Los orquestadores dejan de enrutar tráfico nuevo durante la ventana y, después, el proceso termina una vez que se drena el trabajo en curso. La ventana es ajustable mediante `READYZ_DRAIN_DELAY_SEC` (algunos servicios usan `READYZ_DRAIN_GRACE_SECONDS`).
* **Modo de despliegue.** El `DEPLOYMENT_MODE` activo se refleja en el cuerpo de `/readyz`. En modo `saas`, una dependencia alcanzada sin TLS hace fallar la comprobación de readiness (y de arranque); en `byoc` se recomienda pero no se impone.
## Readiness multi-tenant
Cuando el [multi-tenancy](/es/reference/byoc-configuration#multi-tenancy) está habilitado, el servicio añade una sonda de readiness por tenant protegida por auth:
```
GET /readyz/tenant/{id}
```
Ejecuta las comprobaciones de readiness contra las conexiones resueltas de un único tenant. El `/readyz` global reporta las comprobaciones con alcance de tenant como `n/a` y apunta a la ruta por tenant.
## Cobertura por servicio
Cada servicio de la lista siguiente expone `/health` (liveness) y `/readyz` (readiness) en su puerto principal. La tabla lista los puertos por defecto, la sonda multi-tenant donde aplica y las dos desviaciones de ruta.
| Producto / servicio | Puerto principal | Liveness | Readiness | Readyz multi-tenant | Notas |
| ----------------------------------------- | ------------------------------ | ------------------------- | -------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Midaz ledger | 3002 | `/health` | `/readyz` | — | También `/version`. Sin `/metrics` (push OTLP). |
| Tracer | 4020 | `/health` | `/readyz` | — | `/version`, `/metrics`. Costura gRPC de reserva opcional (desactivada por defecto). |
| Reporter (API) | 4005 | `/health` | `/readyz` | — | `/version`. Se ejecuta cuando `RUN_MODE=api`. |
| Reporter (worker) | 4006 | `/health` | `/readyz` | — | Servidor de salud de worker dedicado (`RUN_MODE=worker`). |
| Flowker (API) | 4021 | `/health` | `/readyz` | — | `/metrics`, `/version`. |
| Flowker (worker) | 4022 | `/health` | `/readyz` | — | Puerto de salud del worker. |
| Flowker (sidecar validador XSD) | 8081 | `/health` | — | — | Solo liveness. |
| Fetcher (manager) | 4006 | `/health` | `/readyz` | Sí | `/metrics`. |
| Fetcher (worker) | 4007 | `/health` | `/readyz` | Sí | `/metrics`. Servidor de salud de worker dedicado. |
| Matcher | 4018 | `/health` | `/readyz` | — | `/version`. Expone la [API de administración de Systemplane](/es/reference/systemplane/overview). |
| Lender | 8080 | `/health` | `/readyz` | — | `/version`. Los receptores de webhook exponen sus propios `/health` y `/readyz`. API de administración de Systemplane. |
| Access Manager | 4000 (auth), 8000 (authorizer) | `/health` | `/readyz` | — | Dos servidores, cada uno con sus propias sondas. |
| Fees | 4002 | `/health` | `/readyz` | — | Parte de Midaz; desplegable de forma independiente. |
| Pix — Directo, vía JD | 8080 | `/health` | `/readyz` | Sí | `/metrics`, `/version`. API de administración de Systemplane. |
| Pix — Indirecto, vía BTG | 4014 | `/health` | `/readyz` (+ `/ready`) | — | **Desviación:** la API responde adicionalmente a `/ready` junto a `/readyz`. Multicomponente (API más workers). |
| Conmutador Pix | Varía (componente dedicado) | `/health` | `/readyz` | — | Por adaptador; Systemplane se ejecuta como un componente desplegable separado. |
| TED — vía JD | 4027 | `/health`, `/health/live` | `/readyz`, `/health/ready` | — | **Desviación:** expone adicionalmente `/health/live` y `/health/ready`. API de administración de Systemplane. |
| Boleto y pago de cuentas — vía BTG | 8080 | `/health` | `/readyz` | Sí | Multicomponente. |
| CCS | 4030 (HTTP), 7001 (gRPC) | `/health` | `/readyz` | Sí | `/metrics`, `/version`. API de administración de Systemplane. |
| STA | 4028 | `/health` | `/readyz` | Sí | `/metrics`, `/version`. API de administración de Systemplane. |
| SISBAJUD | 4029 | `/health` | `/readyz` | Sí | `/metrics`, `/version`. API de administración de Systemplane. |
| SLC | 4111 | `/health` | `/readyz` | Sí | `/metrics`, `/version`. API de administración de Systemplane. |
| SPI | 8080 | `/health` | `/readyz` | — | API de administración de Systemplane. |
| SPB | Varía | `/health` | `/readyz` | — | API de administración de Systemplane. |
| SILOC | Varía | `/health` | `/readyz` | — | — |
| Consignado | 8080 | `/health` | `/readyz` | Sí | `/metrics`, `/version`. API de administración de Systemplane. |
| Intercambio de archivos SPB (BC-Correios) | 9090 | `/health` (Live) | `/readyz` (Ready) | — | **Desviación:** `/health` se asigna al handler de liveness (Live) y `/readyz` al de readiness (Ready). API de administración de Systemplane (catálogo). |
**Readyz multi-tenant** se marca como `Sí` donde el servicio registra `GET /readyz/tenant/{id}`; aparece cuando el multi-tenancy está habilitado. Un `—` significa que no se registra ninguna sonda dedicada por tenant para ese servicio.
**Los puertos** son valores por defecto de compose/`.env.example` y pueden sobrescribirse por despliegue; consulta [Puertos de red por defecto](/es/reference/default-network-ports). `Varía` marca un servicio cuyo puerto por defecto depende de la configuración del despliegue.