failpoint

Реализация failpoints для Golang. Fail points используются для добавления точек в коде, где ошибки могут быть внедрены под управлением пользователя. Fail point — это фрагмент кода, который выполняется только тогда, когда соответствующий failpoint активен.

Быстрый старт (использование failpoint-ctl)

1. Соберите failpoint-ctl из исходников

   root@kitploit:~

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

2. Внедрите failpoints в вашу программу, например:

   root@kitploit:~

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

3. Преобразуйте ваш код с помощью failpoint-ctl enable

4. Соберите с помощью go build

5. Включите failpoints с помощью переменной окружения GO_FAILPOINTS

   root@kitploit:~

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

   Примечание: GO_FAILPOINTS не работает с маркером типа InjectCall.

6. Если вы используете go run для запуска теста, не забудьте добавить сгенерированный в вашу команду, например:

Быстрый старт (использование failpoint-toolexec)

1. Соберите failpoint-toolexec из исходников

   root@kitploit:~

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

2. Внедрите failpoints в вашу программу, например:

   root@kitploit:~

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

3. Используйте отдельный кэш сборки, чтобы избежать смешивания кэшей без failpoint-toolexec, и выполните сборку

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

4. Включите failpoints с помощью переменной окружения GO_FAILPOINTS

   root@kitploit:~

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

5. Вы также можете использовать go run или go test, например:

   root@kitploit:~

Принципы проектирования

• Определяйте failpoint в валидном коде Golang, а не в комментариях или где-либо ещё

• Failpoint не имеет дополнительных затрат

  • Не влияет на обычную логику
  • Не вызывает регресса производительности обычного кода
  • Код failpoint не появится в итоговом бинарном файле

• Код failpoint можно писать и читать, и он должен проверяться компилятором

• Сгенерированный код по определению failpoint легко читается

• Сохраняйте номера строк такими же, как у кода с внедрением (легче отлаживать)

• Поддержка параллельных тестов с context.Context

Ключевые концепции

• Failpoint

  Failpoint — это фрагмент кода, который выполняется только тогда, когда соответствующий failpoint активен. Замыкание никогда не будет выполнено, если выполняется failpoint.Disable("failpoint-name-for-demo").

  root@kitploit:~

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

• Функции-маркеры

  • Это просто пустая функция

    • Чтобы подсказать переписчику заменить её на сравнение на равенство
    • Чтобы получать некоторые параметры в качестве правила переписывания
    • Она будет встроена во время компиляции и не попадёт в бинарный файл (нулевая стоимость)
    • Переменные из внешней области видимости могут быть доступны в замыкании через захват, и преобразованный код остаётся корректным, поскольку все захваченные переменные находятся во внешней области видимости оператора IF.

  • Её легко писать и читать

  • Добавляет проверку компилятором для failpoints: код не скомпилируется в обычном режиме, если код failpoint невалиден

• Список функций-маркеров

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

Как внедрить failpoint в вашу программу

• Вы можете вызвать failpoint.Inject, чтобы внедрить failpoint в место вызова, где failpoint-name используется для запуска failpoint, а failpoint-closure будет развёрнут как тело оператора IF.

  root@kitploit:~

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

  Преобразованный код выглядит так:

  root@kitploit:~

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

• failpoint.Value — это значение, которое передаётся через failpoint.Enable("failpoint-name", "return(5)"); его можно игнорировать.

  root@kitploit:~

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

  ИЛИ

  root@kitploit:~

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

  Преобразованный код выглядит так:

Некоторые сложные примеры failpoints

• Внедрение failpoint в оператор инициализации IF или условное выражение

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

  Приведённый выше блок кода сгенерирует что-то вроде этого:

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

• Внедрение failpoint в оператор SELECT, чтобы он блокировал один из CASE, если failpoint активен

Рекомендации по именованию failpoint

Как вы видите выше, _curpkg_ автоматически оборачивает исходное имя failpoint в вызов failpoint.Eval. Можно думать о _curpkg_ как о макросе, который автоматически добавляет путь текущего пакета к имени failpoint. Например,

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

Вам не нужно заботиться о _curpkg_ в вашем приложении. Он автоматически генерируется после запуска failpoint-ctl enable и удаляется с помощью failpoint-ctl disable.

Поскольку все failpoints в пакете используют одно и то же пространство имён, нужно быть внимательными, чтобы избежать конфликтов имён. Существуют некоторые рекомендуемые правила именования, улучшающие эту ситуацию.

• Сохраняйте имя уникальным в текущем подпакете

• Используйте самодокументируемое имя для failpoint

  Вы можете включить failpoints с помощью переменных окружения

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

Детали реализации

1. Определите группу функций-маркеров
2. Разберите импорты и отбросьте исходные файлы, которые не импортируют failpoint
3. Обойдите AST, чтобы найти вызовы функций-маркеров
4. Вызовы функций-маркеров будут переписаны с помощью оператора IF, который вызывает failpoint.Eval, чтобы определить, активен ли failpoint, и выполняет код failpoint, если он включён

Благодарности

• Благодарим gofail за предоставленную первоначальную реализацию.