Superviser une instance n8n self-hosted : healthz, métriques et alertes

Une instance n8n self-hosted qui tourne depuis des mois sans surveillance, c'est une panne qui attend son heure : un disque rempli par les données d'exécution, un conteneur arrêté après un redémarrage du serveur, des workflows planifiés qui ne se déclenchent plus — et personne ne s'en aperçoit avant que quelqu'un demande pourquoi le rapport hebdomadaire n'est pas arrivé. La supervision d'une instance n8n tient en trois couches complémentaires : la disponibilité de l'instance, la santé des exécutions, et les métriques dans la durée. Aucune des trois ne remplace les autres.

Couche 1 : la disponibilité de l'instance

L'endpoint /healthz

n8n expose nativement un endpoint de healthcheck : https://votre-instance/healthz. Tant que l'instance est opérationnelle, il répond avec un statut 200. C'est le point d'entrée de toute supervision — celui qu'interrogent les orchestrateurs (healthcheck Docker, probes Kubernetes) et les sondes externes.

Une sonde uptime externe, obligatoirement hors de votre serveur

Le réflexe indispensable : faire interroger /healthz toutes les minutes par un service de monitoring externe — UptimeRobot, Better Stack, ou tout équivalent, dont les offres gratuites suffisent largement pour une instance. Le mot important est externe : une sonde hébergée sur le même serveur que n8n tombe en même temps que lui. Si le serveur entier disparaît (panne d'hébergeur, disque plein, noyau figé), seul un observateur extérieur peut le constater et vous alerter.

Pourquoi un Error Workflow ne détecte pas une instance tombée

C'est le malentendu le plus fréquent. Un Error Workflow est déclenché par n8n lui-même quand une exécution échoue. Si l'instance entière est hors ligne, plus rien ne s'exécute — ni vos workflows, ni l'Error Workflow censé vous prévenir. Le silence est alors total, et c'est précisément le scénario le plus grave : les déclenchements planifiés manqués pendant une indisponibilité ne sont pas rattrapés. L'Error Workflow supervise les exécutions ; la sonde externe supervise l'instance. Il faut les deux.

Couche 2 : la santé des exécutions

L'Error Workflow global

Une fois la disponibilité couverte, la question devient : les workflows qui s'exécutent réussissent-ils ? Le socle est un Error Workflow global unique pour l'instance, référencé dans les settings de chaque workflow en production, qui notifie sur Slack ou par email avec le nom du workflow, le node en cause et le lien vers l'exécution échouée. Sa mise en place est détaillée dans notre guide de gestion des erreurs.

En complément, la liste des exécutions dans l'interface n8n reste l'outil de diagnostic quotidien : filtrer par statut « Error », repérer un workflow qui échoue en boucle, comparer les durées d'exécution. Une revue rapide chaque matin suffit souvent à repérer une dérive avant qu'elle devienne un incident.

Purger les données d'exécution avant qu'elles ne remplissent PostgreSQL

Chaque exécution enregistrée pèse dans la base de données — et sur une instance active, la table des exécutions peut atteindre plusieurs gigaoctets en quelques mois, dégradant les performances puis remplissant le disque (ce qui, retour à la couche 1, fait tomber l'instance). n8n fournit des variables d'environnement pour purger automatiquement :

• EXECUTIONS_DATA_PRUNE=true — active la purge automatique des anciennes exécutions.
• EXECUTIONS_DATA_MAX_AGE — l'âge maximal (en heures) au-delà duquel les données d'exécution sont supprimées ; une valeur de 168 (7 jours) à 336 (14 jours) convient à la plupart des instances.

Deux nuances : si vos workflows portent des obligations de traçabilité, ne comptez pas sur l'historique d'exécutions n8n comme piste d'audit — externalisez les événements vers une base dédiée, comme le fait notre workflow d'enregistrement d'audit dans Supabase. Et la purge ne remplace pas les sauvegardes : la base PostgreSQL contient vos workflows et vos credentials, et mérite le rituel décrit dans notre guide de sauvegarde et restauration PostgreSQL.

Couche 3 : les métriques dans la durée

Activer l'endpoint Prometheus

Les deux premières couches détectent les incidents ; les métriques révèlent les tendances — le volume d'exécutions qui double, les durées qui s'allongent, la file d'attente qui gonfle. n8n expose nativement un endpoint au format Prometheus : définissez la variable d'environnement N8N_METRICS=true, redémarrez, et l'endpoint /metrics devient disponible.

Ce qu'il faut y regarder en priorité :

• Les compteurs d'exécutions (réussies, échouées) : un taux d'échec qui monte est le signal le plus précoce d'un problème d'API externe ou de credential expiré.
• En mode queue avec Redis : les métriques de file d'attente — des jobs en attente qui s'accumulent signalent des workers sous-dimensionnés bien avant que les utilisateurs ne remarquent la lenteur.

Un Prometheus qui scrape cet endpoint et un dashboard Grafana par-dessus constituent le montage classique. C'est optionnel pour une petite instance — la sonde uptime et l'Error Workflow couvrent l'essentiel — mais cela devient pertinent dès que l'instance porte des workflows à volume, ou que vous voulez corréler l'activité avec les coûts, dans l'esprit de notre article sur le suivi du coût des appels IA.

Les logs : le troisième œil qu'on oublie

Quand un incident survient, les métriques disent que quelque chose ne va pas ; les logs disent souvent pourquoi. En Docker, docker logs -f <conteneur> (ou docker compose logs -f n8n) donne accès au flux, et la variable N8N_LOG_LEVEL règle la verbosité (info par défaut, debug pour investiguer un problème précis). Une étude publiée dans Communications of the ACM (Oliner, Ganapathi & Xu, 2012, « Advances and Challenges in Log Analysis » — Google Scholar) souligne que les logs restent une ressource sous-exploitée alors qu'ils sont indispensables au diagnostic des systèmes en production — un constat qui s'applique parfaitement aux instances n8n, où le réflexe de lire les logs du conteneur résout une bonne partie des mystères (instance qui redémarre en boucle, connexion PostgreSQL refusée, mémoire saturée).

Le workflow « meta » : n8n qui se surveille lui-même

La dernière brique est élégante parce qu'elle utilise n8n pour superviser n8n : un workflow heartbeat minimal, déclenché par un Schedule Trigger toutes les 5 ou 10 minutes, qui envoie un simple GET vers un service de type healthchecks.io. Le principe du dead man's switch : le service n'alerte pas quand le signal arrive, mais quand il cesse d'arriver au-delà d'une période de grâce.

Ce montage a une propriété que la sonde /healthz n'a pas : il vérifie la chaîne complète et réelle — l'instance est en ligne, et le scheduler déclenche à l'heure, et les exécutions aboutissent, et le réseau sortant fonctionne. Une instance peut répondre 200 sur /healthz tout en ayant un scheduler bloqué ou une file saturée : le heartbeat, lui, le détecterait. Trois précautions :

• Gardez ce workflow trivial (un Schedule Trigger, un HTTP Request) : chaque node ajouté est une cause de faux positif.
• Réglez la période de grâce du service à 2-3 fois l'intervalle du heartbeat pour tolérer un redémarrage planifié.
• Vérifiez le fuseau horaire du Schedule Trigger, piège classique détaillé dans notre guide du Schedule Trigger.

Par où commencer, concrètement

Par ordre de rapport effort/bénéfice :

• Jour 1 : sonde uptime externe sur /healthz (10 minutes), Error Workflow global (30 minutes), purge des exécutions (EXECUTIONS_DATA_PRUNE + EXECUTIONS_DATA_MAX_AGE, 5 minutes).
• Semaine 1 : workflow heartbeat vers healthchecks.io, revue de la liste des exécutions intégrée à la routine.
• Quand le volume le justifie : N8N_METRICS=true, Prometheus et Grafana, centralisation des logs.

Cette progressivité est l'un des arguments du self-hosted face au cloud managé — vous contrôlez tout, mais rien ne vous est fourni, un arbitrage détaillé dans notre comparatif self-hosted vs cloud. Et si vos workflows portent des obligations réglementaires, la supervision rejoint la traçabilité : le Pack Conformité & Audit (149 €) inclut les workflows d'enregistrement d'audit et de journalisation qui complètent naturellement le dispositif décrit ici.