debugging-by-evidence

証拠に基づくデバッグ

基本原則。 インシデントに関する未知の点をすべて調べるのではなく、判断に必要な主張を検証します。

• 仮説は実験を選ぶためのものであり、原因が確定したことを意味しません。 報告、ログ、コードから、ローカルで再現する前に反証可能な仮説を立てられます。
• 相補的な証拠の層を活用します。 インシデント記録は事象の発生を示し、制御された実験は元の引き金を特定できなくても、不具合のある処理を明らかにできます。
• あなたは何かの作業の途中でこれを開きました。 これはその作業の進め方であり、作業に取って代わるものではありません。始める前に何をしていたのかを明確にし、終わったらその作業に戻りましょう。

問いに合ったシグナルを選ぶ

• 報告された失敗と、利用可能な証拠から始めます。 ローカルでテストが成功しても、記録されたインシデントが消えるわけではありません。
• それぞれが明らかにできることに応じて、再現、リプレイ、制御された障害注入、トレースを選びます。 これらは選択肢であり、必須の順序ではありません。
• テスト対象の処理は実際のままにします。 根拠のある依存先の結果やスケジュールを注入し、呼び出し元から見える契約をアサートします。
• コマンド、条件、結果を記録します。 注入した条件にはその旨を明記し、本番で観測された事象として報告しないでください。

何をいつ書き込めるか

• 裏付けのある修正を行う前に書き込みが許されるのは、許可された診断テストと計測に限られます。 入力、依存先の結果、スケジュールを制御して変更することは実験であり、本番環境の修正ではありません。
• ベースラインを維持します。 調査中の条件を変更し、正しさをテストしている処理は変更しないでください。置き換えは分離し、元の証拠を保持します。
• 許可の範囲はワークスペースの境界までです。 コミット、ブランチの移動、リモート操作、デプロイは行いません。一時的な計測は削除し、有用な回帰テストは残します。

最初の実行前に確認すること

• 環境に尋ねても答えは返ってきません。 3つの点でセットアップを確定できます。そのうち2つは、すでに環境内にあります。

  • ユーザー自身の言葉で書かれた症状を引用します。
  • その対象を実行するために、プロジェクトがすでに宣言しているコマンド。
  • 失敗が常時発生するのか、時折発生するのかという報告と、利用可能な条件や観測内容。

• 報告された発生率と、測定された発生率を区別します。 判断に役立つ場合にのみ頻度を測定し、調査を始める前に失敗を繰り返すよう求めるのではなく、不明な頻度は不明と明記します。

• 最初の調査の前に、予算をはっきり伝えます。 どこまで調べるつもりなのかを、調査回数または時間で示し、私に見えるところに記してください。中断できる範囲を定めた調査のほうが、終わってから報告される無制限の調査より価値があります。

• 次の調査はそれぞれ、判断に役立つものでなければなりません。 範囲内で残る疑問に次の実行で答えられない場合は、停止するか、接点を変えるか、引き継ぎます。

読むべきルール

1行につき1つのルールです。 左列の項目を、症状または現在の状態と照らし合わせてください。

• 該当項目によって、調査の開始地点が決まります。 次に何が正当化されるかは証拠によって判断します。各状態をすべて通ることが、すべての調査に求められるわけではありません。
• 判断が必要になった時点でルールを読みます。 停止と権限の制限は、どの状態にも適用されます。
• 2行がどちらも症状に該当しそうなら、両方を読んでください。 読み落としはループ全体のやり直しにつながります。読みすぎても、コストはファイル1つ分です。
• すべての行を読んでから、該当する項目に対応してください。取り消しにくいものから優先します。 行を読むコストはかかりません。読み飛ばした行に、見落とした情報があるものです。

次のような状況が見られる場合...	読むルール
ローカルで実行しても報告された障害を再現できない、またはループの実行が遅い、ノイズが多い、断続的、あるいは利用できない	rules/runnable-signal.md
失敗した実験に無関係なセットアップが含まれ、主張が不明瞭になっている	rules/minimising.md
説明がすでに明白に思える、または最初に思いついたことをすぐにテストしようとしている	rules/rival-hypotheses.md
依存関係、入力、スケジュールに対する観察と制御された変更のどちらを選ぶか判断している	rules/probing.md
障害が発生箇所から離れた場所に現れる、または依存関係の有効な結果に対して、呼び出し側が無効な動作をする	rules/fix-at-the-source.md
処理上の欠陥が実証され、元の発生要因が不明なままでも、それを防ぐテストが必要になっている	rules/regression-seam.md
試行が判断に役立たなくなった、回帰によって修正に疑問が生じた、または必要な観察ができない	rules/stopping-and-escalating.md

見分けるポイント。

• シグナルと最小化。 シグナルは、実行可能な観察または実験を選びます。最小化は、有用なシグナルが得られた後に、無関係なセットアップを取り除きます。
• 仮説とプロービング。 プローブの前に予測を明確にします。独立した問いは、異なるレイヤーで並行して進めてもかまいません。それぞれの証拠は分けて扱ってください。
• ソースとシーム。 ソースは、根拠のある修正をどこに適用すべきかを判断します。シームは、テストでどのコントラクトを保護するかを判断します。

基本方針。

