Outcome Contract

実例

レポート用テーブルへ流す日次の取り込み。契約はこうなります。

1. 1平日の 08:30 JST 以降に必ず実行される。
2. 2execution が成功で終わる。
3. 3出力が 1 件以上ある。
4. 45 分以内に終わる。
5. 5downstream probe が、対象テーブルが更新されたことを確認する。

期限に猶予を足した 08:45 JST に、OutcomeGuard が 5 つを評価します。実行され、成功し、112 件を運び、90 秒で終わり、probe が新しい行を確認できていれば正常です。実行されて 0 件だった場合は正常ではありません。n8n が何を記録していても同じです。

ルールの種類

must_run

契約の対象期間内に execution が開始されていること。

must_succeed

その execution が成功で終わっていること。

items_out_gte

最終 node が N 件以上を出していること。「空は疑わしい」を「空は失敗」に変えるルールです。

runtime_lt_ms

指定した時間内に終わること。遅いことが欠けることと同じくらい困る場合に使います。

last_node_is

指定した node で終わること。結果を書き込む node を指定すれば、1 つ手前で終わった実行を拾えます。

probe

OutcomeGuard が実行する外部チェック。連携先が実際に変わったことを確認します。engine は probe の結果を判定するだけで、結果を作り出しません。

期限、timezone、猶予

契約には cron 式と timezone で表した期限があり、猶予時間（既定 15 分）を持ちます。猶予を待ってから判定するため、2 分の遅れが incident になることはありません。

timezone は、サーバーの都合ではなく業務の時間に合わせてください。09:00 JST までに机の上にある必要があるレポートの期限は JST です。instance が UTC で動いているかどうかは実装の都合です。

downstream probe

probe は、検証の中で n8n の外を見る唯一の部分です。答える問いは 1 つだけ。連携先は実際に変わったか。実務上は鮮度の確認になります。最新の行、ファイルの更新時刻、レコードのフィールド。probe は合否とあわせて、観測した鮮度も報告します。

probe は設計上、読み取り専用です。変更を確認するために対象を読みますが、対象へ書き込むことはありません。

誤報で信用を失わない書き方

• 期限は、業務として本当に困る時刻にします。08:30 に予定していても、10:00 までに必要なら期限は 10:00 です。
• items_out_gte は、意味を持つ最小の数にします。多くの場合 1 が適切です。平均に近い数を入れると、閑散日に必ず鳴ります。
• runtime_lt_ms は余裕を持たせます。中央値ではなく、観測した p95 より上に置いてください。
• まず must_run と must_succeed から始めます。件数は 1 週間ほど数字を見てから、probe は誤りが高くつく箇所にだけ足します。