Node Execution Data n8n : annoter ses exécutions pour les retrouver

Vous savez qu'un workflow a mal traité la commande CMD-20841 hier après-midi, mais la liste des exécutions n'affiche qu'une colonne de dates et de statuts verts. Ouvrir les exécutions une par une pour retrouver la bonne coûte dix minutes à chaque incident. Le node Execution Data (n8n-nodes-base.executionData) existe précisément pour ça : il attache des paires clé/valeur métier à l'exécution en cours, qui deviennent ensuite des critères de filtre dans la liste des exécutions. Ce guide couvre ses paramètres exacts, ses limites réelles, sa disponibilité par plan — le point le plus souvent passé sous silence — et la façon de choisir des clés utiles sans transformer l'historique en base de données personnelles.

Le problème : des dizaines d'exécutions, une seule qui vous intéresse

Tant qu'un workflow tourne trois fois par jour, l'historique suffit. Dès qu'il traite des centaines d'événements — webhooks de commandes, tickets de support, emails entrants — la liste devient un mur d'horodatages indifférenciés. Le débogage change alors de nature : le problème n'est plus « comprendre l'erreur » mais « localiser l'exécution concernée », ce qui précède toute la démarche décrite dans notre guide de débogage des workflows n8n.

Le problème dépasse largement n8n. Dans le rapport technique de Google « Dapper, a Large-Scale Distributed Systems Tracing Infrastructure » (2010), Benjamin H. Sigelman, Luiz André Barroso, Mike Burrows et leurs co-auteurs décrivent une infrastructure de traçage dont l'un des mécanismes clés est la possibilité d'attacher des annotations applicatives aux traces pour retrouver et corréler les requêtes qui intéressent le développeur. Le node Execution Data est la version minimale de cette idée.

Ce que fait exactement le node Execution Data

Le node est disponible sous le nom Execution Data dans les nodes core. Sa documentation le résume ainsi : enregistrer des métadonnées pour les exécutions du workflow, afin de pouvoir ensuite chercher sur ces données dans la liste Executions.

• Une seule opération : Save Execution Data for Search. Le node n'a pas de mode lecture.
• Un champ répétable : vous ajoutez un Saved Field par métadonnée, avec une Key et une Value. Les deux acceptent des expressions, donc {{ $json.order_id }} fonctionne directement.
• Aucune sortie modifiée : les items passent au travers du node inchangés. Vous pouvez l'insérer au milieu d'une chaîne sans casser le flux de données.

L'équivalent en node Code, pour les cas où la clé elle-même est dynamique :

// Une valeur à la fois
$execution.customData.set('order_id', $json.order_id);

// Ou l'objet complet d'un coup (remplace ce qui existait)
$execution.customData.setAll({
  order_id: String($json.order_id),
  customer_id: String($json.customer_id),
  channel: 'webhook',
});

return $input.all();

Le node graphique couvre l'essentiel des besoins ; le node Code sert quand vous devez construire les clés au vol ou n'écrire des métadonnées que sous condition.

Disponibilité par plan : à vérifier avant de câbler quoi que ce soit

C'est la nuance qui manque à la plupart des tutoriels. Le node apparaît dans le panneau de n'importe quelle instance, mais la fonctionnalité de données d'exécution personnalisées est soumise au plan. La documentation n8n le formule sans ambiguïté :

Custom executions data is available on: Cloud: Pro, Enterprise; Self-Hosted: Enterprise, registered Community

Traduit en décisions pratiques :

• n8n Cloud : les plans d'entrée n'y donnent pas accès. Il faut au minimum le plan Pro, ou Enterprise.
• Self-hosted : accessible avec une licence Enterprise… ou avec une Community edition enregistrée. Ce second cas est le moins connu et le plus intéressant : la Community edition self-hosted, gratuite, débloque la fonctionnalité en demandant une clé de licence par email (Settings > Usage and plan > Unlock), aux côtés des dossiers de workflows et du debug dans l'éditeur.

