failpoint

Una implementación de failpoints para Golang. Los failpoints se utilizan para añadir puntos de código donde se pueden inyectar errores de forma controlada por el usuario. Un failpoint es un fragmento de código que solo se ejecuta cuando el failpoint correspondiente está activo.

Inicio rápido (usando failpoint-ctl)

1. Compila failpoint-ctl desde el código fuente

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

2. Inyecta failpoints en tu programa, por ejemplo:

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

3. Transforma tu código con failpoint-ctl enable

4. Compila con go build

5. Activa los failpoints con la variable de entorno GO_FAILPOINTS

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

   Nota: GO_FAILPOINTS no funciona con el tipo de marcador InjectCall.

6. Si usas go run para ejecutar el test, no olvides añadir el archivo generado binding__failpoint_binding__.go a tu comando, así:

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

Inicio rápido (usando failpoint-toolexec)

1. Compila failpoint-toolexec desde el código fuente

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

2. Inyecta failpoints en tu programa, por ejemplo:

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

3. Usa un caché de compilación separado para evitar mezclar cachés sin failpoint-toolexec, y compila

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

4. Activa los failpoints con la variable de entorno GO_FAILPOINTS

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

5. También puedes usar go run o go test, por ejemplo:

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

Principios de diseño

• Define el failpoint en código Golang válido, no en comentarios ni en nada más

• El failpoint no tiene ningún costo adicional

  • No afecta a la lógica normal
  • No causa regresiones de rendimiento en el código normal
  • El código del failpoint no aparecerá en el binario final

• La rutina del failpoint es escribible/legible y debe ser verificada por un compilador

• El código generado por la definición del failpoint es fácil de leer

• Mantiene los mismos números de línea que los códigos de inyección (más fácil de depurar)

• Soporta pruebas paralelas con context.Context

Conceptos clave

• Failpoint

  Un failpoint es un fragmento de código que solo se ejecuta cuando el failpoint correspondiente está activo. El cierre nunca se ejecutará si se ejecuta 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)
  })
  

• Funciones marcadoras

  • Son solo funciones vacías

    • Para indicar al reescritor que reescriba con una sentencia de igualdad
    • Para recibir algunos parámetros como regla de reescritura
    • Se alinearán en tiempo de compilación y no emitirán nada al binario (costo cero)
    • Las variables del ámbito externo pueden ser accedidas en el cierre mediante captura, y el código convertido sigue siendo legal porque todas las variables capturadas están ubicadas en el ámbito externo de la sentencia IF.

  • Son fáciles de escribir/leer

  • Introducen una verificación del compilador para los failpoints que no se pueden compilar en el modo normal si el código del failpoint es inválido

• Lista de funciones marcadoras

  • 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) {}

• Variables de entorno de failpoint soportadas

  Los failpoints se pueden habilitar exportando variables de entorno con el siguiente patrón, que es bastante similar a las VARIABLES SYSCTL de failpoints en FreeBSD

  Nota: InjectCall no se puede habilitar mediante variables de entorno.

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

  El argumento especifica qué acción tomar; puede ser uno de:

  • off: No realizar ninguna acción (no dispara el código del failpoint)
  • return: Disparar el failpoint con el argumento especificado
  • sleep: Dormir el número de milisegundos especificado
  • panic: Pánico
  • break: Ejecutar gdb y entrar en el depurador
  • print: Imprimir la ruta del failpoint para inyectar la variable
  • pause: Pause pausará hasta que el failpoint se desactive

Cómo inyectar un failpoint en tu programa

• Puedes llamar a failpoint.Inject para inyectar un failpoint en el punto de llamada, donde failpoint-name se usa para disparar el failpoint y failpoint-closure se expandirá como el cuerpo de la sentencia IF.

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

  El código convertido se ve así:

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

• failpoint.Value es el valor que se pasa mediante failpoint.Enable("failpoint-name", "return(5)"), el cual se puede ignorar.

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

  O

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

  Y el código convertido se ve así:

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

• Además, el cierre del failpoint puede ser una función que reciba context.Context. Puedes hacer cosas personalizadas con context.Context, como controlar si un failpoint está activo en pruebas paralelas u otros casos. Por ejemplo:

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

  El código convertido se ve así: