BIGboss248/nextjs-wordpress

Habilidad de Health Check y Observabilidad para Next.js (nextjs-healthcheck)

Un flujo de trabajo modular y listo para producción para crear y mantener endpoints de health check (/api/health), sondas de salud de Docker Compose sin dependencias y métricas de tiempo de ejecución de Node.js en aplicaciones Next.js App Router.

---

Resumen del Flujo de Trabajo

flowchart TD
    A["1. Escanear Proyecto<br/>(Base de Datos y Docker Compose)"] --> B["2. Generar /api/health<br/>(Plantillas con Métricas)"]
    B --> C["3. Inyectar Sondas Docker<br/>(docker-compose.yml)"]
    C --> D["4. Verificar y Validar<br/>(curl & docker compose ps)"]

---

Manual de Ejecución Paso a Paso

Sigue esta lista de verificación secuencialmente para implementar y verificar el monitoreo de salud de la aplicación:

1. Descubrimiento del Proyecto e Inspección de Dependencias

• Ubicar la Ruta del Manejador de Rutas: Determina si el proyecto usa app/ o src/app/ (objetivo: app/api/health/route.ts o src/app/api/health/route.ts).
• Detectar Base de Datos / Almacenes Externos: Escanea package.json en busca de ORMs y clientes (Prisma, Drizzle, Supabase, Mongoose, PostgreSQL, Redis). Consulta database-probes.md.
• Ubicar Archivos Docker Compose: Descubre docker-compose.yml, docker-compose.prod.yml u otras pilas de compose. Consulta docker-compose-probes.md.

2. Implementar el Manejador de Ruta de Health Check

• Seleccionar Plantilla de Ruta:
  • Si No hay Base de Datos: Despliega route-no-db.ts.template.
  • Si Hay Base de Datos: Despliega route-with-db.ts.template y conecta el cliente de base de datos específico del proyecto con un tiempo de espera estricto de 2 segundos.
• Forzar Ejecución Dinámica: Asegúrate de que export const dynamic = "force-dynamic"; y los encabezados Cache-Control: no-store, no-cache, must-revalidate estén presentes.
• Configurar Métricas No Bloqueantes: Recopila la saturación del heap V8, el retardo del bucle de eventos ($p99$ lag via perf_hooks) y el tiempo de actividad del proceso. Consulta status-and-metrics.md.
• Aplicar Disciplina de Códigos de Estado HTTP: Devuelve 200 OK para healthy/degraded y 503 Service Unavailable para unhealthy.

3. Configurar Sondas de Salud de Docker Compose

• Identificar Servicios Next.js: Inspecciona los archivos de compose detectados en busca de bloques de servicio Next.js (nextjs-app, web, app).
• Inyectar Bloque de Healthcheck: Agrega la sonda de salud de Node.js sin dependencias desde docker-compose.healthcheck.template.yml.

4. Verificación y Pruebas

• Prueba de API Local:

  curl -i http://localhost:3000/api/health
  

  Verifica la respuesta HTTP 200 con un payload JSON válido (status, timestamp, uptimeSeconds, checks).
• Verificación del Estado de Salud de Compose:

  docker compose ps
  

  Verifica que las transiciones de estado del servicio a (healthy) después del período de inicio inicial.

---

Casos Extremos y Errores Conocidos de IA

[!WARNING]

• Falta de force-dynamic: Next.js App Router puede evaluar o almacenar en caché las respuestas de ruta estáticamente si se omite export const dynamic = "force-dynamic", causando marcas de tiempo obsoletas y métricas de tiempo de actividad congeladas.
• Conexiones de Base de Datos Colgadas: Nunca consultes bases de datos externas sin un tiempo de espera máximo (2000ms). La latencia de red no manejada puede provocar el agotamiento del grupo de solicitudes.
• Dependencias de Herramientas Externas en Contenedores: No confíes en curl o wget en los health checks de Docker; las imágenes mínimas de producción (p. ej., node:alpine o distroless) a menudo carecen de ellos. Usa fetch nativo de Node.js a través de node -e.
• Fugas de Secretos: Nunca imprimas URLs de conexión a la base de datos, contraseñas ni trazas de error internas sin procesar en el payload de respuesta pública de /api/health.

---

Esquema del Resumen de Salida

Al completar la configuración del health check, proporciona un informe resumido conciso:

### Configuración de Monitoreo de Salud Completa

- **Manejador de Ruta**: `[app/api/health/route.ts](file:///...)`
- **Sondas de Base de Datos**: [Configurado: Prisma / Drizzle / Ninguna] (Tiempo de espera: 2000ms)
- **Métricas de Tiempo de Ejecución**: Saturación del Heap V8 y Retardo del Bucle de Eventos (p99)
- **Pilas de Docker Compose Actualizadas**: `docker-compose.yml`, `docker-compose.prod.yml`
- **Estado de Verificación**: PASADO (HTTP 200 / Contenedor Saludable)

---

Guías de Referencia y Plantillas

• Referencia de Códigos de Estado y Métricas: Matriz de estado arquitectónico, fórmulas de memoria y umbrales de latencia.
• Referencia de Sondas de Base de Datos: Lista de verificación de detección, envoltura de tiempo de espera y patrones de sonda ORM.
• Referencia de Sondas Docker Compose: Reglas de coincidencia de servicios y definiciones de fetch sin dependencias.
• Plantilla de Ruta (Sin BD): Manejador de ruta completo para aplicaciones sin estado.
• Plantilla de Ruta (Con BD): Manejador de ruta completo con sondas de dependencias.
• Plantilla de Healthcheck de Docker Compose: Fragmento de compose reutilizable.