Un workflow avec 12 étapes, deux branches conditionnelles et une boucle échoue à la troisième itération de la deuxième sous-étape de la boucle. Le message d’erreur dit « format de réponse inattendu ». Par où commencer ?
Sans données d’exécution détaillées, vous devinez. Avec les traces d’exécution, vous voyez exactement ce qui s’est passé — chaque entrée, chaque sortie, chaque limite de timing, chaque tentative de réessai — dans une vue hiérarchique qui reflète la structure du workflow.
Ce que les traces d’exécution capturent
Chaque exécution de workflow produit une trace d’exécution : un arbre de spans qui reflète le graphe d’exécution du workflow. Chaque span enregistre :
- Identité de l’étape — Quelle étape, par ID et nom
- Timing — Heure de début, heure de fin et durée en millisecondes
- Entrées — Les valeurs exactes passées à l’étape après résolution des templates
- Sorties — La sortie structurée produite par l’étape (ou l’erreur levée)
- Tentatives de réessai — Si l’étape a réessayé, chaque tentative est enregistrée avec son erreur et le délai de backoff avant la tentative suivante
- Contexte d’imbrication — Quelle branche d’une condition, quelle itération d’une boucle, quelle branche d’une étape parallèle
Structure hiérarchique
L’arbre de traces suit exactement la structure du workflow :
Exécution du Workflow
├── Étape 1 : Rechercher le prospect (recette) — 2,3s, succès
├── Étape 2 : Qualifier le lead (recette) — 1,8s, succès
├── Étape 3 : Condition (score >= 70)
│ └── Branche Alors
│ ├── Étape 3a : Parallèle
│ │ ├── Branche A : Rédiger l'email — 3,1s, succès
│ │ └── Branche B : Rédiger le message LinkedIn — 2,7s, succès
│ └── Étape 3b : Revue (approbation) — en attente
└── Étape 4 : Archiver (ignorée — la condition a pris la branche alors)Les branches conditionnelles montrent quel chemin a été pris et pourquoi. Les boucles montrent chaque itération avec son élément et les résultats des sous-étapes. Les branches parallèles montrent l’exécution concurrente avec les timings individuels.
Trois couches d’observabilité
Les traces d’exécution sont l’une des trois couches d’observabilité complémentaires :
Les traces d’exécution (Firestore) sont l’outil d’inspection détaillé par exécution. Elles alimentent l’interface d’inspection des exécutions et sont conçues pour déboguer des exécutions individuelles. Chaque exécution génère une trace, et les traces sont conservées pendant toute la durée de vie de l’enregistrement d’exécution.
Les métriques Prometheus suivent la santé opérationnelle agrégée : nombre total d’exécutions, taux de succès, percentiles de durée et compteurs d’erreurs. Elles alimentent les tableaux de bord et les alertes — « le taux de succès du workflow X est passé sous 95 % dans la dernière heure. »
Les spans OpenTelemetry fournissent le traçage distribué à travers les frontières de services. Le wrapper withSpan() crée des spans pour tout chemin de code instrumenté, transportant les métadonnées de workflow et d’étape. Ils s’intègrent avec tout backend compatible OTel (Jaeger, Datadog, Honeycomb) pour la corrélation de traces inter-systèmes.
Utiliser les traces pour déboguer
Trouver le point de défaillance
Ouvrez la page de détail de l’exécution et développez l’arbre de traces. Les étapes échouées sont mises en évidence. Cliquez sur l’étape échouée pour voir ses entrées exactes et le message d’erreur. Comparez les entrées à ce que vous attendiez — souvent le problème est une étape en amont produisant une sortie inattendue qui est passée à une étape en aval.
Repérer les problèmes de résolution de templates
La trace de chaque étape montre les valeurs d’entrée résolues — après substitution des templates. Si une étape attendait {{step.research.company_name}} mais a obtenu undefined, la trace vous montre la valeur réellement résolue. Vérifiez si l’étape référencée a produit le champ de sortie attendu.
Identifier les goulots d’étranglement de performance
Triez par durée pour trouver les étapes les plus lentes. Une étape qui prend 15 secondes quand des étapes similaires prennent 2 secondes pourrait atteindre une limite de taux, utiliser un modèle plus coûteux que nécessaire, ou traiter une entrée inhabituellement volumineuse.
Déboguer le comportement de réessai
Quand une étape a réessayé avant de réussir (ou d’échouer définitivement), la trace montre chaque tentative : l’erreur qui a déclenché le réessai, le délai de backoff et le résultat de la tentative suivante. Schémas courants : limites de taux transitoires 429 (les réessais réussissent après le backoff), erreurs persistantes 400 (tous les réessais échouent avec la même erreur — corrigez l’entrée, pas le nombre de réessais).
Les traces sont automatiques
Vous n’avez pas à configurer le traçage. Chaque exécution de workflow produit une trace, chaque étape est instrumentée, et la trace est persistée de manière asynchrone (fire-and-forget) pour ne pas ralentir l’exécution. L’inspecteur d’exécution lit les traces à la demande quand vous ouvrez la vue détaillée.
Les traces d’exécution sont disponibles sur tous les plans. Les métriques Prometheus et l’intégration OpenTelemetry sont disponibles sur Enterprise. En savoir plus sur les workflows ou commencez votre essai gratuit.