failpoint

Une implémentation des failpoints pour Golang. Les failpoints sont utilisés pour ajouter des points de code où des erreurs peuvent être injectées de manière contrôlée par l'utilisateur. Un failpoint est un extrait de code qui n'est exécuté que lorsque le failpoint correspondant est actif.

Démarrage rapide (utilisation de failpoint-ctl)

1. Compilez failpoint-ctl à partir des sources

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

2. Injectez des failpoints dans votre programme, par exemple :

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

3. Transformez votre code avec failpoint-ctl enable

4. Compilez avec go build

5. Activez les failpoints avec la variable d'environnement GO_FAILPOINTS

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

   Remarque : GO_FAILPOINTS ne fonctionne pas avec le type de marqueur InjectCall.

6. Si vous utilisez go run pour exécuter le test, n'oubliez pas d'ajouter le fichier généré binding__failpoint_binding__.go à votre commande, par exemple :

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

Démarrage rapide (utilisation de failpoint-toolexec)

1. Compilez failpoint-toolexec à partir des sources

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

2. Injectez des failpoints dans votre programme, par exemple :

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

3. Utilisez un cache de build séparé pour éviter de mélanger les caches sans failpoint-toolexec, et compilez

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

4. Activez les failpoints avec la variable d'environnement GO_FAILPOINTS

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

5. Vous pouvez aussi utiliser go run ou go test, par exemple :

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

Principes de conception

• Définir le failpoint dans du code Golang valide, pas dans des commentaires ou autre chose

• Un failpoint n'a aucun coût supplémentaire

  • N'affectera pas la logique normale
  • Ne provoquera pas de régression de performance du code normal
  • Le code du failpoint n'apparaîtra pas dans le binaire final

• Le code du failpoint est lisible/modifiable et doit être vérifié par un compilateur

• Le code généré par la définition d'un failpoint est facile à lire

• Conserve les numéros de ligne identiques aux codes d'injection (plus facile à déboguer)

• Prend en charge les tests parallèles avec context.Context

Concepts clés

• Failpoint

  Un failpoint est un extrait de code qui n'est exécuté que lorsque le failpoint correspondant est actif. La fermeture ne sera jamais exécutée si failpoint.Disable("failpoint-name-for-demo") est exécuté.

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

• Fonctions de marqueur

  • Ce n'est qu'une fonction vide

    • Pour indiquer au réécrivain de réécrire avec une instruction d'égalité
    • Pour recevoir certains paramètres comme règle de réécriture
    • Elle sera inlinée au moment de la compilation et n'émettra rien dans le binaire (coût nul)
    • Les variables de la portée externe peuvent être accédées dans la fermeture par capture, et le code converti reste valide car toutes les variables capturées se trouvent dans la portée externe de l'instruction IF.

  • C'est facile à écrire/lire

  • Introduit une vérification par le compilateur pour les failpoints qui ne peuvent pas compiler en mode normal si le code du failpoint est invalide

• Liste des fonctions de marqueur

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

• Variable d'environnement de failpoint prise en charge

  Un failpoint peut être activé en exportant des variables d'environnement selon le modèle suivant, ce qui ressemble beaucoup aux variables SYSCTL du failpoint FreeBSD

  Remarque : InjectCall ne peut pas être activé par des variables d'environnement.

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

  L'argument spécifie l'action à effectuer ; il peut être l'un des suivants :

  • off : n'effectue aucune action (ne déclenche pas le code du failpoint)
  • return : déclenche le failpoint avec l'argument spécifié
  • sleep : dort pendant le nombre de millisecondes spécifié
  • panic : provoque une panique
  • break : exécute gdb et s'arrête dans le débogueur
  • print : affiche le chemin du failpoint pour la variable d'injection
  • pause : suspend l'exécution jusqu'à ce que le failpoint soit désactivé

Comment injecter un failpoint dans votre programme

• Vous pouvez appeler failpoint.Inject pour injecter un failpoint au site d'appel, où failpoint-name est utilisé pour déclencher le failpoint et failpoint-closure sera développé comme corps de l'instruction IF.

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

  Le code converti ressemble à :

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

• failpoint.Value est la valeur transmise par failpoint.Enable("failpoint-name", "return(5)"), qui peut être ignorée.

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

  OU

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

  Et le code converti ressemble à :

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