• 何が証明できるかを問わず最も安価なチェックではなく、必要十分な中で最も低コストの証拠を使います。
• 独立した作業は適切な範囲にとどめます。 ソースコードの分析、処理に関するテスト、環境の観察は、必要な入力がそろっていれば、互いを待つ必要はありません。重複する実験上の編集は混在させないでください。
• テストした範囲を超えて断定しないでください。 条件付きの処理上の欠陥は、過去のインシデントの発生要因を特定しなくても、範囲を限定した修正の根拠になります。

証拠が許す範囲を述べる

状態が変わったら、確立された主張と残るギャップを示してください。

状態	意味	可能になること
debug/NO-SIGNAL	障害の報告はあるが、まだ実行可能なチェックがない	記録とコードを調べ、仮説を立て、制御された実験を組み立てる
debug/RED	記録された条件下で、実行結果が関連するコントラクトに違反している	説明を比較し、メカニズムを検証する。観察された条件と注入された条件を区別して明記する
debug/MINIMISED	有用な失敗チェックから、無関係なセットアップが取り除かれている	縮小実験を任意で行う。すべての修正に必須ではない
debug/EXPLAINED	証拠によって、メカニズムと修正の適用範囲が裏付けられている	承認された修正を適用する。観察されていないインシデントの発生要因は、明示したままにする
debug/RESOLVED	実証された欠陥が修正され、影響を受けるコントラクトが検証されている	テストした範囲に限ってその欠陥を解決済みとする。特定されていない限り、過去の発生要因を特定したとは主張しない

• それ自体を目的に最小化しないでください。 実験の内容が理解でき、判断に十分になった時点で、縮小を止めます。
• ギャップが妨げるのは、そのギャップに依存する主張と行動だけです。 有用であれば、別の独立したレイヤーを調査してください。同じ観察が得られない状態を追い続けないでください。
• 実行が成功しても、対象範囲は限定的です。 イベントが観察されなかったことは、断続的なイベントが発生し得ないことの証明ではありません。

結論を証拠に合わせる

• 発生： 信頼できるインシデント記録または再現によって、その条件下で障害が発生したことが示されています。
• 処理： 管理されたテストによって、指定された条件に実際のコードがどのように反応するかが示されています。依存関係の結果は、その契約と整合している必要があります。作り上げた動作は再現ではありません。
• 過去の原因： 元のインシデントの引き金を特定するには、その引き金の証拠が必要であり、単にそれを強制するテストだけでは不十分です。
• 修正： 不具合のある依存関係または分岐を取り除くには、契約チェックの失敗と互換性チェックが必要です。引き金の発生率の推定は必須ではありません。
• 調整： 再試行、バックオフ、またはタイムアウトの変更には、復旧、タイミング、負荷、副作用に関連する証拠が必要です。エラーを強制しただけでは、選んだ値の正当化にはなりません。

因果関係に関する各主張について、コードまたは観測された事象、識別に役立つ結果、未解明の点を示してください。正当化される修正が変わらないのであれば、もっともらしい別の説明を排除する必要はありません。その境界を記録してください。

再試行するのではなく、調査を止めるとき

• 次の実行で何が変わる可能性があるかを明確にする。 繰り返すことで、明示された条件下での変動を推定できる場合はありますが、それが原因究明の進展に直結するとは限りません。
• 新たなリグレッションは修正への反証として扱う。 アーキテクチャが間違っていることの自動的な証明として扱ってはいけません。
• 対象範囲の判断が裏付けられたとき、不可欠な観測ができないとき、調査の上限に達したとき、または次の手順に新たな権限が必要なときは止める。 未解決の疑問を報告しつつ、別の裏付けられた作業を妨げないでください。

出力の要件

Symptom      as reported, with the available incident evidence
State        the established claim and the next justified action
Experiments  conditions, real code exercised, observed or injected inputs, results
Mechanism    supported causal links at file:line, including conditional claims
Not shown    historical trigger, frequency or compatibility still unverified
Fix          the scoped change and affected callers/contracts
Proof        the failing contract check before and after, relevant adjacent checks,
             and removal of temporary instrumentation

• 避けたことではなく、観測したことを報告する。
• 「修正しました」から始めない。 読者には、まず因果関係の連なりを示す必要があります。原因を示す前に修正を述べると、たまたまうまくいった推測のように受け取られます。そして実際に推測であることもあります。

これに該当する場合は省略しない

• 原因が明白に思えるとき。 このスキルは、その思い込みを崩すためにあります。
• 誰かがすでに障害を報告しているとき。 その人の証拠を使い、推論する前に新たなローカル発生を要求してはいけません。
• 修正が1行のとき。 間違った行を1行だけ修正しても、やはり間違いです。
• 急いでいるとき。 推測こそが、2回目、3回目の試行を生みます。

振り分け

• 上の表で、適用するルールとその順序を選ぶ。 選んだルールを最後まで読み、自分で解釈し、どのルールを開いたかを1行で伝えてください。
• 競合する説明は並行して検証してもかまいません。 それらの順位付けと結果の判断を他者に委ねてはいけません。
• ユーザーからの直接の指示は、ここにある内容より優先されます。
• 修正ができた時点で、それはもはや症状ではなく変更です。 ここで判断するのではなく、差分のレビューに回してください。