AIワークフローで失敗ログを残す方法｜原因追跡できる形にする

AIワークフローの失敗を後から調べるには、「Errorになった」という記録だけでは足りません。どのRunのどのStepで、どの入力の参照を使い、何回目の試行で、どの種類の失敗になったかを結びます。顧客データやSecretを扱う場合は、原因追跡に必要な項目と、通常ログへ残さない項目を同時に決めます。

最初に、ログの目的を二つに分けてください。運用ログは「止まった処理を見つけ、次のActionを選ぶ」ための記録です。監査ログは「誰が何を変更したか、いつ判断したか」を後から説明する記録です。同じ保管先を使う場合でも、閲覧権限、保存期間、検索キーは同一とは限りません。すべての入力や出力を長期間保存することを、観測性の前提にしないでください。

失敗ログの最小Schema

表は横にスクロールできます

Field	役割	例・注意
run_id	一回のWorkflow実行を識別	再試行で新Runができる設計なら、親Runとの関連も記録
event_id	外部EventとRunを結ぶ	送信元が提供する安定IDがあれば利用。個人情報をIDへ埋め込まない
correlation_id	複数Systemをまたぐ処理を追跡	内部で生成する場合は衝突・保持範囲を設計
workflow_version	実行時点の定義を特定	編集後の再実行と元の実行を区別
step_id / step_name	失敗場所を特定	表示名だけでなく、変更されにくい識別子も検討
status / error_type	失敗と次Actionを分類	timeout、validation、認証、rate limit、外部障害など
occurred_at	時系列を比較	UTCなどの基準と、発生時刻・記録時刻の区別を統一
attempt / retry_of	試行回数と前回実行を結ぶ	無限Retryや別Eventの混同を防ぐ
input_ref / output_ref	必要なデータへ限定的に参照	参照先の権限・期限・削除方針を確認
next_action / owner	誰が何をするか示す	自動Retry、人手修正、調査待ち、停止を区別
duration_ms / external_status	遅延と応答の状況を比較	外部APIの応答コード等は必要な範囲で保持

これは全システム共通の標準Schemaではなく、記事内で設計を始めるための例です。使っているWorkflow製品がRun ID、Step ID、Error codeなどを既に出力するなら、まずその公式仕様と実データを確認し、同じ意味のFieldを二重管理しないようにします。製品間で名前が異なる場合は、対応表を作ってから共通ログへ変換してください。

Run・Event・Step・Attemptを混ぜない

RunはWorkflowの一回の実行、Eventはその起点となった業務上の入力、Stepは実行内の処理単位、Attemptは同じ処理を試した回数です。これらを一つの「実行ID」へまとめると、Webhook再送で新Runができたのか、同一Run内のRetryなのかが分からなくなります。

例えば、問い合わせEvent evt-42からCRM登録、通知、完了記録を行うとします。最初のRunが通知StepでTimeoutし、確認のため再実行した場合、ログでは新しいRun IDと同じEvent ID、対象Step、前回RunまたはRetry元、Attempt番号を結びます。CRM登録が完了済みならその結果を参照し、通知だけ再開できるかを判断します。再実行後のログを元の行へ上書きせず、試行ごとに時系列を残すと、いつ何を判断したかを後から追えます。

event_id = evt-42

run_id = run-20261006-01

workflow_version = wf-v12

step_id = send_notification

attempt = 1

status = failed

error_type = timeout

retry_of = null

next_action = check_remote_result

input_ref = request-opaque-73

上記は架空データであり、実サービスを使った検証結果ではありません。識別値も説明用です。実ログへメールアドレス、本文、認証Tokenをそのまま入れず、制御された参照値を使います。相関IDから入力を取得できる仕組みを作る場合は、参照先にも同じアクセス制御・監査・削除方針が必要です。

Errorを「原因」ではなく「次の判断」に結び付ける

分類名は細かくしすぎず、担当者が次に何をするか決められる粒度にします。たとえばValidationなら入力またはMappingの修正、Authenticationなら接続・権限の確認、Rate limitなら提供元の待機条件確認、Timeoutなら相手側で処理が完了したか照会、外部Service障害なら状態ページや再試行条件の確認、AI OutputならSchema検証と人手Reviewです。

表は横にスクロールできます

分類	ログで残すもの	次の判断
Validation	不足・形式違反のField名。値そのものは必要性を確認	入力修正までHold
Authentication	接続名、失敗Step、応答の分類	資格情報や権限を確認。Secretは記録しない
Rate limit	提供元、応答分類、発生時刻、Retry予定	公式の待機・上限条件を確認
Timeout	要求識別子、送信時刻、外部結果の確認状況	成功済みか不明なら照会してから再送
External service	依存先、status、影響範囲	復旧待ちか、手動処理かを決定
AI Output	モデル／Promptの版を必要な範囲で識別、検証結果	失敗値を業務へ渡さずReviewへ

Error Message全文やHTTP Request bodyを保存すると、診断には便利でも個人情報・認証情報・機密値が混ざることがあります。ログへ残す前に、Message、Header、Payload、URL queryへSecretが含まれないか確認します。必要な場合も、マスク済みの分類、限定された参照先、短い保持期間のいずれが適切かを選びます。

失敗から復旧する流れ

1. Alertまたは失敗行からrun_idを開き、対象Workflowとversionを確認する。

2. event_id、step_id、attemptで同じ業務Eventの過去Runを探す。

3. 最後に成功したStepと失敗Step、外部Actionの送信有無を区別する。

4. Error分類に沿って、入力修正・権限確認・待機・外部結果照会・人手Reviewを選ぶ。

5. Retryするなら、再実行範囲、完了済みActionの扱い、回数と期限を確認する。

