failpoint

Golang向けのfailpointsの実装です。フェイルポイントは、ユーザーが制御した方法でエラーを注入できるコードポイントを追加するために使用されます。フェイルポイントは、対応するフェイルポイントがアクティブな場合にのみ実行されるコードスニペットです。

クイックスタート (failpoint-ctl を使う)

1. ソースから failpoint-ctl をビルドする

   root@kitploit:~

   git clone https://github.com/pingcap/failpoint.git
   cd failpoint
   make
   ls bin/failpoint-ctl
   

2. フェイルポイントをプログラムに注入します。例:

   root@kitploit:~

   package main
   
   import "github.com/pingcap/failpoint"
   
   func main() {
       failpoint.Inject("testPanic", func() {
           panic("failpoint triggerd")
       })
   }
   

3. failpoint-ctl enable でコードを変換する

4. go build でビルドする

5. GO_FAILPOINTS 環境変数でフェイルポイントを有効にする

   root@kitploit:~

   GO_FAILPOINTS="main/testPanic=return(true)" ./your-program
   

   注: GO_FAILPOINTS は InjectCall タイプのマーカーでは機能しません。

6. go run でテストを実行する場合は、生成された binding__failpoint_binding__.go をコマンドに追加することを忘れないでください。例:

クイックスタート (failpoint-toolexec を使う)

1. ソースから failpoint-toolexec をビルドする

   root@kitploit:~

   git clone https://github.com/pingcap/failpoint.git
   cd failpoint
   make
   ls bin/failpoint-toolexec
   

2. フェイルポイントをプログラムに注入します。例:

   root@kitploit:~

   package main
   
   import "github.com/pingcap/failpoint"
   
   func main() {
       failpoint.Inject("testPanic", func() {
           panic("failpoint triggerd")
       })
   }
   

3. failpoint-toolexec なしのキャッシュが混ざらないように、別のビルドキャッシュを使用してビルドする

   GOCACHE=/tmp/failpoint-cache go build -toolexec path/to/failpoint-toolexec

4. GO_FAILPOINTS 環境変数でフェイルポイントを有効にする

   root@kitploit:~

   GO_FAILPOINTS="main/testPanic=return(true)" ./your-program
   

5. go run や go test を使うこともできます。例:

   root@kitploit:~

   GOCACHE=/tmp/failpoint-cache GO_FAILPOINTS="main/testPanic=return(true)" go run -toolexec path/to/failpoint-toolexec your-program.go
   

設計原則

• フェイルポイントをコメントやその他のものではなく、有効な Golang コードで定義する

• フェイルポイントに追加コストはない

  • 通常のロジックには影響しない
  • 通常のコードのパフォーマンスを低下させない
  • フェイルポイントコードは最終バイナリには含まれない

• フェイルポイントのルーチンは読み書き可能で、コンパイラでチェックされるべきである

• フェイルポイント定義によって生成されるコードは読みやすい

• 注入コードと同じ行番号を維持する（デバッグしやすい）

• context.Context による並列テストをサポートする

主要な概念

• フェイルポイント

  フェイルポイントは、対応するフェイルポイントがアクティブな場合にのみ実行されるコードスニペットです。 failpoint.Disable("failpoint-name-for-demo") が実行された場合、クロージャは決して実行されません。

  root@kitploit:~

  var outerVar = "declare in outer scope"
  failpoint.Inject("failpoint-name-for-demo", func(val failpoint.Value) {
      fmt.Println("unit-test", val, outerVar)
  })
  

• マーカー関数

  • それは単なる空の関数です

    • リライタに等価ステートメントで書き換えることを示すため
    • 書き換えルールとしていくつかのパラメータを受け取るため
    • コンパイル時にインライン化され、バイナリには何も出力されません（ゼロコスト）
    • 外部スコープの変数はキャプチャによってクロージャからアクセスでき、変換後のコードも有効です。キャプチャされた変数はすべて IF ステートメントの外側スコープに配置されるためです。

  • 書きやすく読みやすい

  • フェイルポイントコードが無効な場合、通常モードではコンパイルできないようにするコンパイラチェックを導入する

• マーカー関数リスト

  • func Inject(fpname string, fpblock func(val Value)) {}
  • func InjectContext(fpname string, ctx context.Context, fpblock func(val Value)) {}
  • func InjectCall(fpname string, args ...any) {}
  • func Break(label ...string) {}
  • func Goto(label string) {}
  • func Continue(label ...string) {}

プログラムにフェイルポイントを注入する方法

