failpoint

Eine Implementierung von Failpoints für Golang. Failpoints werden verwendet, um Codepunkte einzufügen, an denen Fehler in einer benutzergesteuerten Weise injiziert werden können. Ein Failpoint ist ein Codeausschnitt, der nur ausgeführt wird, wenn der entsprechende Failpoint aktiv ist.

Schnellstart (mit failpoint-ctl)

1. Baue failpoint-ctl aus dem Quellcode

   root@kitploit:~

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

2. Injiziere Failpoints in dein Programm, z. B.:

   root@kitploit:~

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

3. Transformiere deinen Code mit failpoint-ctl enable

4. Baue mit go build

5. Aktiviere Failpoints mit der Umgebungsvariable GO_FAILPOINTS

   root@kitploit:~

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

   Hinweis: GO_FAILPOINTS funktioniert nicht mit Markern vom Typ InjectCall.

6. Wenn du go run zum Ausführen des Tests verwendest, vergiss nicht, die generierte Datei in deinen Befehl aufzunehmen, z. B.:

Schnellstart (mit failpoint-toolexec)

1. Baue failpoint-toolexec aus dem Quellcode

   root@kitploit:~

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

2. Injiziere Failpoints in dein Programm, z. B.:

   root@kitploit:~

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

3. Verwende einen separaten Build-Cache, um eine Vermischung mit Caches ohne failpoint-toolexec zu vermeiden, und baue:

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

4. Aktiviere Failpoints mit der Umgebungsvariable GO_FAILPOINTS

   root@kitploit:~

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

5. Du kannst auch go run oder go test verwenden, z. B.:

   root@kitploit:~

Designprinzipien

• Definiere Failpoints als gültigen Golang-Code, nicht als Kommentare oder etwas anderes

• Failpoints verursachen keine zusätzlichen Kosten

  • Sie haben keine Auswirkung auf die reguläre Logik
  • Sie verursachen keine Leistungsregression im regulären Code
  • Failpoint-Code erscheint nicht im finalen Binary

• Failpoint-Routinen sind schreib-/lesbar und sollten von einem Compiler geprüft werden

• Der durch die Failpoint-Definition erzeugte Code ist leicht lesbar

• Die Zeilennummern bleiben identisch mit den injizierten Codes (einfacheres Debugging)

• Unterstützung paralleler Tests mit context.Context

Kernkonzepte

• Failpoint

  Ein Failpoint ist ein Codeausschnitt, der nur ausgeführt wird, wenn der entsprechende Failpoint aktiv ist. Die Closure wird niemals ausgeführt, wenn failpoint.Disable("failpoint-name-for-demo") ausgeführt wird.

  root@kitploit:~

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

• Markerfunktionen

  • Sie sind nur leere Funktionen

    • Sie weisen den Rewriter an, mit einer Gleichheitsanweisung umzuschreiben
    • Sie empfangen einige Parameter als Umschreibungsregel
    • Sie werden zur Compile-Zeit inline eingefügt und geben nichts an das Binary aus (Nullkosten)
    • Die Variablen im äußeren Gültigkeitsbereich können in der Closure durch Capturing zugegriffen werden, und der konvertierte Code ist weiterhin gültig, da sich alle erfassten Variablen im äußeren Gültigkeitsbereich der IF-Anweisung befinden.

  • Sie sind leicht zu schreiben/lesen

  • Sie führen eine Compilerprüfung für Failpoints ein, die im regulären Modus nicht kompilieren können, wenn der Failpoint-Code ungültig ist

• Liste der Markerfunktionen

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

So injizierst du einen Failpoint in dein Programm

• Du kannst failpoint.Inject aufrufen, um einen Failpoint an der Aufrufstelle zu injizieren, wobei failpoint-name zum Auslösen des Failpoints verwendet wird und failpoint-closure als Rumpf der IF-Anweisung expandiert wird.

  root@kitploit:~

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

  Der konvertierte Code sieht wie folgt aus:

  root@kitploit:~

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

• failpoint.Value ist der Wert, der durch failpoint.Enable("failpoint-name", "return(5)") übergeben wird, und kann ignoriert werden.

  root@kitploit:~

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

  ODER

  root@kitploit:~

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

Einige komplizierte Failpoint-Demos

• Injiziere einen Failpoint in die IF-INITIAL-Anweisung oder den CONDITIONAL-Ausdruck

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

  Der obige Codeblock erzeugt etwas wie folgt:

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

• Injiziere einen Failpoint in die SELECT-Anweisung, um einen CASE zu blockieren, wenn der Failpoint aktiv ist

Best Practices für Failpoint-Namen

Wie oben zu sehen, umschließt _curpkg_ den ursprünglichen Failpoint-Namen im failpoint.Eval-Aufruf automatisch. Du kannst dir _curpkg_ wie ein Makro vorstellen, das dem Failpoint-Namen automatisch den aktuellen Paketpfad voranstellt. Zum Beispiel:

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

Du musst dich in deiner Anwendung nicht um _curpkg_ kümmern. Es wird nach dem Ausführen von failpoint-ctl enable automatisch erzeugt und mit failpoint-ctl disable wieder entfernt.

Da alle Failpoints in einem Paket denselben Namespace teilen, müssen wir vorsichtig sein, um Namenskonflikte zu vermeiden. Es gibt einige empfohlene Namensregeln, um diese Situation zu verbessern.

• Halte den Namen im aktuellen Unterpaket eindeutig

• Verwende einen selbsterklärenden Namen für den Failpoint

  Du kannst Failpoints über Umgebungsvariablen aktivieren

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

Implementierungsdetails

1. Definiere eine Gruppe von Markerfunktionen
2. Analysiere Imports und entferne Quelldateien, die keinen Failpoint importieren
3. Durchlaufe den AST, um Markerfunktionsaufrufe zu finden
4. Markerfunktionsaufrufe werden mit einer IF-Anweisung umgeschrieben, die failpoint.Eval aufruft, um zu bestimmen, ob ein Failpoint aktiv ist, und führt den Failpoint-Code aus, wenn der Failpoint aktiviert ist

Danksagungen

• Dank an gofail für die Bereitstellung der ursprünglichen Implementierung.