Votre instance n8n tourne, vos workflows s'exécutent, et un matin vous découvrez que rien ne s'est lancé depuis la veille : le serveur répondait, mais la base de données ne suivait plus. Sans supervision, c'est le client ou le collègue qui vous prévient. Avec trois endpoints que n8n fournit déjà, vous pouvez l'apprendre avant eux.
Cet article explique ce que chaque endpoint de santé et de métriques vérifie réellement, comment les activer, et comment en tirer un dispositif d'alerte simple pour une PME. Les faits sur n8n viennent de sa documentation officielle, citée en fin d'article ; les choix d'organisation sont notre analyse, à adapter à votre contexte.
Trois endpoints, trois questions différentes
n8n expose trois URL de supervision. Elles ne répondent pas à la même question, et c'est là que se trouvent les erreurs les plus fréquentes.
| Endpoint | Question posée | Disponibilité |
|---|---|---|
/healthz |
Le processus n8n répond-il ? | Self-hosted et Cloud |
/healthz/readiness |
La base est-elle connectée et migrée ? | À vérifier pour votre version |
/metrics |
Que se passe-t-il à l'intérieur ? | Self-hosted uniquement, désactivé par défaut |
/healthz : « le serveur est joignable »
D'après la documentation, <url-de-votre-instance>/healthz renvoie un code HTTP standard, et un 200 indique que l'instance est joignable. La même page précise que cet endpoint n'indique pas l'état de la base de données.
Conséquence pratique : un contrôle qui ne regarde que /healthz peut rester au vert alors que l'instance ne peut plus lire ni écrire ses workflows. C'est un test de vivacité, pas un test de bon fonctionnement.
/healthz/readiness : « l'instance peut travailler »
Le second endpoint, <url-de-votre-instance>/healthz/readiness, renvoie un 200 si la base de données est connectée et migrée, c'est-à-dire si l'instance est prête à recevoir du trafic. C'est celui à brancher sur un orchestrateur ou un répartiteur de charge qui doit décider s'il envoie des requêtes à l'instance.
La documentation ne décrit pas de corps de réponse pour ces deux endpoints : fondez vos contrôles sur le code HTTP, pas sur un texte à analyser.
/metrics : « comment va-t-elle, en détail »
Le troisième endpoint expose des métriques au format Prometheus, collectées avec la bibliothèque prom-client. Il est désactivé par défaut et se règle avec la variable N8N_METRICS=true. La documentation indique qu'il est disponible sur toutes les éditions auto-hébergées, et pas sur n8n Cloud.
Activer et configurer
Le point d'entrée tient en une ligne :
export N8N_METRICS=true
Plusieurs variables permettent ensuite d'ajuster ce qui est exposé. Voici celles qui nous semblent utiles pour démarrer, avec leur valeur par défaut d'après la page des variables d'environnement :
| Variable | Défaut | Rôle |
|---|---|---|
N8N_ENDPOINT_HEALTH |
healthz |
Chemin de l'endpoint de santé |
N8N_METRICS |
false |
Active /metrics |
N8N_METRICS_PREFIX |
n8n_ |
Préfixe des métriques propres à n8n |
N8N_METRICS_INCLUDE_DEFAULT_METRICS |
true |
Métriques système et Node.js |
N8N_METRICS_INCLUDE_QUEUE_METRICS |
false |
Métriques de jobs en mode queue |
N8N_METRICS_INCLUDE_WORKFLOW_ID_LABEL |
false |
Ajoute l'identifiant du workflow comme étiquette |
D'autres variables N8N_METRICS_INCLUDE_* existent (cache, nœuds, credentials, API, planificateur) : elles sont toutes désactivées par défaut. Notre conseil est de n'en activer qu'une à la fois et seulement quand une question précise le justifie. Plus on ajoute d'étiquettes, plus le volume de séries à stocker augmente, ce qui est un principe général de Prometheus plutôt qu'une mesure propre à n8n.
Le cas du mode queue : surveiller aussi les workers
Si vous avez passé n8n en mode queue avec des workers, la supervision devient plus importante, parce qu'il y a désormais plusieurs processus qui peuvent tomber indépendamment.
Deux points à retenir de la documentation :
- l'endpoint de santé est toujours actif sur l'instance principale, mais désactivé par défaut sur les workers. Pour l'activer, on utilise
QUEUE_HEALTH_CHECK_ACTIVE=true. La page ne détaille pas cette variable ligne à ligne : vérifiez son effet sur votre version avant de l'industrialiser ; - les instances principales et les workers peuvent exposer des métriques.
Avec N8N_METRICS_INCLUDE_QUEUE_METRICS=true, les instances principales exposent des métriques issues de la file d'attente, par exemple le nombre de jobs actifs, terminés, en échec et en attente (n8n_scaling_mode_queue_jobs_active, ..._completed, ..._failed, ..._waiting avec le préfixe par défaut). La variable N8N_METRICS_QUEUE_METRICS_INTERVAL règle la fréquence de rafraîchissement.
Dans une configuration à plusieurs instances principales, la documentation mentionne une jauge instance_role_leader à 1 pour l'instance leader et 0 pour les autres, pratique pour agréger les requêtes sans compter plusieurs fois la même donnée.
Une règle de sécurité avant tout
La documentation est explicite : n'exposez pas /metrics publiquement. Limitez-le aux services internes qui collectent les données Prometheus, car il peut révéler des informations opérationnelles sensibles.
En pratique, cela veut dire : pas de règle de reverse proxy qui publie /metrics sur Internet, un réseau privé ou une liste d'adresses autorisées entre n8n et le collecteur, et une vérification depuis l'extérieur que l'URL ne répond pas. Si vous avez déjà protégé vos webhooks par une signature, appliquez le même raisonnement ici : ce qui sert à l'exploitation n'a pas vocation à être public.
Un dispositif minimal pour une PME
Tout le monde n'a pas besoin d'un Prometheus et d'un Grafana. Voici une progression en trois niveaux, de la plus simple à la plus complète.
- Niveau 1, une sonde externe sur
/healthz/readiness. Un service de supervision de disponibilité qui interroge l'URL toutes les minutes et vous écrit par e-mail ou messagerie après quelques échecs consécutifs. C'est peu de travail et cela détecte le scénario du début de cet article. Préférezreadinessàhealthzpour que la base de données soit incluse dans le contrôle. - Niveau 2, une alerte sur l'échec des workflows. La sonde ne voit pas un workflow qui échoue pendant que l'instance est saine. Pour cela, n8n propose le déclencheur d'erreur et le workflow d'alerte : les deux niveaux se complètent, l'un surveille la plateforme, l'autre le contenu.
- Niveau 3,
/metricscollecté par Prometheus. À envisager quand vous avez plusieurs workers, des volumes élevés ou des engagements de service. Commencez par suivre la file d'attente (jobs en attente et en échec) et l'état des instances, avant d'ajouter des étiquettes détaillées.
Notre avis : le niveau 1 + le niveau 2 couvrent l'essentiel des besoins d'une petite structure. Le niveau 3 se justifie par un volume ou un risque, pas par principe.
Quoi alerter, et quoi ignorer
Une alerte utile déclenche une action. Quelques règles de bon sens :
- Alerter sur une indisponibilité confirmée, pas sur un échec isolé : exigez plusieurs contrôles consécutifs en échec avant d'envoyer un message.
- Alerter sur une file qui ne se vide plus, si vous êtes en mode queue : un nombre de jobs en attente qui grimpe sans redescendre signale des workers absents ou saturés. Le seuil dépend de votre charge ; mesurez d'abord ce qui est normal chez vous.
- Ne pas alerter sur chaque métrique. Les métriques par défaut du système sont utiles pour diagnostiquer après coup, rarement pour réveiller quelqu'un.
- Tester l'alerte elle-même. Coupez volontairement la base ou le service sur un environnement de test et vérifiez que le message arrive, et qu'il dit quoi faire.
Pensez aussi à relier la supervision à vos opérations de maintenance : une mise à jour de n8n auto-hébergé doit se terminer par un contrôle de readiness, qui vérifie justement que la base est migrée.
Les pièges à éviter
- Se contenter de
/healthz: il confirme que le serveur répond, pas que la base fonctionne. - Chercher
/metricssur n8n Cloud : l'endpoint n'y est pas disponible, selon la documentation. - Oublier les workers : en mode queue, l'instance principale peut aller bien pendant que les workers sont à l'arrêt.
- Publier
/metricssur Internet : à bannir. - Activer toutes les étiquettes d'un coup : la charge de stockage et de lecture augmente sans que vous sachiez ce que vous cherchez.
FAQ
Quelle est la différence entre /healthz et /healthz/readiness ?
/healthz renvoie 200 quand l'instance est joignable, sans indication sur la base de données. /healthz/readiness renvoie 200 quand la base de données est connectée et migrée, donc quand l'instance est prête à travailler.
/metrics est-il actif par défaut ?
Non. Il faut définir N8N_METRICS=true. Il n'est pas disponible sur n8n Cloud.
Faut-il Prometheus pour surveiller n8n ?
Non. Une sonde de disponibilité sur /healthz/readiness et une alerte sur les échecs de workflows couvrent déjà une bonne part des besoins d'une petite structure. Prometheus devient pertinent avec plusieurs workers ou des exigences de service.
Comment surveiller les workers en mode queue ?
Activez l'endpoint de santé des workers avec QUEUE_HEALTH_CHECK_ACTIVE=true et, si besoin, les métriques de file d'attente avec N8N_METRICS_INCLUDE_QUEUE_METRICS=true. Vérifiez le comportement sur votre version.
Peut-on changer le chemin /healthz ?
Oui, avec la variable N8N_ENDPOINT_HEALTH (valeur par défaut : healthz).
Sources
- Monitoring — documentation n8n
- Enable Prometheus metrics — documentation n8n
- Endpoints environment variables — documentation n8n
Fiabiliser votre instance avec InfiniteLab
Mettre en place la supervision d'une instance n8n, c'est un travail de quelques heures quand on sait quoi mesurer, et un sujet qu'on découvre trop tard quand on ne l'a pas fait. Si vous voulez un second regard sur votre dispositif (sondes, alertes, sauvegardes, passage en mode queue), parlons de votre instance.