なぜ Outcome Contract が必要か
実行の監視が答えるのは 2 つだけです。動いたか、エラーが出たか。どちらも「仕事が終わったか」には答えません。Outcome Contract は、本当に知りたい答えを書いておく場所です。書いてあれば、機械が確認できます。
Outcome Contract を設定したワークフローは、すべてのルールを満たしたときだけ正常です。1 つでも満たさなければ OUTCOME_FAILED になり、どのルールで落ちたかを示します。
実例
レポート用のテーブルへ流す日次の取り込みなら、条件はこうなります。
- 平日の 08:30 JST 以降に必ず実行される。
- 実行が成功で終わる。
- 出力が 1 件以上ある。
- 5 分以内に終わる。
- 届け先の確認で、対象テーブルが更新されたことを確かめる。
期限に猶予を足した 08:45 JST に、OutcomeGuard が 5 つを評価します。実行され、成功し、112 件を運び、90 秒で終わり、届け先の確認で新しい行が見つかれば正常です。実行されて 0 件だった場合は正常ではありません。n8n が何を記録していても同じです。
ルールの種類
- must_run
- 対象期間内に実行が始まっていること。
- must_succeed
- その実行が成功で終わっていること。
- items_out_gte
- 最後のノードが N 件以上を出していること。「空は疑わしい」を「空は失敗」に変えるルールです。
- runtime_lt_ms
- 指定した時間内に終わること。遅れが、実行されないのと同じくらい困る場合に使います。
- last_node_is
- 指定したノードで終わること。結果を書き込むノードを指定すれば、1 つ手前で終わった実行を拾えます。
- probe
- OutcomeGuard が行う届け先の確認。連携先が実際に変わったかを確かめます。判定エンジンは確認の結果を判定するだけで、結果を作り出しません。
期限、タイムゾーン、猶予
Outcome Contract の期限は cron 式とタイムゾーンで表し、猶予時間（既定 15 分）を持ちます。猶予を待ってから判定するため、2 分の遅れがインシデントになることはありません。
タイムゾーンは、サーバーの都合ではなく業務の時間に合わせてください。09:00 JST までに手元に届いていないと困るレポートなら、期限は JST で書きます。インスタンスが UTC で動いているかどうかは関係ありません。
届け先の確認（probe）
届け先の確認は、検証の中で n8n の外を見る唯一の部分です。答える問いは「連携先は実際に変わったか」の 1 つだけで、実務では更新の新しさを確かめることになります。見るのは最新の行、ファイルの更新時刻、レコードのフィールドなどです。合否とあわせて、観測した最終更新も報告します。
届け先の確認は、設計上、読み取り専用です。変更を確認するために対象を読みますが、対象へ書き込むことはありません。
誤報で信用を失わない書き方
- 期限は、業務として本当に困る時刻にします。08:30 に予定していても、10:00 までに必要なら期限は 10:00 です。
- items_out_gte は、意味を持つ最小の数にします。多くの場合 1 が適切です。平均に近い数を入れると、閑散日に必ず鳴ります。
- runtime_lt_ms は余裕を持たせます。中央値ではなく、観測した p95 より上に置いてください。
- まず must_run と must_succeed から始めます。件数の条件は 1 週間ほど数字を見てから足し、届け先の確認は、間違いが高くつく箇所にだけ足します。