n8n : externaliser les logs sans casser la prod

Un workflow n8n qui échoue silencieusement à 3h du matin reste invisible si les logs restent confinés dans le conteneur. La sortie standard se remplit, le disque sature, et l’historique d’exécution disparaît au fil du pruning automatique. Externaliser les logs n8n n’est pas un luxe pour les déploiements en production : c’est la condition pour diagnostiquer, auditer et conserver une trace exploitable au-delà de quelques jours.

Avant d’envoyer quoi que ce soit vers un système tiers, il faut comprendre ce que n8n écrit réellement, où et à quel niveau. La confusion entre logs applicatifs et données d’exécution est la première cause de configurations bancales.

Les logs n8n : deux flux distincts à ne pas confondre

n8n produit deux types d’informations qui circulent par des canaux séparés. Les logs applicatifs concernent le process Node.js lui-même : démarrage, erreurs internes, état de la file d’attente, connexions à la base. Les données d’exécution, elles, décrivent ce qui se passe dans chaque workflow : entrées et sorties des nodes, durée, statut, erreurs métier. Ces dernières sont stockées en base de données, pas dans les logs au sens classique.

Cette distinction conditionne toute la stratégie d’externalisation. Envoyer les logs applicatifs vers Loki ne donnera aucune visibilité sur le payload d’un node HTTP Request. Inversement, exporter les exécutions via l’API n’affiche pas les erreurs de connexion Postgres du process n8n. Une stack de monitoring complète couvre les deux flux.

Les niveaux de log et leur configuration

La variable N8N_LOG_LEVEL accepte cinq valeurs utiles en production : error, warn, info, verbose et debug. La valeur silent désactive complètement la sortie. Par défaut, n8n est positionné sur info, qui capture les événements de démarrage, les exécutions terminées et les erreurs sans noyer le flux.

Le niveau debug multiplie le volume par dix ou vingt selon la charge : il trace les requêtes internes, les appels à la base, les détails de la file d’attente. À réserver au troubleshooting ponctuel. La documentation officielle de n8n confirme que les niveaux pertinents en exploitation sont info ou debug pour investigation, et qu’un excès de verbosité dégrade les performances I/O sur les instances chargées.

Logs d’exécution versus logs applicatifs

Les logs d’exécution sont accessibles via l’interface (onglet Executions) et l’API REST /executions. Ils contiennent les données binaires des nodes, ce qui les rend lourds : un workflow avec dix nodes manipulant des fichiers peut générer plusieurs mégaoctets par run. Les logs applicatifs, eux, sortent sur stdout par défaut et restent textuels.

Conséquence pratique : la rétention des exécutions se gère côté base via le pruning, tandis que la rétention des logs applicatifs dépend de l’outil qui capture stdout (Docker, journald, agent de collecte).

Configurer la sortie des logs n8n via les variables d’environnement

Quatre variables suffisent à passer d’un mode console vers un fichier exploitable par un agent de collecte. N8N_LOG_OUTPUT accepte console, file ou les deux séparés par une virgule. N8N_LOG_FILE_LOCATION définit le chemin du fichier, par défaut ~/.n8n/logs/n8n.log. N8N_LOG_FILE_SIZE_MAX fixe la taille maximale en mégaoctets avant rotation, et N8N_LOG_FILE_COUNT_MAX le nombre de fichiers conservés.

Rediriger les logs vers un fichier

Une configuration typique en Docker self-hosted ressemble à ceci :

N8N_LOG_LEVEL=info
N8N_LOG_OUTPUT=console,file
N8N_LOG_FILE_LOCATION=/home/node/.n8n/logs/n8n.log
N8N_LOG_FILE_SIZE_MAX=16
N8N_LOG_FILE_COUNT_MAX=10

Conserver la sortie console en parallèle du fichier permet à Docker de continuer à capturer les logs pour docker logs, tout en alimentant un fichier qu’un agent comme Promtail ou Filebeat peut lire.

Rotation et rétention des fichiers

Avec les valeurs ci-dessus, n8n garde au maximum 160 Mo de logs locaux (10 fichiers de 16 Mo). Ce volume est suffisant pour quelques jours sur une instance moyenne, jamais pour un audit à 90 jours. C’est précisément ce constat qui rend l’externalisation incontournable : la rotation locale n’est qu’un tampon, pas une stratégie de conservation.

Sur Kubernetes, la rotation est gérée par kubelet sur les fichiers du conteneur, ce qui rend les variables FILE_SIZE_MAX moins critiques. Sur un déploiement Docker Compose classique, négliger ces limites expose à une saturation de disque silencieuse.

Log Streaming : la solution native vers des destinations externes

Le Log Streaming est la fonctionnalité officielle d’externalisation, disponible uniquement sur les plans Enterprise et Cloud Enterprise. Elle permet de pousser les événements n8n (créations de workflows, exécutions, connexions utilisateurs, modifications de credentials) vers une ou plusieurs destinations, en temps réel, depuis l’interface d’administration.

