Salud y readiness

Referencia del contrato de sondas /health, /readyz y /version expuesto por todos los servicios de Lerian, con las formas de respuesta y el comportamiento de arranque y apagado.

La mayoría de los servicios desplegables de Lerian exponen los mismos tres endpoints HTTP operacionales en su puerto de aplicación principal: /health, /readyz y /version. Los orquestadores como Kubernetes los usan para decidir cuándo un servicio está vivo, cuándo puede recibir tráfico y qué build ejecuta. Este es el contrato de sondas estándar, no una garantía para todos los servicios. Algunos componentes (workers y sidecars) exponen solo un subconjunto. La tabla de cobertura por servicio a continuación es la referencia autoritativa para las excepciones.

​

Los endpoints de las sondas

Endpoint	Método	Propósito	Estado	Auth
/health	GET	Liveness. Confirma que el proceso está activo. Devuelve 200 con el cuerpo healthy.	200	Público (antes de la autenticación)
/readyz	GET	Readiness. Confirma que todas las dependencias son accesibles. Devuelve 200 cuando está listo y 503 cuando alguna dependencia está caída o degradada.	200 / 503	Público (antes de la autenticación)
/version	GET	Información de build. Devuelve la versión en ejecución y los metadatos del build.	200	Público (antes de la autenticación)

Las rutas se escriben exactamente /health y /readyz, no /healthz ni /livez. Las tres sondas están en el puerto de aplicación principal, antes del middleware de autenticación. Son sondas públicas y quedan fuera de los logs de acceso y del tracing de solicitudes.

​

El cuerpo de la respuesta de /readyz

/readyz devuelve un documento JSON que describe la readiness general y cada verificación de dependencia.

{
  "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.<dep>.status	Resultado por dependencia: up, down, degraded, skipped o n/a.
checks.<dep>.latency_ms	Latencia de ida y vuelta de la sonda en milisegundos, cuando se mide.
checks.<dep>.tls	Si la conexión con esa dependencia usa TLS.
checks.<dep>.breaker_state	Estado del circuit breaker, cuando un breaker antecede a la dependencia.
checks.<dep>.error / .reason	Detalle del fallo o el motivo por el que se omitió una verificación. Saneado en saas y byoc; detallado en local.
version	Versión del servicio en ejecución.
deployment_mode	El DEPLOYMENT_MODE activo: local, saas o byoc.

Vocabulario de estado es un conjunto cerrado:

• status general: healthy o unhealthy.
• status por verificación: up, down, degraded, skipped, n/a.

/readyz devuelve HTTP 200 solo cuando el estado general es healthy. Si alguna verificación está down o degraded, devuelve HTTP 503.

​

Comportamiento de arranque y apagado

Las sondas evitan que un orquestador enrute tráfico hacia un servicio que no puede atenderlo.

• Autochequeo de arranque. /readyz devuelve 503 (“servidor no listo”) hasta que el listener está activo y las dependencias son accesibles. Por lo tanto, un balanceador de carga no recibe un pod en arranque de forma prematura, incluso si /health ya responde 200.
• Drenaje elegante. Al recibir SIGTERM, el servicio cambia /readyz a 503 durante una ventana de drenaje (unos 12 segundos) mientras /health permanece en 200. Los orquestadores dejan de enrutar tráfico nuevo durante la ventana y luego el proceso termina una vez que el trabajo en curso se drena. La ventana es configurable mediante READYZ_DRAIN_DELAY_SEC (algunos servicios usan READYZ_DRAIN_GRACE_SECONDS).
• Modo de despliegue. El cuerpo de /readyz reporta el DEPLOYMENT_MODE activo. En modo saas, una dependencia alcanzada sin TLS hace fallar la verificación de readiness (y de arranque). En byoc, TLS es una recomendación, no un requisito.

​

Readiness multi-tenant

Cuando habilitas multi-tenancy, el servicio agrega una sonda de readiness por tenant protegida por autenticación:

GET /readyz/tenant/{id}

Ejecuta las verificaciones de readiness contra las conexiones resueltas de un único tenant. El /readyz global reporta las verificaciones con alcance de tenant como n/a y apunta a la ruta por tenant.

​

Cobertura por servicio

Todos los servicios que se muestran a continuación exponen /health (liveness) y /readyz (readiness) en su puerto principal. La tabla lista los puertos predeterminados, la sonda multi-tenant donde aplica y las dos desviaciones de ruta.

Producto / servicio	Puerto principal	Liveness	Readiness	Multi-tenant readyz	Notas
Midaz ledger	3002	/health	/readyz	—	También /version. Sin /metrics (OTLP push).
Tracer	4020	/health	/readyz	—	/version, /metrics. Interfaz 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 dedicado para el worker (RUN_MODE=worker).
Flowker (API)	4021	/health	/readyz	—	/metrics, /version.
Flowker (worker)	4022	/health	/readyz	—	Puerto de salud del worker.
Flowker (sidecar validador de XSD)	8081	/health	—	—	Solo liveness.
Matcher	4018	/health	/readyz	—	/version. Expone la API de administración de systemplane.
Lender	8080	/health	/readyz	—	/version. Los receptores de webhook exponen sus propios /health y /readyz. API de administración de systemplane.
Access Manager	4000 (autenticación), 8000 (autorizador)	/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	Yes	/metrics, /version. API de administración de systemplane.
Pix — Indirecto, vía BTG	4014	/health	/readyz (+ /ready)	—	Desviación: la API además responde en /ready junto con /readyz. Multicomponente (API más workers).
Switch de Pix	Varies (componente dedicado)	/health	/readyz	—	Por adaptador; systemplane se ejecuta como un componente desplegable independiente.
TED — vía JD	4027	/health, /health/live	/readyz, /health/ready	—	Desviación: además expone /health/live y /health/ready. API de administración de systemplane.
Boleto y pagos de facturas — vía BTG	8080	/health	/readyz	Yes	Multicomponente.
CCS	4030 (HTTP), 7001 (gRPC)	/health	/readyz	Yes	/metrics, /version. API de administración de systemplane.
STA	4028	/health	/readyz	Yes	/metrics, /version. API de administración de systemplane.
SISBAJUD	4029	/health	/readyz	Yes	/metrics, /version. API de administración de systemplane.
SLC	4111	/health	/readyz	Yes	/metrics, /version. API de administración de systemplane.
SPI	8080	/health	/readyz	—	API de administración de systemplane.
SPB	Varies	/health	/readyz	—	API de administración de systemplane.
SILOC	Varies	/health	/readyz	—	—
Consignado	8080	/health	/readyz	Yes	/metrics, /version. API de administración de systemplane.
Intercambio de archivos SPB (BC Correios)	9090	/health (Live)	/readyz (Ready)	—	Desviación: /health mapea al handler de liveness (Live) y /readyz al handler de readiness (Ready). API de administración de systemplane (catálogo).

Multi-tenant readyz muestra Yes donde el servicio registra GET /readyz/tenant/{id}. La ruta aparece cuando habilitas multi-tenancy. Un — significa que el servicio no registra una sonda dedicada por tenant.

Puertos son los valores predeterminados de compose/.env.example y se pueden sobrescribir por despliegue. Consulta Puertos de red predeterminados. Varies marca un servicio cuyo puerto predeterminado depende de la configuración de despliegue.