Monitorización: logs, healthchecks, Prometheus/Grafana

Quien aloja por su cuenta una instancia de n8n necesita tres elementos para un funcionamiento fiable: logs significativos para la resolución de problemas, un endpoint de healthcheck para la supervisión de disponibilidad y métricas de Prometheus para una visión más profunda de las colas, los webhooks y los formularios. n8n ya incluye estos tres elementos, solo hay que activarlos y conectarlos mediante variables de entorno. Estado: julio de 2026.

Configurar el nivel de log y la salida de logs

n8n utiliza la biblioteca de logging winston y configura la salida de logs según la documentación de n8n sobre logging mediante variables de entorno. Para el uso diario bastan dos ajustes.

• N8N_LOG_LEVEL: controla el nivel de detalle. De menor a mayor están disponibles silent, error, warn, info y debug, el valor por defecto es info. silent no muestra nada, debug ofrece la información de diagnóstico más detallada y es adecuado sobre todo para la resolución de problemas específica.
• N8N_LOG_OUTPUT: determina dónde se registran los logs, console o file, también combinados como console,file. El valor por defecto es console.
• N8N_LOG_FILE_LOCATION: ruta del archivo de log, cuando file está activo. El valor por defecto es <carpeta n8n>/logs/n8n.log.
• N8N_LOG_FILE_SIZE_MAX: tamaño máximo por archivo de log en MB, por defecto 16 MB.
• N8N_LOG_FILE_COUNT_MAX: número máximo de archivos de log conservados, por defecto 100. Con varios workers, este valor debe establecerse de forma consciente para que la rotación se ajuste al espacio de almacenamiento disponible.

En producción, info suele ser suficiente, debug sigue siendo una medida temporal porque escribe notablemente más datos y llena los archivos de log más rápido.

Endpoints de healthcheck para la supervisión de disponibilidad

Según la documentación de n8n sobre monitorización n8n ofrece dos endpoints de salud adecuados para comprobaciones externas de disponibilidad. El endpoint /healthz solo indica si la instancia es accesible, un HTTP 200 no dice nada sobre el estado de la base de datos. El endpoint /healthz/readiness va más allá: solo devuelve 200 cuando la base de datos está conectada y migrada, es decir, cuando la instancia está realmente lista para procesar solicitudes. La ruta se puede adaptar mediante la variable N8N_ENDPOINT_HEALTH, por ejemplo cuando un reverse proxy espera una ruta de salud diferente.

En el servidor principal, el endpoint de salud está siempre activo. En las instancias worker en modo cola, en cambio, está desactivado por defecto y debe activarse mediante QUEUE_HEALTH_CHECK_ACTIVE=true si un balanceador de carga u orquestador también debe comprobar los workers.

Exportar métricas de Prometheus

Para datos operativos más detallados, n8n ofrece un endpoint /metrics mediante la biblioteca prom-client. Está desactivado por defecto y se activa con N8N_METRICS=true, tanto en instancias main como worker. Importante para la operación: el endpoint no debe ser accesible públicamente, sino solo para sistemas internos que consumen los datos de Prometheus, ya que revela detalles operativos de la instancia.

Qué métricas y etiquetas se muestran exactamente lo controlan las variables N8N_METRICS_INCLUDE_*. Para configuraciones de escalado en modo cola, N8N_METRICS_INCLUDE_QUEUE_METRICS=true proporciona indicadores como n8n_scaling_mode_queue_jobs_active, _completed, _failed y _waiting, la frecuencia de actualización se puede ajustar mediante N8N_METRICS_QUEUE_METRICS_INTERVAL. Desde n8n 2.28.0 también se pueden registrar los tiempos de ejecución de webhooks y formularios: N8N_METRICS_INCLUDE_WEBHOOK_METRICS activa el histograma n8n_webhook_request_duration_seconds, N8N_METRICS_INCLUDE_FORM_METRICS su equivalente n8n_form_submission_duration_seconds para los envíos de formularios. Con N8N_METRICS_INCLUDE_WORKFLOW_INFO se puede activar además un gauge n8n_workflow_info, que vincula los ID de workflow con nombres legibles, útil para paneles de Grafana sin ID crípticos.

Visualizar métricas con Grafana

Una vez activadas las métricas, Prometheus se encarga de la recopilación mediante un scrape job que consulta periódicamente la ruta /metrics de la instancia n8n, por defecto n8n se ejecuta en el puerto 5678. Grafana se conecta después como fuente de datos con la dirección del servidor Prometheus. Para empezar no es necesario construir dashboards desde cero: n8n publica en el proyecto de GitHub n8n-observability dashboards de Grafana ya preparados para las métricas admitidas, incluidos los tiempos de ejecución de webhooks y formularios.

Importante para la contextualización: el endpoint /metrics solo está disponible en instancias autoalojadas, no está disponible en n8n Cloud. Quien quiera trabajar de forma productiva con self-hosting y control total del proceso encontrará apoyo en la consultoría de n8n de NordFlux.

Preguntas frecuentes sobre monitorización en n8n

¿Está disponible el endpoint /metrics en n8n Cloud?

No, según la documentación de n8n, el endpoint de métricas de Prometheus está previsto exclusivamente para instancias autoalojadas. No está disponible para instancias en la nube.

¿Qué nivel de log es adecuado para el funcionamiento en producción?

El valor por defecto info suele ofrecer contexto suficiente para el funcionamiento continuo. debug genera bastante más salida y es adecuado sobre todo para investigar una incidencia concreta de forma específica y durante un tiempo limitado.

¿Cómo superviso los workers en una configuración en modo cola?

El endpoint de salud está desactivado por defecto en las instancias worker en modo cola y debe activarse mediante QUEUE_HEALTH_CHECK_ACTIVE=true. Además, N8N_METRICS_INCLUDE_QUEUE_METRICS=true proporciona indicadores de trabajos activos, completados, fallidos y en espera en la cola.

¿Necesito Grafana obligatoriamente para supervisar n8n?

No. Para una supervisión de disponibilidad sencilla basta con el endpoint /healthz o /healthz/readiness, que muchas herramientas de monitorización pueden consultar directamente mediante una comprobación HTTP. Grafana solo resulta relevante cuando hay que representar gráficamente historiales detallados, datos de colas o de latencia procedentes del endpoint /metrics.