Destinations supportées

Trois types de destinations sont disponibles nativement. Le Webhook envoie un POST HTTP avec le payload JSON de l’événement vers n’importe quelle URL, ce qui ouvre l’intégration avec Datadog, New Relic ou un collecteur custom. Syslog cible les infrastructures traditionnelles, avec support TCP/UDP et choix de la facility. Sentry est dédié au suivi d’erreurs applicatives, avec mapping automatique des événements d’échec d’exécution.

Chaque destination se configure avec un nom, une liste d’événements à transmettre (granularité par catégorie : workflow, node, exécution, audit) et les paramètres de connexion. Plusieurs destinations peuvent fonctionner en parallèle, par exemple un webhook vers Datadog pour les exécutions et Sentry pour les erreurs.

Circuit breaker et résilience

Un mécanisme de circuit breaker protège n8n contre l’indisponibilité d’une destination externe. Si un webhook ne répond plus, n8n n’accumule pas indéfiniment les tentatives : après plusieurs échecs consécutifs, le circuit s’ouvre et les événements sont temporairement abandonnés plutôt que de bloquer le process principal. Le circuit se referme automatiquement après une période de cooldown.

Ce comportement évite qu’une panne de Datadog ou de Splunk ne propage une latence sur les exécutions de workflows. C’est un détail souvent absent des comparatifs, alors qu’il détermine la stabilité réelle de la chaîne en production.

Externaliser sans Log Streaming : les approches pour self-hosted

La communauté self-hosted sans licence Enterprise dispose de plusieurs voies, toutes éprouvées en production. Le choix dépend de l’infrastructure existante et du type de log à externaliser.

Agents de collecte vers Grafana Loki ou Elasticsearch

L’approche la plus robuste consiste à déployer un agent qui lit le fichier de log n8n et le pousse vers une plateforme centralisée. Promtail alimente Loki avec un parsing minimal et des labels par container. Filebeat ou Fluent Bit envoient vers Elasticsearch, OpenSearch ou Splunk. Vector joue le même rôle avec une syntaxe de transformation plus expressive.

Sur Kubernetes, un DaemonSet Fluent Bit collecte les logs de tous les pods n8n sans configuration spécifique côté application, à condition que N8N_LOG_OUTPUT reste sur console. Cette approche est documentée pour AWS CloudWatch via le CloudWatch Agent en sidecar ou DaemonSet.

Workflow n8n de monitoring des exécutions

Pour les données d’exécution (et non les logs applicatifs), un workflow n8n dédié peut interroger l’API REST interne /rest/executions à intervalle régulier, filtrer les échecs et pousser les résultats vers Google Sheets, Airtable, Notion, Supabase ou n’importe quelle base externe. Cette méthode est la plus accessible pour les débutants, avec des nodes natifs pour la plupart des destinations courantes.

Le pattern : un node Schedule Trigger toutes les cinq minutes, un node HTTP Request vers /rest/executions?status=error, un Split In Batches, puis un node de destination. Pour des volumes importants, PostgreSQL, MySQL ou SQLite restent plus adaptés que les solutions no-code, avec la possibilité de requêter l’historique en SQL.

Correlation ID pour tracer les exécutions de bout en bout

Dans une architecture où n8n appelle des microservices downstream, injecter un identifiant unique par exécution permet de corréler les logs n8n avec ceux des services appelés. La méthode consiste à générer un UUID dans le premier node du workflow ({{ $execution.id }} ou un crypto.randomUUID() dans un Code node), puis à le propager dans les headers HTTP de chaque appel sortant sous un nom standard comme X-Correlation-ID ou traceparent.

Les champs JSON recommandés pour des logs structurés incluent timestamp, workflow_id, run_id, node_id, correlation_id, severity, message, environment et tenant. Cette normalisation rend les recherches multi-services triviales dans Loki, Elastic ou Splunk. L’écosystème OpenTelemetry, via le protocole OTLP, permet d’aller plus loin en instrumentant chaque node comme un span traçable.

Pruning des exécutions et archivage long terme

n8n purge automatiquement les données d’exécution pour éviter que la base ne croisse indéfiniment. Le comportement se contrôle par EXECUTIONS_DATA_PRUNE=true (actif par défaut), EXECUTIONS_DATA_MAX_AGE (en heures, par défaut 336 soit 14 jours) et EXECUTIONS_DATA_PRUNE_MAX_COUNT (nombre maximum d’exécutions conservées, par défaut 10000).

Configurer le pruning

Sur une instance qui exécute 50 000 workflows par jour, les valeurs par défaut conservent moins de cinq heures d’historique. Augmenter EXECUTIONS_DATA_PRUNE_MAX_COUNT à 500 000 et EXECUTIONS_DATA_MAX_AGE à 720 (30 jours) reste viable sur Postgres dimensionné, mais alourdit les sauvegardes et ralentit les requêtes sur l’onglet Executions.