Autrement dit : si vous auto-hébergez, ce guide vous concerne pour zéro euro, mais seulement après enregistrement de l'instance. Sur le plan Cloud d'entrée, le node s'exécutera sans erreur visible, mais le filtre correspondant n'apparaîtra pas dans la liste des exécutions — vérifiez-le avant de refactoriser dix workflows. C'est aussi un critère quand vous séparez développement et production : une instance de test non enregistrée ne reproduira pas le comportement de la prod.

Les limites exactes (et une ambiguïté de la documentation)

Les contraintes documentées sont volontairement serrées, parce que ces données sont indexées pour la recherche :

• Maximum 10 éléments de données personnalisées par exécution.
• Clé : 50 caractères maximum.
• Valeur : elle doit être une chaîne de caractères. Sur la longueur, la documentation n'est pas cohérente — la page du node annonce 512 caractères, la page consacrée aux données d'exécution personnalisées annonce 255. En attendant que les deux convergent, restez sous 255 caractères : c'est la borne prudente, et aucune clé de recherche utile n'a besoin de plus.
• En cas de dépassement, n8n tronque la valeur et journalise l'événement plutôt que de faire échouer l'exécution.

Point de vigilance sur le typage : un order_id numérique doit être converti (String($json.order_id)) si vous passez par le node Code. Via le node Execution Data, l'expression est déjà rendue sous forme de texte.

Où placer le node dans le workflow

La règle est simple : le plus tôt possible après que l'identifiant métier soit connu, et jamais après un point susceptible d'échouer.

• Juste après le trigger, quand le webhook porte déjà l'identifiant. Placement idéal : même si le workflow plante trois nodes plus loin, l'exécution en échec reste retrouvable.
• Après le premier enrichissement, quand l'identifiant vient d'un appel API. Vous perdez la traçabilité des exécutions qui échouent avant ce point : compensez avec une clé grossière posée en amont (source: webhook_stripe).
• Plusieurs fois, pour enrichir progressivement : une clé au trigger, une autre après la décision d'un agent. Les appels successifs ajoutent des clés (set) ; attention à setAll(), qui remplace l'objet entier.

Dans un découpage en sub-workflows, chaque sub-workflow exécuté dans son propre contexte génère sa propre exécution : posez les mêmes clés des deux côtés, sinon vous retrouverez le parent sans l'enfant. Et dans un error workflow, ces métadonnées font un excellent contenu d'alerte — « échec sur la commande CMD-20841 » vaut mieux que « échec ».

Choisir ses clés : identifiants stables, et pas plus

Dix clés maximum, cela force à choisir. Les bonnes candidates sont des identifiants métier stables : order_id, ticket_id, customer_id (les clés primaires de vos systèmes) ; source ou channel pour segmenter les volumes ; env si une même instance sert plusieurs contextes ; un statut de décision (route: escalade_humaine) pour retrouver les cas litigieux. Ce sont souvent déjà vos clés d'idempotence : la logique décrite dans notre guide sur l'idempotence des webhooks se réutilise telle quelle, et c'est bon signe — une clé qui identifie un événement de façon fiable identifie aussi une exécution de façon fiable.

À l'inverse, évitez d'y mettre des données personnelles quand un identifiant technique suffit. Email, nom, téléphone : ces valeurs sont stockées avec l'exécution en base et s'affichent dans les filtres à toute personne ayant accès à l'interface. Sous l'angle RGPD, c'est de la minimisation élémentaire : customer_id: 4821 permet exactement la même recherche que email: prenom.nom@societe.fr, sans créer un nouveau traitement de données identifiantes dans un journal technique dont la rétention est rarement documentée. Pour une piste plus riche et opposable, le bon endroit est une table dédiée avec sa politique de conservation — l'approche détaillée dans notre guide sur la piste d'audit RGPD avec n8n et Supabase.

