failpoint

Uma implementação de failpoints para Golang. Fail points são usados para adicionar pontos de código onde erros podem ser injetados de forma controlada pelo usuário. Um fail point é um trecho de código que só é executado quando o failpoint correspondente está ativo.

Início rápido (usando failpoint-ctl)

1. Compile failpoint-ctl a partir do código-fonte

   root@kitploit:~

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

2. Injete failpoints no seu programa, por exemplo:

   root@kitploit:~

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

3. Transforme o seu código com failpoint-ctl enable

4. Compile com go build

5. Ative failpoints com a variável de ambiente GO_FAILPOINTS

   root@kitploit:~

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

   Nota: GO_FAILPOINTS não funciona com marcadores do tipo InjectCall.

6. Se você usar go run para executar o teste, não se esqueça de adicionar o gerado ao seu comando, por exemplo:

Início rápido (usando failpoint-toolexec)

1. Compile failpoint-toolexec a partir do código-fonte

   root@kitploit:~

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

2. Injete failpoints no seu programa, por exemplo:

   root@kitploit:~

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

3. Use um cache de build separado para evitar misturar caches sem o failpoint-toolexec e compile

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

4. Ative failpoints com a variável de ambiente GO_FAILPOINTS

   root@kitploit:~

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

5. Você também pode usar go run ou go test, por exemplo:

   root@kitploit:~

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

Princípios de design

• Defina failpoint em código Golang válido, não em comentários ou qualquer outra coisa

• Failpoint não tem nenhum custo extra

  • Não terá efeito na lógica regular
  • Não causará regressão de desempenho no código normal
  • O código do failpoint não aparecerá no binário final

• A rotina do failpoint é escrevível/legível e deve ser verificada por um compilador

• O código gerado pela definição de failpoint é fácil de ler

• Mantenha os números de linha iguais aos dos códigos de injeção (mais fácil de depurar)

• Suporte a testes paralelos com context.Context

Conceitos-chave

• Failpoint

  Um failpoint é um trecho de código que só é executado quando o failpoint correspondente está ativo. A closure nunca será executada se failpoint.Disable("failpoint-name-for-demo") for executado.

  root@kitploit:~

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

• Funções de marcador

  • É apenas uma função vazia

    • Para indicar ao reescritor que reescreva com uma instrução de igualdade
    • Para receber alguns parâmetros como regra de reescrita
    • Será embutida (inline) em tempo de compilação e não emitirá nada para o binário (custo zero)
    • As variáveis do escopo externo podem ser acessadas na closure por captura, e o código convertido continua válido porque todas as variáveis capturadas estão localizadas no escopo externo da instrução IF.

  • É fácil de escrever/ler

  • Introduz uma verificação do compilador para failpoints que não podem compilar no modo normal se o código do failpoint for inválido

• Lista de funções de marcador

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

Como injetar um failpoint no seu programa

• Você pode chamar failpoint.Inject para injetar um failpoint no local da chamada, onde failpoint-name é usado para acionar o failpoint e failpoint-closure será expandido como o corpo da instrução IF.

  root@kitploit:~

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

  O código convertido fica assim:

  root@kitploit:~

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

• failpoint.Value é o valor passado por failpoint.Enable("failpoint-name", "return(5)"), que pode ser ignorado.

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

  E o código convertido fica assim:

  root@kitploit:~

Alguns exemplos de failpoints complicados

• Injete um failpoint na instrução IF INITIAL ou na expressão CONDITIONAL

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

  O bloco de código acima gerará algo assim:

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

• Injete um failpoint na instrução SELECT para fazer com que ela bloqueie um CASE se o failpoint estiver ativo

Melhores práticas para nomes de failpoint

Como você viu acima, _curpkg_ envolverá automaticamente o nome original do failpoint na chamada failpoint.Eval. Você pode pensar em _curpkg_ como um macro que automaticamente prefixa o caminho do pacote atual ao nome do failpoint. Por exemplo,

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

Você não precisa se preocupar com _curpkg_ na sua aplicação. Ele é gerado automaticamente após executar failpoint-ctl enable e é removido com failpoint-ctl disable.

Como todos os failpoints em um pacote compartilham o mesmo namespace, precisamos ter cuidado para evitar conflitos de nomes. Existem algumas regras de nomenclatura recomendadas para melhorar essa situação.

• Mantenha o nome único no subpacote atual

• Use um nome autoexplicativo para o failpoint

  Você pode ativar failpoints por variáveis de ambiente

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

Detalhes de implementação

1. Defina um grupo de funções de marcador
2. Analise as importações e elimine um arquivo-fonte que não importe um failpoint
3. Percorra a AST para encontrar chamadas de funções de marcador
4. As chamadas de funções de marcador serão reescritas com uma instrução IF, que chama failpoint.Eval para determinar se um failpoint está ativo e executa o código do failpoint se ele estiver ativado

Agradecimentos

• Agradecemos ao gofail por fornecer a implementação inicial.