Archiver hors de n8n pour conserver l’historique

Une rétention de 90 jours est souvent citée comme repère pour les besoins d’audit et de support. Aucune configuration de pruning ne permet de tenir cette durée sans dégrader les performances : externaliser est la seule réponse durable. Le workflow de monitoring décrit plus haut, lancé toutes les heures avec un filtre sur la dernière fenêtre, suffit à archiver l’essentiel dans une base externe avant que le pruning ne supprime les données.

Sécurité et conformité des logs externalisés

Externaliser des logs sans filtrage expose à une fuite massive de données sensibles. Les payloads d’exécution contiennent fréquemment des tokens d’API, des emails, des numéros de téléphone, parfois des mots de passe en clair si un workflow manipule des credentials. Ces informations se retrouvent alors dupliquées dans Loki, Datadog ou la base d’archivage, avec une surface d’attaque démultipliée.

Filtrer les données sensibles avant envoi

La règle de base : ne jamais logger de mots de passe, clés API, tokens ou données personnelles directes. À la place, conserver des identifiants d’enregistrement (user_id, order_id) qui permettent de retrouver l’information dans le système source sans la dupliquer dans les logs.

Concrètement, un node Code en fin de workflow peut nettoyer le payload avant qu’il ne soit persisté ou envoyé. Pour le Log Streaming Enterprise, le filtrage se fait côté destination (par exemple un processor Logstash qui masque les champs sensibles via une regex). Côté agent, Fluent Bit et Vector proposent des filtres de redaction natifs.

Chiffrement et authentification des destinations

Toute destination externe doit être atteinte en TLS. Les webhooks de Log Streaming acceptent une authentification par header personnalisé, ce qui permet de protéger l’endpoint receveur par un token partagé. Syslog supporte TLS depuis RFC 5425, à activer explicitement côté n8n et côté collecteur.

Sur les architectures multi-tenant, ajouter un champ tenant aux logs structurés et appliquer un filtrage côté destination (Loki avec multi-tenancy via header X-Scope-OrgID, Elasticsearch avec index par tenant) garantit qu’un opérateur ne voit que les logs du périmètre auquel il a droit.

FAQ sur l’externalisation des logs n8n

Comment exporter les logs d’exécution n8n vers un fichier externe ?

Définir N8N_LOG_OUTPUT=file et N8N_LOG_FILE_LOCATION=/chemin/vers/n8n.log. Ajuster N8N_LOG_FILE_SIZE_MAX et N8N_LOG_FILE_COUNT_MAX pour la rotation. Ces variables concernent les logs applicatifs ; pour les données d’exécution complètes, passer par l’API REST /rest/executions ou le Log Streaming.

Le Log Streaming est-il disponible sur la version community self-hosted ?

Non, le Log Streaming natif est réservé aux licences Enterprise et Cloud Enterprise. Les self-hosters en community edition utilisent des agents de collecte (Promtail, Fluent Bit, Filebeat) sur le fichier de log, ou un workflow n8n qui interroge l’API d’exécution.

Quelle est la différence entre les logs n8n et les logs d’exécution de workflows ?

Les logs n8n (applicatifs) décrivent le process Node.js : démarrage, erreurs internes, file d’attente. Ils sortent sur stdout ou un fichier. Les logs d’exécution décrivent ce qui se passe dans chaque workflow (entrées/sorties des nodes, statut, durée). Ils sont stockés en base de données et consultables via l’interface ou l’API.

Comment centraliser les logs de plusieurs instances n8n ?

Déployer un collecteur centralisé (Loki, ELK Stack, OpenSearch) et installer un agent (Promtail, Filebeat, Fluent Bit) sur chaque instance. Ajouter des labels d’instance (hostname, environment) permet de filtrer et corréler les logs depuis une seule interface Grafana ou Kibana.

Combien de temps n8n conserve-t-il les logs d’exécution par défaut ?

Les données d’exécution sont conservées 336 heures (14 jours) ou 10 000 exécutions maximum, selon ce qui est atteint en premier. Ces valeurs se modifient via EXECUTIONS_DATA_MAX_AGE et EXECUTIONS_DATA_PRUNE_MAX_COUNT. Désactiver entièrement le pruning avec EXECUTIONS_DATA_PRUNE=false est possible mais déconseillé sans archivage externe.

Pour démarrer rapidement : activer la sortie fichier avec rotation, brancher un agent Fluent Bit vers Loki, et créer un workflow de monitoring qui archive les exécutions en échec dans une base externe. Cette combinaison couvre 90 % des besoins sans licence Enterprise, et reste compatible avec une migration ultérieure vers le Log Streaming natif si le périmètre l’exige.