OpenTelemetry dans n8n : tracer vos exécutions dans Grafana, Datadog ou Jaeger

Un webhook qui répond en 4 secondes au lieu de 400 millisecondes : le panneau d’exécution natif de n8n montre bien que quelque chose a ralenti, mais rarement où précisément le temps a été perdu quand plusieurs nodes s’enchaînent — un appel HTTP externe, une recherche vectorielle, un modèle de langage, un node Code. Depuis la version 2.19, n8n peut exporter chaque exécution de workflow sous forme de traces OpenTelemetry : le standard ouvert (projet CNCF) déjà utilisé pour observer le reste d’une infrastructure applicative. Une exécution n8n devient alors une trace parmi les autres dans Jaeger, Grafana Tempo, Datadog ou tout backend compatible OTLP — sans agent tiers ni bricolage de timing.

Ce que trace OpenTelemetry dans n8n

Le principe reprend celui du tracing distribué popularisé par Benjamin H. Sigelman et ses co-auteurs dans Dapper, a Large-Scale Distributed Systems Tracing Infrastructure (Google, 2010) : reconstruire, à partir d’identifiants propagés d’un appel à l’autre, le chemin complet d’une requête à travers un système composé de plusieurs étapes. Dans n8n, chaque exécution de workflow devient une trace racine, et chaque node exécuté devient un span enfant avec son horodatage de début et de fin. Un sous-workflow appelé via Execute Workflow apparaît comme une branche imbriquée dans la même trace plutôt que comme une exécution isolée à corréler manuellement — exactement le type de causalité inter-composants que Jonathan Mace, Ryan Roelke et Rodrigo Fonseca cherchent à automatiser dans Pivot Tracing: Dynamic Causal Monitoring for Distributed Systems (SOSP 2015), plutôt que de le reconstruire à la main à partir de logs épars.

Résultat concret : ouvrir une trace lente dans Jaeger montre immédiatement lequel des cinq nodes du workflow a pris 3,8 des 4 secondes — un appel HTTP Request vers une API tierce, par exemple — sans avoir à rouvrir l’exécution dans l’interface n8n et à comparer les horodatages à la main.

Configuration minimale

Deux variables d’environnement suffisent pour démarrer :

N8N_OTEL_ENABLED=true
N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://votre-collecteur:4318

n8n ajoute automatiquement /v1/traces à cette URL et exporte les spans en OTLP/HTTP (encodage Protobuf) — pointez la variable vers l’URL de base de votre collecteur, pas vers le chemin /v1/traces lui-même, une confusion fréquente en première configuration.

Trois variables complètent ce socle selon le déploiement :

• N8N_OTEL_EXPORTER_OTLP_HEADERS : liste de paires clé=valeur séparées par des virgules, pour l’authentification si votre backend (Datadog, Honeycomb, New Relic…) exige une clé d’API dans les en-têtes de la requête d’export.
• N8N_OTEL_TRACES_SAMPLE_RATE : un ratio entre 0 et 1 pour échantillonner les traces sur une instance à fort volume plutôt que de tout exporter — utile dès que le nombre d’exécutions quotidiennes dépasse ce que votre backend absorbe confortablement.
• Le suffixe _FILE sur n’importe quelle variable ci-dessus (par exemple N8N_OTEL_EXPORTER_OTLP_HEADERS_FILE) permet de lire sa valeur depuis un fichier plutôt que depuis une variable en clair — pratique avec un gestionnaire de secrets sur Docker ou Kubernetes.

Le piège du mode queue : une variable par instance

Sur une instance simple, ces variables suffisent au redémarrage du conteneur. En mode queue, la configuration doit être répétée sur chaque composant — l’instance principale et tous les workers. Un worker démarré sans N8N_OTEL_ENABLED continue d’exécuter normalement les workflows qui lui sont confiés : rien ne plante, rien n’alerte, mais aucune trace n’est émise pour ces exécutions. Le symptôme typique est une instrumentation qui semble fonctionner en test (une seule instance) puis des trous inexpliqués en production dès que docker compose up --scale n8n-worker=3 répartit la charge sur plusieurs processus. La vérification la plus sûre : définir les variables N8N_OTEL_* au niveau du service Docker Compose partagé par l’instance principale et les workers, plutôt que de les dupliquer service par service.

