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 语句，以便在故障点激活时阻塞某个 CASE

  root@kitploit:~

  func (s *StoreService) ExecuteStoreTask() {
      select {
      case <-func() chan *StoreTask {
          failpoint.Inject("priority-fp", func(_ failpoint.Value) {
              return make(chan *StoreTask)
          })
          return s.priorityHighCh
      }():
          fmt.Println("execute high priority task")
  
      case <- s.priorityNormalCh:
          fmt.Println("execute normal priority task")
  
      case <- s.priorityLowCh:
          fmt.Println("execute normal low task")
      }
  }
  

故障点命名最佳实践

如上所示，_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. 标记函数调用将被重写为 IF 语句，该语句调用 failpoint.Eval 来判断故障点是否激活，并在故障点启用时执行故障点代码

致谢

• 感谢 gofail 提供了最初的实现。