Ein Workflow mit 12 Schritten, zwei bedingten Verzweigungen und einer Schleife scheitert in der dritten Iteration des zweiten Teilschritts der Schleife. Die Fehlermeldung sagt “unexpected response format.” Wo fangen Sie an?
Ohne detaillierte Ausführungsdaten raten Sie. Mit Execution Traces sehen Sie genau, was passiert ist — jede Eingabe, jede Ausgabe, jede Zeitgrenze, jeden Wiederholungsversuch — in einer hierarchischen Ansicht, die die Struktur des Workflows widerspiegelt.
Was Execution Traces erfassen
Jeder Workflow-Run erzeugt einen Execution Trace: einen Baum von Spans, der den Ausführungsgraphen des Workflows widerspiegelt. Jeder Span zeichnet auf:
- Schritt-Identität — Welcher Schritt, nach ID und Name
- Zeiterfassung — Startzeit, Endzeit und Dauer in Millisekunden
- Eingaben — Die exakten Werte, die nach Template-Auflösung an den Schritt übergeben wurden
- Ausgaben — Die strukturierte Ausgabe, die der Schritt produziert hat (oder der Fehler, den er geworfen hat)
- Wiederholungsversuche — Wenn der Schritt wiederholt wurde, wird jeder Versuch mit seinem Fehler und der Backoff-Verzögerung vor dem nächsten Versuch aufgezeichnet
- Verschachtelungskontext — Welcher Zweig einer Bedingung, welche Iteration einer Schleife, welcher Zweig eines parallelen Schritts
Hierarchische Struktur
Der Trace-Baum folgt exakt der Struktur des Workflows:
Workflow Run
├── Schritt 1: Interessent recherchieren (Recipe) — 2,3s, Erfolg
├── Schritt 2: Lead qualifizieren (Recipe) — 1,8s, Erfolg
├── Schritt 3: Bedingung (Score >= 70)
│ └── Then-Zweig
│ ├── Schritt 3a: Parallel
│ │ ├── Zweig A: E-Mail entwerfen — 3,1s, Erfolg
│ │ └── Zweig B: LinkedIn-Nachricht entwerfen — 2,7s, Erfolg
│ └── Schritt 3b: Überprüfung (Genehmigung) — wartend
└── Schritt 4: Archivieren (übersprungen — Bedingung nahm Then-Zweig)Bedingte Verzweigungen zeigen, welcher Pfad genommen wurde und warum. Schleifen zeigen jede Iteration mit ihrem Element und den Ergebnissen der Teilschritte. Parallele Zweige zeigen gleichzeitige Ausführung mit individuellen Zeitmessungen.
Drei Ebenen der Observability
Execution Traces sind eine von drei komplementären Observability-Ebenen:
Execution Traces (Firestore) sind das detaillierte Inspektionstool für einzelne Runs. Sie treiben die Run-Inspector-UI an und sind zum Debuggen einzelner Runs konzipiert. Jeder Run erhält einen Trace, und Traces werden für die Lebensdauer des Run-Datensatzes aufbewahrt.
Prometheus-Metriken verfolgen den aggregierten Betriebszustand: Gesamtausführungen, Erfolgsraten, Dauer-Perzentile und Fehlerzähler. Diese speisen Dashboards und Alerting — “Workflow X’s Erfolgsrate ist in der letzten Stunde unter 95% gefallen.”
OpenTelemetry-Spans bieten verteiltes Tracing über Service-Grenzen hinweg. Der withSpan()-Wrapper erstellt Spans für jeden instrumentierten Codepfad und trägt Workflow- und Schritt-Metadaten. Diese integrieren sich mit jedem OTel-kompatiblen Backend (Jaeger, Datadog, Honeycomb) zur systemübergreifenden Trace-Korrelation.
Traces zum Debuggen verwenden
Den Fehlerpunkt finden
Öffnen Sie die Run-Detailseite und erweitern Sie den Trace-Baum. Fehlgeschlagene Schritte sind hervorgehoben. Klicken Sie auf den fehlgeschlagenen Schritt, um seine exakten Eingaben und die Fehlermeldung zu sehen. Vergleichen Sie die Eingaben mit dem, was Sie erwartet haben — oft liegt das Problem darin, dass ein vorgelagerter Schritt unerwartete Ausgaben produziert, die an einen nachgelagerten Schritt weitergegeben werden.
Template-Auflösungsprobleme erkennen
Der Trace jedes Schritts zeigt die aufgelösten Eingabewerte — nach Template-Substitution. Wenn ein Schritt {{step.research.company_name}} erwartet hat, aber undefined erhalten hat, zeigt der Trace den tatsächlich aufgelösten Wert. Prüfen Sie, ob der referenzierte Schritt das erwartete Ausgabefeld produziert hat.
Performance-Engpässe identifizieren
Sortieren Sie nach Dauer, um die langsamsten Schritte zu finden. Ein Schritt, der 15 Sekunden dauert, während ähnliche Schritte 2 Sekunden brauchen, trifft möglicherweise auf ein Rate Limit, verwendet ein teureres Modell als nötig oder verarbeitet unerwartet große Eingaben.
Retry-Verhalten debuggen
Wenn ein Schritt vor dem Erfolg (oder endgültigen Fehlschlag) wiederholt wurde, zeigt der Trace jeden Versuch: den Fehler, der die Wiederholung ausgelöst hat, die Backoff-Verzögerung und das Ergebnis des nächsten Versuchs. Häufige Muster: transiente 429-Rate-Limits (Wiederholungen erfolgreich nach Backoff), persistente 400-Fehler (alle Wiederholungen scheitern mit demselben Fehler — beheben Sie die Eingabe, nicht die Anzahl der Wiederholungen).
Traces sind automatisch
Sie konfigurieren kein Tracing. Jeder Workflow-Run erzeugt einen Trace, jeder Schritt ist instrumentiert, und der Trace wird asynchron persistiert (Fire-and-Forget), sodass er die Ausführung nicht verlangsamt. Der Run-Inspector liest Traces bei Bedarf, wenn Sie die Detailansicht öffnen.
Execution Traces sind in allen Tarifen verfügbar. Prometheus-Metriken und OpenTelemetry-Integration sind im Enterprise-Tarif verfügbar. Mehr über Workflows erfahren oder kostenlose Testversion starten.