Choisir un backend : Jaeger pour démarrer, Grafana Tempo ou Datadog en production

N’importe quel collecteur compatible OTLP fonctionne, mais tous ne demandent pas le même effort de mise en place :

• Jaeger : image Docker unique (jaegertracing/all-in-one), interface web incluse, zéro configuration au-delà du port OTLP à exposer. Le choix le plus rapide pour valider que les traces arrivent bien avant de brancher un backend plus lourd.
• Grafana Tempo : s’intègre nativement à un stack Grafana existant, notamment si vous exposez déjà les métriques Prometheus de votre instance n8n — les deux se retrouvent dans les mêmes tableaux de bord.
• Datadog, Honeycomb, New Relic, Splunk : backends managés déjà en place dans beaucoup d’organisations ; n8n s’y ajoute alors comme un service applicatif de plus, au lieu d’un silo de logs séparé à surveiller à part.

Pour un premier test en local, un docker-compose.yml minimal ajoute simplement un service Jaeger à côté de n8n :

services:
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"   # interface web
      - "4318:4318"     # collecteur OTLP/HTTP

  n8n:
    image: n8nio/n8n
    environment:
      - N8N_OTEL_ENABLED=true
      - N8N_OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318
    ports:
      - "5678:5678"

Après quelques exécutions de workflow, l’interface Jaeger sur localhost:16686 affiche déjà les traces, groupées par nom de workflow.

Ce qu’OpenTelemetry ne remplace pas

Trois outils de ce blog couvrent des couches différentes de l’observabilité d’une instance n8n, et se combinent plutôt qu’ils ne se concurrencent :

• Face à la supervision d’instance (/healthz, métriques Prometheus) : cette dernière répond à « mon instance est-elle en ligne et en bonne santé », une question d’infrastructure agrégée. OpenTelemetry répond à « où est passé le temps sur cette exécution précise », une question de détail ponctuel.
• Face à Langfuse pour les AI Agents : Langfuse trace spécifiquement les appels à un modèle de langage (tokens, coût, raisonnement) à l’intérieur d’un node AI Agent. OpenTelemetry trace la mécanique du workflow entier — utile même sur des workflows sans aucune IA, comme le tri d’emails ou une synchronisation de stock.
• Face à l’Error Workflow : celui-ci capture les échecs pour alerter ou relancer. OpenTelemetry capture aussi les exécutions qui réussissent mais ralentissent, invisibles pour un Error Workflow qui ne se déclenche que sur une erreur explicite.

Cas d’usage concrets

• Diagnostiquer une latence variable sur le Pack Assistant RAG (119 €) : un chatbot qui répond parfois en 2 secondes et parfois en 15 cache généralement un goulot dans la recherche vectorielle ou l’appel au modèle de génération — une trace ouverte dans Jaeger isole en un coup d’œil lequel des deux nodes varie, plutôt que de deviner à partir des logs.
• Repérer un fournisseur externe qui ralentit un pipeline du Pack Inbox IA (79 €) : si le tri d’emails par IA ralentit progressivement, une trace distingue immédiatement un appel API qui dérive (fournisseur IMAP, API du modèle) d’un problème propre au workflow.
• Documenter la performance d’un pipeline du Pack Conformité & Audit (149 €) : au-delà de la piste d’audit fonctionnelle déjà stockée dans Supabase, des traces permettent de justifier, en cas de question, que le traitement d’un dossier reste dans une fenêtre de temps prévisible.

Les trois packs sont réunis dans le Bundle FlowKit Complet (269 € au lieu de 347 € achetés séparément) : la même instrumentation OpenTelemetry couvre tous les workflows dès lors qu’elle est activée une fois, au niveau de l’instance.

En résumé

Deux variables d’environnement suffisent à faire émettre à n8n des traces OpenTelemetry standard, exploitables dans Jaeger pour démarrer ou dans un backend de production comme Grafana Tempo ou Datadog. La fonctionnalité est self-hosted uniquement, disponible dès la Community Edition, et demande une attention particulière en mode queue où chaque worker doit porter la même configuration. Elle ne remplace ni la supervision d’instance, ni Langfuse pour les AI Agents, ni l’Error Workflow : elle comble un angle mort spécifique, celui de savoir où passe le temps à l’intérieur d’une exécution précise — la question que ni un compteur agrégé ni une alerte d’échec ne peuvent, par construction, résoudre.