Monitoring : logs, healthchecks, Prometheus/Grafana

Quiconque héberge lui-même une instance n8n a besoin de trois éléments pour un fonctionnement fiable : des logs pertinents pour le dépannage, un endpoint healthcheck pour la surveillance de la disponibilité, et des métriques Prometheus pour un aperçu plus approfondi des files d'attente, des webhooks et des formulaires. n8n intègre déjà ces trois éléments, il suffit de les activer et de les relier via des variables d'environnement. État : juillet 2026.

Configurer le niveau de log et la sortie des logs

n8n utilise la bibliothèque de logging winston et configure la sortie des logs selon la documentation n8n sur le logging via des variables d'environnement. Pour un usage courant, deux paramètres suffisent.

• N8N_LOG_LEVEL : contrôle le niveau de détail. Du plus bas au plus élevé, silent, error, warn, info et debug sont disponibles, la valeur par défaut est info. silent n'affiche rien, debug fournit les informations de diagnostic les plus détaillées et convient surtout au dépannage ciblé.
• N8N_LOG_OUTPUT : définit où les logs sont écrits, console ou file, également combinables en console,file. La valeur par défaut est console.
• N8N_LOG_FILE_LOCATION : chemin du fichier de log, lorsque file est actif. La valeur par défaut est <dossier n8n>/logs/n8n.log.
• N8N_LOG_FILE_SIZE_MAX : taille maximale par fichier de log en Mo, valeur par défaut 16 Mo.
• N8N_LOG_FILE_COUNT_MAX : nombre maximal de fichiers de log conservés, valeur par défaut 100. Avec plusieurs workers, cette valeur doit être définie consciemment pour que la rotation corresponde à l'espace de stockage disponible.

En production, info suffit généralement, debug reste une mesure temporaire car il écrit nettement plus de données et remplit les fichiers de log plus rapidement.

Endpoints healthcheck pour la surveillance de la disponibilité

Selon la documentation n8n sur le monitoring n8n fournit deux endpoints de santé adaptés aux vérifications de disponibilité externes. L'endpoint /healthz indique seulement si l'instance est joignable, un HTTP 200 ne dit rien sur l'état de la base de données. L'endpoint /healthz/readiness va plus loin : il ne renvoie 200 que lorsque la base de données est connectée et migrée, c'est-à-dire que l'instance est réellement prête à traiter des requêtes. Le chemin peut être adapté via la variable N8N_ENDPOINT_HEALTH, par exemple lorsqu'un reverse proxy attend un autre chemin de santé.

Sur le serveur principal, l'endpoint de santé est toujours actif. Sur les instances worker en mode queue, en revanche, il est désactivé par défaut et doit être activé via QUEUE_HEALTH_CHECK_ACTIVE=true si un load balancer ou un orchestrateur doit également vérifier les workers.

Exporter des métriques Prometheus

Pour des données opérationnelles plus détaillées, n8n fournit un endpoint /metrics via la bibliothèque prom-client. Il est désactivé par défaut et s'active avec N8N_METRICS=true, aussi bien sur les instances main que worker. Important pour l'exploitation : l'endpoint ne doit pas être accessible publiquement, mais uniquement aux systèmes internes qui consomment les données Prometheus, car il révèle des détails opérationnels de l'instance.

Les métriques et labels précis affichés sont contrôlés par les variables N8N_METRICS_INCLUDE_*. Pour les configurations de scaling en mode queue, N8N_METRICS_INCLUDE_QUEUE_METRICS=true fournit des indicateurs comme n8n_scaling_mode_queue_jobs_active, _completed, _failed et _waiting, le taux d'actualisation peut être ajusté via N8N_METRICS_QUEUE_METRICS_INTERVAL. Depuis n8n 2.28.0, les durées d'exécution des webhooks et des formulaires peuvent également être relevées : N8N_METRICS_INCLUDE_WEBHOOK_METRICS active l'histogramme n8n_webhook_request_duration_seconds, N8N_METRICS_INCLUDE_FORM_METRICS son équivalent n8n_form_submission_duration_seconds pour les soumissions de formulaires. Avec N8N_METRICS_INCLUDE_WORKFLOW_INFO, une gauge n8n_workflow_info peut en outre être activée, qui associe les ID de workflow à des noms lisibles, pratique pour des panneaux Grafana sans ID cryptiques.

Visualiser les métriques avec Grafana

Une fois les métriques activées, Prometheus se charge de la collecte via un scrape job qui interroge régulièrement le chemin /metrics de l'instance n8n, par défaut n8n s'exécute sur le port 5678. Grafana est ensuite connecté comme source de données avec l'adresse du serveur Prometheus. Pour démarrer, il n'est pas nécessaire de construire des dashboards à partir de zéro : n8n publie dans le projet GitHub n8n-observability des dashboards Grafana prêts à l'emploi pour les métriques prises en charge, y compris pour les durées d'exécution des webhooks et des formulaires.

Important pour le contexte : l'endpoint /metrics n'est disponible que pour les instances auto-hébergées, il n'est pas disponible avec n8n Cloud. Ceux qui souhaitent travailler de manière productive en self-hosting avec une pleine maîtrise du processus trouveront un accompagnement auprès du conseil n8n de NordFlux.

Questions fréquentes sur le monitoring dans n8n

L'endpoint /metrics est-il disponible avec n8n Cloud ?

Non, selon la documentation n8n, l'endpoint de métriques Prometheus est prévu exclusivement pour les instances auto-hébergées. Il n'est pas disponible pour les instances cloud.

Quel niveau de log convient pour l'exploitation en production ?

La valeur par défaut info fournit généralement un contexte suffisant pour l'exploitation courante. debug produit nettement plus de sorties et convient surtout pour examiner un incident précis de manière ciblée et limitée dans le temps.

Comment surveiller les workers dans une configuration en mode queue ?

L'endpoint de santé est désactivé par défaut sur les instances worker en mode queue et doit être activé via QUEUE_HEALTH_CHECK_ACTIVE=true. De plus, N8N_METRICS_INCLUDE_QUEUE_METRICS=true fournit des indicateurs sur les jobs actifs, terminés, échoués et en attente dans la file.

Ai-je absolument besoin de Grafana pour surveiller n8n ?

Non. Pour un simple monitoring de disponibilité, l'endpoint /healthz ou /healthz/readiness suffit, que de nombreux outils de monitoring peuvent interroger directement via un contrôle HTTP. Grafana ne devient pertinent que lorsque des historiques détaillés, des données de file d'attente ou de latence issues de l'endpoint /metrics doivent être analysés graphiquement.