Cette distinction entre métadonnée de recherche et journal de provenance n'est pas nouvelle. Le travail de référence de Yogesh L. Simmhan, Beth Plale et Dennis Gannon, « A Survey of Data Provenance in e-Science » (ACM SIGMOD Record, 2005), classe les systèmes de provenance selon pourquoi elle est enregistrée, ce qu'elle décrit et comment elle est stockée — et montre que les usages « découverte et recherche » n'appellent pas le même niveau de détail que les usages « audit et reproductibilité ». Les données d'exécution n8n relèvent clairement du premier.

Relire les valeurs : c'est le node Code, pas le node Execution Data

Piège classique : le node Execution Data ne sait pas relire ce qu'il a écrit. Sa seule opération est l'écriture. Pour récupérer les valeurs pendant l'exécution, passez par un node Code :

const orderId = $execution.customData.get('order_id');
const all = $execution.customData.getAll();

return [{ json: { orderId, all, executionId: $execution.id } }];

$execution.id est le complément naturel : l'identifiant technique unique de l'exécution en cours. Le pattern qui marche bien consiste à écrire cet ID dans votre système métier — un champ n8n_execution_id sur la commande ou le ticket — pendant que le node Execution Data écrit l'identifiant métier dans n8n. Le lien devient bidirectionnel : depuis le CRM vous ouvrez l'exécution par son URL, depuis n8n vous filtrez par numéro de commande. Même principe que pour la journalisation des décisions d'un agent IA, à ceci près que la donnée reste ici volontairement minuscule.

Annotations, pruning et Insights : les trois compléments

Les annotations d'exécution (tags et notation posés manuellement depuis l'interface) répondent à un besoin différent : marquer a posteriori un cas intéressant, alors que les données personnalisées sont posées automatiquement. Elles ont un effet de bord précieux, documenté par n8n : les exécutions annotées ne sont jamais supprimées par le pruning automatique. Si votre instance purge l'historique via EXECUTIONS_DATA_MAX_AGE ou EXECUTIONS_DATA_PRUNE_MAX_COUNT, un tag est le moyen le plus simple de sanctuariser une exécution de référence — à garder en tête en lisant notre guide sur le nettoyage des exécutions et de la base n8n.

Insights travaille à l'étage au-dessus : agrégats de volume, taux d'échec, temps gagné, comme détaillé dans notre guide de n8n Insights. Les deux se complètent — Insights vous dit qu'il y a eu 12 échecs cette semaine, les données personnalisées vous disent lesquels. Pour sortir de l'interface, les exécutions restent interrogeables par l'API REST de n8n.

Quand ce dispositif ne suffit plus — traçage fin des étapes d'un agent, comparaison de prompts, latence par appel — le besoin relève d'un outil dédié, comme décrit dans notre guide sur l'observabilité des agents IA avec Langfuse.

En résumé

Le node Execution Data fait une chose et la fait bien : attacher jusqu'à 10 paires clé/valeur (clé ≤ 50 caractères, valeur en chaîne, à garder sous 255 caractères) à l'exécution en cours, via son unique opération Save Execution Data for Search, pour la retrouver ensuite par filtre. Placez-le tôt, dès que l'identifiant métier est connu ; choisissez des identifiants stables plutôt que des données personnelles ; relisez les valeurs avec $execution.customData.get() dans un node Code, jamais avec le node lui-même. Et vérifiez d'abord votre plan : Cloud Pro ou Enterprise, self-hosted Enterprise, ou — c'est la bonne nouvelle — Community edition self-hosted simplement enregistrée, gratuitement.

Pour aller plus loin

Si votre motivation est la traçabilité réglementaire plutôt que le confort de débogage, le Pack Conformité & Audit (149 €) va plus loin que les 10 clés autorisées ici : il structure une piste d'audit externalisée, avec rétention maîtrisée et minimisation des données — exactement ce que les données d'exécution n8n ne sont pas censées porter. Pour un workflow d'emails où l'enjeu est de retrouver vite « le mail du client X », le Pack Inbox IA (79 €) arrive déjà câblé avec les identifiants métier aux bons endroits.