ドキュメント走る自動再開

予期せぬ中断と自動再開

ワークフローが途中で中断された場合はどうすればよいですか?リカバリとべき等性を備え、ブレークポイントでダウンロードを再開し、副作用の繰り返しを回避します。

「実行が一度に完了しなかった場合にどうするか」は、運用レベルのワークフローが答えなければならない質問です。 Braidrun は 2 つの処理ソリューションを提供します。

デフォルト: 安全なブレーク — 実行を中断としてマークし、それが明確に表示されるまで待ってから、途中の特定のステップから手動で「再試行」します。
オプション: 自動的に実行を継続します — 「このワークフローは継続可能 + どのステップがべき等であるか」を明示的に宣言すると、プラットフォームは中断ポイントから自動的に継続します。

中断ってどういう意味ですか？

2 つのカテゴリ:

プラットフォーム側 - サービスが再起動され、インスタンスが置き換えられ、ホストに障害が発生します。私たちはこれらを避けようとしますが、100% 避けられるわけではありません。
あなた側では、実行を積極的に「キャンセル」します（中断ではなくキャンセルで停止します）。

前者のカテゴリのみが「自動継続」処理に入り、CANCELLED の実行は自動的には実行されません。

デフォルトの動作: 安全なブレーク

プラットフォーム側の割り込みが発生すると、プラットフォームは次のことを行います。

実行ステータスを中断としてマークします。
完了したすべてのステップの結果、生成物、ログを保存します。
オンサイト通知を受け取ります (電子メール/Slack も通知に従って設定されます)。
実行の詳細ページに移動すると、「失敗したステップから再試行」することができます。プラットフォームは前のステップの結果を再利用します。

このデフォルトはすべてのワークフローで使用でき、構成は必要ありません。以下に適しています:

ワークフローには外部の副作用（電子メールの送信/金額の差し引き/データベースの変更）が含まれています
本番環境が「再起動して実行を継続しても安全かどうか」がまだわからない場合

オプション: 自動的に実行を継続します

ワークフローが純粋なデータパイプライン (読み取り専用 API + レポート生成) の場合は、自動継続を有効にすることができます。中断が発生した後、プラットフォームは手動でクリックする必要がなく、中断ポイントから自動的に実行を継続します。

2 層オプトインが有効になっています

自動継続を有効にするには、両方のレイヤーを YAML で宣言する必要があります。

ワークフローレベル: 宣言 recovery.autoResumeOnRestart: true
ステップレベル: 安全に再実行するための段階的な手順 idempotent: true

完全な例

yaml

name: daily-asa-digest
version: "1.0.0"

recovery:
  autoResumeOnRestart: true
  policy: RESUME_FROM_LAST_INCOMPLETE
  maxAutoResumeAttempts: 3

steps:
  - id: fetch_asa_data
    type: sub_workflow
    module: dingyue-module-asa-fetch
    idempotent: true           # 只读拉取，可重跑

  - id: build_excel
    type: sub_workflow
    module: dingyue-module-excel-report
    idempotent: true           # 生成文件到产物目录，可重跑

  - id: notify_team
    type: sub_workflow
    module: dingyue-module-slack-deliver
    # 不写 idempotent —— 默认 false，发消息不可重跑

3つのリカバリーポリシー

policy	意味	シーンに合わせて
`ABORT`	自動的に復元しないことは、デフォルトの動作に戻すことと同じです。	テスト段階
`RESUME_FROM_LAST_INCOMPLETE`	デフォルト。最初の完了していないステップから再実行します。	データパイプライン、読み取り専用 API 集約、純粋な計算
`RESUME_FROM_START`	ワークフロー全体を最初から再実行する	停止中にデータソースが変更される可能性があり、更新が必要になるシナリオ

idempotent マークの付け方

ステップが冪等であるかどうかを判断するためのゴールドスタンダードは次のとおりです。

「同じ入力を 2 回実行した場合、副作用はありますか?」

可能であれば (外部メッセージを送信したり、お金を請求したり、注文を書き込んだり)、冪等性を追加しないでください。

ステップのプロパティ	`idempotent`
読み取り専用 API クエリ (プルレポート、リストアプリ)	✓ true
純粋な計算/データ変換	✓ true
Markdown/Excel を製品ディレクトリに生成	✓ true(古い製品は再実行前に消去されます)
LLM 推論 (副作用のないツール)	✓ true(トークンは再計算されますが、意味的には安全です)
メール送信 / 電報 / Slack / フェイシュ	✗ false
外部DBへの書き込み/広告入札額変更/注文/引き落とし	✗ false
Webhook アウトバウンドコール	✗ false(他のエンドポイントが重複を明示的に削除しない限り)
manual_approval	✗ false(実行を続行すると、承認者に再度 ping が送信され、エクスペリエンスが低下します)

デフォルト値は false - 安全第一

idempotent が記述されていない場合、デフォルトは false です。 RESUME_FROM_LAST_INCOMPLETE は、冪等でないステップに遭遇すると ABORT にダウングレードします。これは自動的には実行されず、手動で実行する必要があります。

自動継続中に発生しないいくつかの状況

リカバリを構成した場合でも、次の実行は自動的に実行され続けません。

トリガーソースは Webhook です。Webhook ペイロードは最大 1 回である可能性があり、プラットフォームはアップストリームが再試行するかどうかを知りません。
トリガーソースはスケジューラです。スケジューラは cron の次のラウンドでそれ自体を再起動します。
現在、manual_approval で停止しています - 承認待ちということは、もともとブロックされていることを意味します。
ワークフロー定義ファイルは停止中に変更されました。プラットフォームはハッシュの不一致を検出しましたが、新しいバージョンに互換性があるかどうかは不明です。

マニュアル「ステップから再試行」（いつでも利用可能）

ワークフローにリカバリが構成されているかどうかに関係なく、実行の詳細ページには常に「失敗したステップから再試行」ボタンが表示されます。

Open an INTERRUPTED / FAILED execution;
失敗/中断されたステップの横にある「このステップから再試行」をクリックします。
以前の COMPLETED ステップの結果が再利用されます。このステップは再び実行を開始します。

ステップが冪等でない場合でも、手動で再試行できます。それは、人間として意識的に「再実行する価値がある」と判断したときだからです。

継続走行制限

システムが「無限ループ」で同じ実行を再起動しないようにします。各実行は自動的に最大 3 回まで実行を継続します。それでも失敗する場合は、停止して対処するまで待ちます。 Recovery.maxAutoResumeAttempts の (1 ～ 20) をオーバーライドできます。

監査

監査イベントは、自動継続が実行されるたびに記録されます。

execution.auto_resume — 正常に走行を継続しました
execution.auto_resume.skipped — ルールによれば、理由があれば走り続けてはいけない

管理者は、これら 2 つのイベントタイプによって監査ログをフィルタリングして表示できます。

実践的な提案

純粋なデータパイプライン (ASA 日次、RSS サマリー): 完全なリカバリ + 冪等。自動的に実行を継続しますのでご安心ください。
外部の副作用がある場合 (控除、メッセージの送信、注文): 自動再開を開かないでください。人間の意思決定を妨害する。
主要な副作用手順の前に、manual_approval を追加します。承認自体が、不連続な実行の「自然なブロックポイント」になります。

次のステップ

実行の監視とログ記録 — 中断状態での実行を表示する方法
ベストプラクティス — 冪等なアノテーション/分割/モジュール化に関する包括的な提案