failpoint

Golang 的 failpoints 实现。故障点用于以用户可控的方式在代码中添加可注入错误的位置。故障点是一段代码片段，仅当对应的故障点处于激活状态时才会执行。

快速开始（使用 failpoint-ctl）

1. 从源码构建 failpoint-ctl

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

2. 向你的程序注入故障点，例如：

   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 环境变量启用故障点

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

   注意：GO_FAILPOINTS 不适用于 InjectCall 类型的标记。

6. 如果你使用 go run 运行测试，别忘了在命令中加入生成的 binding__failpoint_binding__.go，例如：

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

快速开始（使用 failpoint-toolexec）

1. 从源码构建 failpoint-toolexec

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

2. 向你的程序注入故障点，例如：

   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 环境变量启用故障点

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

5. 你也可以使用 go run 或 go test，例如：

   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")，该闭包将永远不会执行。

  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) {}
  • func Fallthrough() {}
  • func Return(results ...interface{}) {}
  • func Label(label string) {}

• 支持的故障点环境变量

  可以通过导出符合以下模式的环境变量来启用故障点，这与 freebsd failpoint SYSCTL VARIABLES 非常相似

  注意：InjectCall 不能通过环境变量启用。

  [<percent>%][<count>*]<type>[(args...)][-><more terms>]
  

  参数指定要执行的操作；可以是以下之一：

  • off：不采取任何操作（不触发故障点代码）
  • return：使用指定参数触发故障点
  • sleep：休眠指定的毫秒数
  • panic：触发 panic
  • break：执行 gdb 并进入调试器中断
  • print：打印注入变量的故障点路径
  • pause：暂停，直到故障点被禁用

如何向你的程序注入故障点

• 你可以在调用点调用 failpoint.Inject 来注入故障点，其中 failpoint-name 用于触发故障点，failpoint-closure 会被展开为 IF 语句的函数体。

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

  转换后的代码如下所示：

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

• failpoint.Value 是通过 failpoint.Enable("failpoint-name", "return(5)") 传入的值，该值可以被忽略。

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

  或者

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

  转换后的代码如下所示：

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

• 此外，故障点闭包可以是一个接收 context.Context 的函数。你可以利用 context.Context 做一些自定义操作，例如在并行测试或其他场景中控制故障点是否激活。例如：

  failpoint.InjectContext(ctx, "failpoint-name", func(val failpoint.Value) {
      fmt.Println("unit-test", val)
  })
  

  转换后的代码如下所示：

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

• 你可以忽略 context.Context，这将生成与上面非 context 版本相同的代码。例如：

  failpoint.InjectContext(nil, "failpoint-name", func(val failpoint.Value) {
      fmt.Println("unit-test", val)
  })
  

  转换为：

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

• 你可以使用 failpoint.InjectCall 注入一个函数调用，这种类型的标记只能通过 failpoint.EnableCall 启用，并且必须在与 InjectCall 调用点相同的进程中调用。使用这种标记，你可以避免故障点代码污染你的源代码。参见 示例。

• 你可以通过 failpoint.WithHook 控制故障点

  func (s *dmlSuite) TestCRUDParallel() {
      sctx := failpoint.WithHook(context.Backgroud(), func(ctx context.Context, fpname string) bool {
          return ctx.Value(fpname) != nil // Determine by ctx key
      })
      insertFailpoints = map[string]struct{} {
          "insert-record-fp": {},
          "insert-index-fp": {},
          "on-duplicate-fp": {},
      }
      ictx := failpoint.WithHook(context.Backgroud(), func(ctx context.Context, fpname string) bool {
          _, found := insertFailpoints[fpname] // Only enables some failpoints.
          return found
      })
      deleteFailpoints = map[string]struct{} {
          "tikv-is-busy-fp": {},
          "fetch-tso-timeout": {},
      }
      dctx := failpoint.WithHook(context.Backgroud(), func(ctx context.Context, fpname string) bool {
          _, found := deleteFailpoints[fpname] // Only disables failpoints. 
          return !found
      })
      // other DML parallel test cases.
      s.RunParallel(buildSelectTests(sctx))
      s.RunParallel(buildInsertTests(ictx))
      s.RunParallel(buildDeleteTests(dctx))
  }
  

• 如果你在循环上下文中使用故障点，你可能会用到其他标记函数。