• failpoint.Inject を呼び出すことで、呼び出しサイトにフェイルポイントを注入できます。failpoint-name はフェイルポイントをトリガーするために使用され、failpoint-closure は IF ステートメントの本体として展開されます。

  root@kitploit:~

  failpoint.Inject("failpoint-name", func(val failpoint.Value) {
      failpoint.Return("unit-test", val)
  })
  

  変換後のコードは次のようになります:

  root@kitploit:~

  if val, _err_ := failpoint.Eval(_curpkg_("failpoint-name")); _err_ == nil {
      return "unit-test", val
  }
  

• failpoint.Value は、failpoint.Enable("failpoint-name", "return(5)") によって渡される値で、無視することができます。

  root@kitploit:~

  failpoint.Inject("failpoint-name", func(_ failpoint.Value) {
      fmt.Println("unit-test")
  })
  

  または

  root@kitploit:~

  failpoint.Inject("failpoint-name", func() {
      fmt.Println("unit-test")
  })
  

  変換後のコードは次のようになります:

  root@kitploit:~

  if _, _err_ := failpoint.Eval(_curpkg_("failpoint-name")); _err_ == nil {
      fmt.Println("unit-test")
  }
  

複雑なフェイルポイントのデモ

• IF 初期化ステートメントまたは条件式にフェイルポイントを注入する

  root@kitploit:~

  if a, b := func() {
      failpoint.Inject("failpoint-name", func(val failpoint.Value) {
          fmt.Println("unit-test", val)
      })
  }, func() int { return rand.Intn(200) }(); b > func() int {
      failpoint.Inject("failpoint-name", func(val failpoint.Value) int {
          return val.(int)
      })
      return rand.Intn(3000)
  }() && b < func() int {
      failpoint.Inject("failpoint-name-2", func(val failpoint.Value) {
          return rand.Intn(val.(int))
      })
      return rand.Intn(6000)
  }() {
      a()
      failpoint.Inject("failpoint-name-3", func(val failpoint.Value) {
          fmt.Println("unit-test", val)
      })
  }
  

  上記のコードブロックは次のようなコードを生成します:

  root@kitploit:~

  if a, b := func() {
      if val, _err_ := failpoint.Eval(_curpkg_("failpoint-name")); _err_ == nil {
          fmt.Println("unit-test", val)
      }
  }, func() int { return rand.Intn(200) }(); b > func() int {
      if val, _err_ := failpoint.Eval(_curpkg_("failpoint-name")); _err_ == nil {
          return val.(int)
      }
      return rand.Intn(3000)
  }() && b < func() int {
      if val, ok := failpoint.Eval(_curpkg_("failpoint-name-2")); ok {
          return rand.Intn(val.(int))
      }
      return rand.Intn(6000)
  }() {
      a()
      if val, ok := failpoint.Eval(_curpkg_("failpoint-name-3")); ok {
          fmt.Println("unit-test", val)
      }
  }
  

• SELECT ステートメントにフェイルポイントを注入して、フェイルポイントがアクティブな場合に1つの CASE をブロックする

  root@kitploit:~

フェイルポイント名のベストプラクティス

上記のように、_curpkg_ は failpoint.Eval 呼び出し内の元のフェイルポイント名を自動的にラップします。_curpkg_ は、現在のパッケージパスをフェイルポイント名の前に自動的に付加するマクロと考えることができます。例:

package ddl // which parent package is `github.com/pingcap/tidb`

func demo() {
	// _curpkg_("the-original-failpoint-name") will be expanded as `github.com/pingcap/tidb/ddl/the-original-failpoint-name`
	if val, ok := failpoint.Eval(_curpkg_("the-original-failpoint-name")); ok {...}
}

アプリケーション内で _curpkg_ を気にする必要はありません。failpoint-ctl enable を実行すると自動的に生成され、failpoint-ctl disable で削除されます。

パッケージ内のすべてのフェイルポイントは同じ名前空間を共有するため、名前の衝突を避けるように注意する必要があります。この状況を改善するための推奨命名規則がいくつかあります。

• 現在のサブパッケージ内で名前を一意にする

• フェイルポイントに自己説明的な名前を使用する

  環境変数でフェイルポイントを有効にできます

  root@kitploit:~

  GO_FAILPOINTS="github.com/pingcap/tidb/ddl/renameTableErr=return(100);github.com/pingcap/tidb/planner/core/illegalPushDown=return(true);github.com/pingcap/pd/server/schedulers/balanceLeaderFailed=return(true)"
  

実装の詳細

1. マーカー関数のグループを定義する
2. インポートを解析し、フェイルポイントをインポートしないソースファイルを削除する
3. AST を走査してマーカー関数呼び出しを見つける
4. マーカー関数呼び出しは、フェイルポイントがアクティブかどうかを判断するために failpoint.Eval を呼び出す IF ステートメントで書き換えられ、フェイルポイントが有効な場合にフェイルポイントコードを実行します

謝辞

• 初期実装を提供してくれた gofail に感謝します。