12ステップ、2つの条件分岐、ループを持つworkflowが、ループの3回目のイテレーションの2番目のサブステップで失敗します。エラーメッセージは「unexpected response format」。どこから始めますか？
詳細な実行データがなければ、推測するしかありません。実行トレースがあれば、何が起こったかが正確に分かります——すべての入力、すべての出力、すべてのタイミング境界、すべてのリトライ試行——workflowの構造をミラーリングする階層的なビューで。
実行トレースが記録するもの
すべてのworkflow実行は実行トレースを生成します：workflowの実行グラフをミラーリングするスパンのツリーです。各スパンは以下を記録します：
- ステップID — どのステップか（IDと名前で）
- タイミング — 開始時刻、終了時刻、ミリ秒単位の所要時間
- 入力 — テンプレート解決後にステップに渡された正確な値
- 出力 — ステップが生成した構造化出力（またはスローしたエラー）
- リトライ試行 — ステップがリトライした場合、各試行がそのエラーと次の試行前のバックオフ遅延とともに記録
- ネストコンテキスト — 条件のどの分岐か、ループのどのイテレーションか、並列ステップのどのブランチか
階層構造
トレースツリーはworkflowの構造に正確に従います：
Workflow Run
├── Step 1: Research prospect (recipe) — 2.3s, success
├── Step 2: Qualify lead (recipe) — 1.8s, success
├── Step 3: Condition (score >= 70)
│ └── Then branch
│ ├── Step 3a: Parallel
│ │ ├── Branch A: Draft email — 3.1s, success
│ │ └── Branch B: Draft LinkedIn message — 2.7s, success
│ └── Step 3b: Review (approval) — waiting
└── Step 4: Archive (skipped — condition took then-branch)条件分岐はどのパスが取られ、なぜ取られたかを表示します。ループは各イテレーションとそのアイテムおよびサブステップの結果を表示します。並列ブランチは個別のタイミングとともに並行実行を表示します。
3つの可観測性レイヤー
実行トレースは3つの補完的な可観測性レイヤーの1つです：
実行トレース（Firestore）は詳細な、実行ごとの検査ツールです。実行インスペクターUIを強化し、個々の実行のデバッグ用に設計されています。すべての実行にトレースがあり、トレースは実行レコードの存続期間中保持されます。
Prometheusメトリクスは集約された運用ヘルスを追跡します：総実行数、成功率、所要時間のパーセンタイル、エラー数。ダッシュボードとアラートに使用されます——「workflow Xの成功率が過去1時間で95%を下回った」。
OpenTelemetryスパンはサービス境界をまたがる分散トレーシングを提供します。withSpan()ラッパーがインストルメント化されたコードパスにworkflowとステップのメタデータを含むスパンを作成します。OTel互換のバックエンド（Jaeger、Datadog、Honeycomb）と統合してクロスシステムトレース相関が可能です。
トレースを使用したデバッグ
障害箇所の特定
実行詳細ページを開き、トレースツリーを展開します。失敗したステップがハイライトされます。失敗したステップをクリックして正確な入力とエラーメッセージを確認します。入力を期待と比較してください——多くの場合、上流のステップが予期しない出力を生成し、下流のステップに渡されたことが問題です。
テンプレート解決の問題の発見
各ステップのトレースは解決された入力値——テンプレート置換後——を表示します。ステップが{{step.research.company_name}}を期待していたがundefinedを得た場合、トレースは実際の解決された値を表示します。参照されたステップが期待される出力フィールドを生成したか確認してください。
パフォーマンスボトルネックの特定
所要時間でソートして最も遅いステップを見つけます。類似のステップが2秒かかるのに15秒かかるステップは、レート制限にヒットしている、必要以上に高価なモデルを使用している、または予想以上に大きな入力を処理している可能性があります。
リトライ動作のデバッグ
ステップが成功前（または永続的に失敗する前）にリトライした場合、トレースは各試行を表示します：リトライをトリガーしたエラー、バックオフ遅延、次の試行の結果。一般的なパターン：一時的な429レート制限（バックオフ後にリトライが成功）、永続的な400エラー（すべてのリトライが同じエラーで失敗——リトライ回数ではなく入力を修正してください）。
トレースは自動的
トレーシングの設定は不要です。すべてのworkflow実行がトレースを生成し、すべてのステップがインストルメント化され、トレースは非同期で永続化されます（fire-and-forget）ため、実行を遅くしません。実行インスペクターは詳細ビューを開いたときにオンデマンドでトレースを読み取ります。
実行トレースはすべてのプランでご利用いただけます。PrometheusメトリクスとOpenTelemetry統合はEnterpriseでご利用いただけます。workflowの詳細を見るか、無料トライアルを開始する。