Un /health que no consulta la base de datos está mintiendo
Casi todo sistema en producción termina con un endpoint
/health que un panel de monitoreo consulta cada pocos
minutos. El error más común, y el más fácil de cometer sin notarlo, es
que responda 200 OK solo porque el proceso sigue corriendo,
sin comprobar nada de lo que ese proceso necesita para funcionar.
Esta nota sale de un caso real. Al auditar nuestros propios sistemas
encontramos que dos de ellos, SortealoPE
y Arca, llevaban meses en producción con un /health que
devolvía 200 incluso con la base de datos caída. El panel estaba verde y
nadie se enteraba. Lo que sigue es cómo debe responder un health check
para que su verde signifique algo, qué trampas aparecen al corregirlo y
cómo probarlo.
Un proceso vivo no es un sistema funcionando
Node.js sigue atendiendo peticiones HTTP aunque la conexión a PostgreSQL
haya muerto hace diez minutos. Si el endpoint solo hace
res.send('ok'), el monitor ve verde mientras iniciar sesión,
guardar un pedido o confirmar un pago fallan en silencio. Es el peor
momento para mentir: el health check existe justo para ese caso.
El código de estado es lo que mira un monitor automático. Un
200 con {"db":"error"} en el cuerpo
cuenta como éxito para cualquier herramienta que solo compare el código,
y casi todas lo hacen. Kubernetes, por ejemplo, define el éxito de una
sonda HTTP así: cualquier código mayor o igual a 200 y menor que 400 es
éxito, y cualquier otro es fallo
(documentación de sondas de Kubernetes).
Aunque no uses Kubernetes, la convención es la misma: el estado HTTP es
el veredicto, el cuerpo es solo explicación para humanos.
Qué debe verificar de verdad
Una consulta real, barata y con tiempo límite contra cada dependencia sin
la cual el sistema no puede cumplir su función. Para casi todos nuestros
sistemas eso es una sola: SELECT 1 contra PostgreSQL. Si
responde a tiempo, 200. Si falla o tarda demasiado, 503.
El 503 es el código correcto porque el estándar HTTP lo define para
exactamente esta situación: el servidor no puede atender la petición en
este momento, normalmente por sobrecarga o mantenimiento, y puede indicar
cuánto esperar con la cabecera Retry-After, cuyo valor es
una fecha HTTP o un número de segundos
(RFC 9110, sección 15.6.4).
Un 500 sugiere un bug en el código; un 503 dice "el proceso está bien,
algo de lo que depende no".
La implementación mínima
En Express con pg queda en pocas líneas. Lo importante no es
la consulta, sino el tiempo límite:
app.get('/health', async (req, res) => {
const inicio = Date.now();
try {
await Promise.race([
pool.query('SELECT 1'),
new Promise((_, rechazar) =>
setTimeout(() => rechazar(new Error('timeout')), 2000)),
]);
res.json({ status: 'ok', db: 'ok', ms: Date.now() - inicio });
} catch (err) {
res.set('Retry-After', '30');
res.status(503).json({ status: 'error', db: 'fail', ms: Date.now() - inicio });
}
}); El cuerpo devuelve el estado y los milisegundos, nunca el mensaje del error: ese texto puede traer el nombre del servidor de base de datos o del usuario, y este endpoint suele ser público.
Trampa 1: el pool agotado también cuelga el health check
pool.query toma un cliente libre del pool. Según la
documentación de node-postgres, si todos los clientes están en uso las
peticiones esperan en una cola, y con connectionTimeoutMillis
en su valor por defecto (0) esa espera puede no terminar nunca
(node-postgres, Pool).
El tamaño por defecto del pool es 10 clientes.
Consecuencia práctica: si una fuga de clientes (un
pool.connect() sin su release()) agota el
pool, tu SELECT 1 queda en cola igual que las demás
consultas y el health check no responde nunca. El monitor lo registra
como timeout, que al menos es rojo, pero sin causa. Por eso el
Promise.race de arriba: devuelve un 503 explícito en dos
segundos en vez de dejar la petición colgada. Y por eso conviene fijar
también connectionTimeoutMillis al crear el pool, para que
todo el sistema falle rápido y no solo el health check. El mismo problema
aparece en las pruebas automáticas, lo contamos en
tests que agotan conexiones de Postgres.
Una limitación honesta del Promise.race: la consulta no se
cancela, solo dejas de esperarla. Con un chequeo cada pocos minutos no
importa; si lo consultaras cada segundo, acumularías consultas
pendientes.
Trampa 2: la ruta no está donde crees
Al registrar sistemas en el monitor descubrimos que SortealoPE y Arca
exponen su salud bajo /api/v1/health, no en
/health. Un chequeo apuntando a la raíz recibía la página
de la aplicación con 200 y daba verde por error, o un 404 y daba rojo
permanente. Regla: antes de registrar un sistema, haz un
curl -i a la URL exacta que vas a vigilar y mira el código
y el cuerpo.
Trampa 3: sin base de datos, sin login
No todo sistema tiene base de datos. Una pasarela de pagos pequeña, sin
tablas, puede responder {"status":"ok","uptime":...}
y está bien: no hay nada más que consultar. La regla "consultar la base
de datos" es en realidad "consultar lo que el sistema necesita". Si tu
sistema depende de un proveedor de pagos para su función principal, la
pregunta es si el health check debe llamarlo. Casi nunca: ver la
siguiente sección.
Los sitios estáticos tampoco pueden hacer una consulta. Para ellos basta
un archivo health.json servido por el mismo servidor web.
Detalle que nos mordió: el flujo de despliegue de la landing copiaba una
lista explícita de archivos, así que hay que añadir el
health.json a esa lista o desaparece en el siguiente
deploy y el monitor lo ve caído.
Vivo no es lo mismo que listo
Kubernetes separa dos preguntas que conviene separar también fuera de él. La sonda de liveness detecta un contenedor que entró en un estado roto y solo se arregla reiniciándolo: si falla, el kubelet lo reinicia. La sonda de readiness decide si recibe tráfico: un pod que se reporta como no listo no recibe tráfico de los Services, pero no se reinicia. Además existe la sonda de arranque (startup) para procesos lentos al iniciar (misma documentación).
La consecuencia de diseño, que es criterio nuestro y no texto de la
documentación: lo que consulta la base de datos es una pregunta de
readiness. Si atas el reinicio del proceso a la base de datos y esta
cae, reiniciarías todas las instancias a la vez sin arreglar nada, y
además perderías la conexión que se reconecta sola al volver la base.
Con un monitor externo que solo observa y avisa, como el nuestro, no hay
reinicio automático que temer y un único endpoint basta. Si algún día un
orquestador decide reiniciar por tu endpoint, sepáralo en dos:
/health/live (el proceso responde, sin dependencias) y
/health/ready (con la base de datos).
Por la misma razón, no pongas en el health check a los proveedores externos (pasarela de pagos, correo). Si el proveedor tiene una caída, tu sistema sigue sirviendo todo lo demás y marcarlo como caído es un falso positivo que entrena a ignorar las alertas.
Un aviso que se cree a sí mismo
El health check es solo la mitad. Lo que hace útil al monitor es cómo interpreta lo que recibe, y ahí aprendimos tres reglas:
- Un fallo suelto no es una caída. Una petición que tarda 3 segundos una vez no justifica despertar a nadie. Las alertas de latencia exigen tres chequeos seguidos malos antes de avisar.
- Guardar la causa al confirmar la caída: qué respondió el endpoint (código y primeras líneas del cuerpo, o timeout) y cómo estaba el servidor en ese momento. El estado del servidor no se puede reconstruir después; "X no responde" sin causa es un susto, "X respondió 503 por la base de datos" es un diagnóstico.
- La parada planificada se declara, no se desactiva. Antes de dar de baja un sistema a propósito, se marca una ventana de mantenimiento: los chequeos se siguen guardando, pero no se abre incidente ni sale aviso.
Más detalle del panel en monitorear tus propios sistemas.
Cómo probarlo antes de confiar
Un health check que nunca ha fallado no está probado. Antes de darlo por bueno, hazlo fallar a propósito en un entorno de prueba, no en producción:
-
Con la base viva:
curl -i https://tu-sistema/healthdebe devolver 200 condb: "ok"y un tiempo bajo. -
Detén PostgreSQL un momento (o cambia la contraseña en el
.envlocal) y repite elcurl: debe devolver 503 en menos de unos 2 segundos y conRetry-After. -
Simula la fuga: abre en una consola tantos
pool.connect()como el tamaño del pool sin liberarlos y consulta el health. Debe devolver 503 por timeout, no quedarse colgado. - Vuelve a levantar la base y comprueba que el endpoint recupera el 200 sin reiniciar el proceso. Si no recupera, tienes un problema de reconexión del pool, que es otro bug que el health check acaba de destapar.
- En el panel, confirma que la tarjeta del sistema se puso roja con la causa correcta y volvió a verde.
Un detalle de node-postgres que ayuda en el punto 4: el
pool emite el evento error cuando un cliente inactivo falla
(por ejemplo porque el servidor se cayó), lo descarta, y si no hay un
manejador registrado, Node lanza un error no capturado que puede tumbar
el proceso. Registra siempre
pool.on('error', ...).
Política, no sugerencia
En nuestros sistemas es una regla fija: ninguno llega a producción sin
un /health que consulte lo que necesita y devuelva 503 si
falla, y sin estar registrado en el panel de monitoreo. La diferencia
es concreta: enterarte de la caída por una alerta en minutos, con la
causa a la vista, o enterarte porque un cliente escribe molesto horas
después.
Checklist final
- El endpoint devuelve 503, no 200 con un error en el cuerpo.
- Consulta la base de datos con
SELECT 1y tiempo límite de un par de segundos. - El pool tiene
connectionTimeoutMillisy un manejadorpool.on('error'). - No expone mensajes de error internos.
- No llama a proveedores externos que no puedes arreglar tú.
- Verificaste la URL exacta con
curl -i, incluido el prefijo de la API. - Sitios estáticos:
health.jsonincluido en el despliegue. - Lo hiciste fallar a propósito y viste el rojo, la causa y la recuperación.
- El sistema está registrado en el monitor y la alerta exige varios fallos seguidos.