6. 新しいAttemptを作り、前の試行を参照して結果を比較する。

7. 復旧後は原因、再発防止、残った手動作業を記録する。

プラットフォームのExecution履歴は、実行の確認・再開に役立つ場合があります。ただし、表示項目、保存期間、再実行時に使うWorkflow版、Incomplete executionの扱いは製品ごとに異なります。n8nの実行一覧、MakeのIncomplete executions、ZapierのRun detailsやLog streamsは同一機能ではありません。導入時には公式資料と現在の契約・設定を確認し、記録されるEventの種類や利用条件を前提にします。

Timeoutのログは「未実行」を意味しない

Timeoutは、こちらが応答を受け取れなかったことを示す場合があり、相手側の処理が行われなかった証明ではありません。再送前に、下流Recordの照会、同一Actionの安定Key、送信元のRequest ID、運用担当者の確認など、実際に利用できる結果確認手段を選びます。どの方法も用意できない場合は、成功・失敗を推測せず「結果不明」として止める方が安全です。

この状態をログ上で表すなら、単純なfailedだけでなく、unknown_outcome、確認担当、確認期限、照会結果などを持たせます。結果が見つからない場合でも、照会範囲や反映遅延を確認し、即座に未作成と判断しないようにします。重複実行の防止が重要なActionほど、再試行の前提と停止条件をRunbookに明記してください。

ログに残さないものを先に決める

次の項目は既定でログへコピーせず、必要性を個別に確認します。

• API Key、OAuth Token、Cookie、Authorization Header、パスワード

• 顧客メールアドレス、氏名、自由記述本文などの個人情報

• AIへ渡したPromptや添付ファイル全文

• 決済・人事・健康等の高機密データ

• 認証情報を含むURLや、秘密値を含むQuery parameter

エラーを再現するために入力本文が必要だと感じても、まず再現用の合成データ、Field単位の型・長さ、赤字化したExcerpt、制御された保管先で代替できないか確認します。ログの閲覧者、利用目的、保持期間、削除方法、Export先も決めてください。ログシステムが別Serviceへ転送するなら、転送先のRegion、権限、暗号化、保持条件も確認します。法務・Privacy上の保存条件がある場合は、一般的な推奨だけで独自判断せず、社内の適用ルールを優先します。

失敗ログの動作を検証する

正常に成功した一回だけを確認しても、調査に使えるSchemaか分かりません。検証環境で次のケースを用意します。

表は横にスクロールできます

Case	操作	期待するログ
Step失敗	意図的にValidation errorを発生させる	run、event、step、分類、next_actionを追える
一時障害	依存先の応答を一時的に失敗させる	attemptと待機／Retry判断が残る
Timeout	応答が受け取れない状況を作る	結果不明を区別し、無条件再送しない
Retry	修正後に再開する	新しいAttemptが元Run・Eventへ結び付く
複数Action	前段成功、後段失敗にする	完了済みActionを区別できる
権限確認	閲覧者を変えてログを見る	必要な担当だけが必要な情報を閲覧できる
Redaction	合成Secretを入力に含める	通常ログ、Alert、Exportへ値が漏れない
保持期限	期限後のデータを確認する	削除・匿名化の仕様どおりになる

各ケースで、記録が出たことだけでなく、運用担当者が次のActionを判断できたかを確認します。RetentionやAccess controlは製品・契約・Workspace設定で変わるため、実際の設定画面と公式資料を照合してください。テストデータに本番の顧客情報や実Secretを使う必要はありません。

30秒で確認するRun一覧

運用画面や通知を設計するなら、最初に見る項目を絞ります。時刻、Workflow名・version、Run ID、失敗Step、分類、Attempt、次Action、担当、結果不明かどうかが一覧で分かると、個別Payloadを開く前に優先度を判断できます。失敗した行をクリックして、Run detailからStep、前後State、外部応答の参照へ進める構造にします。

一覧のStatusだけで正常・異常を断定しないことも大切です。Handled error、警告付き完了、Incomplete execution、意図的な停止などは、Workflow製品で表示意味が異なります。Statusの翻訳表を作る場合は、各製品の公式定義を確認し、業務側の「通知が必要」「人手待ち」「再送禁止」といった判断を別項目で持たせてください。

調査できるかを評価する

失敗ログの価値は、保存するFieldの多さではなく、実際の問いへ答えられるかで評価できます。次の問いを、合成データを使って10分以内に調査できるか試してください。

• どのEventとRunが影響を受けたか

• どのStepで、何回目に失敗したか

• 下流Actionが送信済みか、結果不明か

• 再試行で重複や二重請求を起こさないか

• 誰が次の対応を行い、どこへ結果を残すか

• 必要なInputを見ずに原因を切り分けられるか

• 記録を見られる担当と、保存終了時点が明確か

答えられない問いがあれば、Field追加の前に、IDの関連付け、Statusの定義、結果照会の手順、担当通知のいずれが欠けているかを特定します。Fieldを追加しても、情報源が取れない、同じ値が常に空、誰も保守しないという状態なら観測性は改善しません。

AIものさしの判断

まず一つの重要Workflowで、Run・Event・Step・Attemptを結ぶ最小Schemaを作り、失敗分類ごとに次Actionを定義します。次に、Timeout、複数Actionの途中失敗、Retry、SecretのRedactionを含む検証ケースを実施します。担当者がログから安全な再開判断をできることを確認してから、同じ設計を他Workflowへ適用してください。

ただし、製品のExecution履歴やログ転送機能があるだけで、重複実行・再試行・保管要件が自動的に解決するわけではありません。取得できるEvent、Run詳細、保存期間、アクセス権限を公式仕様と現在の設定で確認し、足りない部分だけを外部ログや運用手順で補います。