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

   root@kitploit:~

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

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

   root@kitploit:~

   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

   root@kitploit:~

   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é à votre commande, par exemple :

Démarrage rapide (utilisation de failpoint-toolexec)

1. Compilez failpoint-toolexec à partir des sources

   root@kitploit:~

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

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

   root@kitploit:~

   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

   root@kitploit:~

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

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

   root@kitploit:~

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é.

  root@kitploit:~

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

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.

  root@kitploit:~

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

  Le code converti ressemble à :

  root@kitploit:~

  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.

  root@kitploit:~

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

  OU

  root@kitploit:~

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

  Et le code converti ressemble à :

Quelques exemples de failpoints complexes

• Injection d'un failpoint dans l'instruction IF INITIALE ou l'expression CONDITIONNELLE

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

  Le bloc de code ci-dessus générera quelque chose comme ceci :

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

• Injection d'un failpoint dans l'instruction SELECT pour qu'elle bloque un CASE si le failpoint est actif

Bonnes pratiques pour les noms de failpoints

Comme vous le voyez ci-dessus, _curpkg_ enveloppe automatiquement le nom original du failpoint dans un appel failpoint.Eval. Vous pouvez considérer _curpkg_ comme une macro qui préfixe automatiquement le chemin du package courant au nom du failpoint. Par exemple,

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 {...}
}

Vous n'avez pas besoin de vous soucier de _curpkg_ dans votre application. Il est généré automatiquement après avoir exécuté failpoint-ctl enable et supprimé avec failpoint-ctl disable.

Comme tous les failpoints d'un package partagent le même espace de noms, nous devons faire attention à éviter les conflits de noms. Voici quelques règles de nommage recommandées pour améliorer cette situation.

• Gardez un nom unique dans le sous-package actuel

• Utilisez un nom explicite pour le failpoint

  Vous pouvez activer les failpoints grâce aux variables d'environnement

  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)"
  

Détails de l'implémentation

1. Définir un groupe de fonctions de marqueur
2. Analyser les imports et supprimer les fichiers sources qui n'importent pas de failpoint
3. Parcourir l'AST pour trouver les appels aux fonctions de marqueur
4. Les appels aux fonctions de marqueur seront réécrits avec une instruction IF, qui appelle failpoint.Eval pour déterminer si un failpoint est actif et exécute le code du failpoint si le failpoint est activé

Remerciements

• Merci à gofail pour l'implémentation initiale.