Ir al contenido
AppsSDAR

Un /health que no consulta la base de datos está mintiendo

Por actualizada el 8 min de lectura Backend y seguridad

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:

  1. Con la base viva: curl -i https://tu-sistema/health debe devolver 200 con db: "ok" y un tiempo bajo.
  2. Detén PostgreSQL un momento (o cambia la contraseña en el .env local) y repite el curl: debe devolver 503 en menos de unos 2 segundos y con Retry-After.
  3. 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.
  4. 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.
  5. 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 1 y tiempo límite de un par de segundos.
  • El pool tiene connectionTimeoutMillis y un manejador pool.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.json incluido 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.