failpoint

Golang용 failpoints 구현입니다. Fail point는 사용자가 제어하는 방식으로 오류를 주입할 수 있는 코드 지점을 추가하는 데 사용됩니다. Fail point는 해당 failpoint가 활성화된 경우에만 실행되는 코드 스니펫입니다.

빠른 시작 (failpoint-ctl 사용)

1. 소스에서 failpoint-ctl 빌드

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

2. 프로그램에 failpoint를 주입하세요, 예:

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

3. failpoint-ctl enable로 코드를 변환하세요

4. go build로 빌드하세요

5. GO_FAILPOINTS 환경 변수로 failpoint를 활성화하세요

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

   참고: GO_FAILPOINTS는 InjectCall 유형의 마커에서는 동작하지 않습니다.

6. 테스트 실행에 go run을 사용하는 경우, 생성된 binding__failpoint_binding__.go를 명령에 포함하는 것을 잊지 마세요. 예:

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

빠른 시작 (failpoint-toolexec 사용)

1. 소스에서 failpoint-toolexec 빌드

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

2. 프로그램에 failpoint를 주입하세요, 예:

   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. GO_FAILPOINTS 환경 변수로 failpoint를 활성화하세요

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

5. go run이나 go test를 사용할 수도 있습니다. 예:

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

설계 원칙

• 유효한 Golang 코드로 failpoint를 정의하세요. 주석이나 다른 것이 아니라.

• Failpoint는 추가 비용이 없습니다

  • 일반 로직에는 영향을 주지 않습니다
  • 일반 코드 성능 저하를 일으키지 않습니다
  • Failpoint 코드는 최종 바이너리에 나타나지 않습니다

• Failpoint 루틴은 쓰기/읽기가 가능하며 컴파일러가 검사해야 합니다

• Failpoint 정의로 생성된 코드는 읽기 쉽습니다

• 주입 코드와 줄 번호를 동일하게 유지합니다(디버깅이 더 쉬움)

• context.Context를 사용한 병렬 테스트를 지원합니다

핵심 개념

• Failpoint

  Failpoint는 해당 failpoint가 활성화된 경우에만 실행되는 코드 스니펫입니다. failpoint.Disable("failpoint-name-for-demo")가 실행되면 클로저는 절대 실행되지 않습니다.

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

• 마커 함수

  • 그것은 단지 빈 함수입니다

    • 재작성자가 동등 비교(equality statement)로 재작성하도록 힌트를 줍니다
    • 재작성 규칙으로 사용할 일부 매개변수를 받습니다
    • 컴파일 타임에 인라인되며 바이너리로 아무것도 내보내지 않습니다(제로 비용)
    • 외부 범위의 변수는 캡처를 통해 클로저에서 접근할 수 있으며, 변환된 코드는 여전히 유효합니다. 모든 캡처된 변수가 IF 문의 외부 범위에 있기 때문입니다.

  • 쓰기/읽기가 쉽습니다

  • failpoint에 대한 컴파일러 검사를 도입합니다. 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) {}
  • func Goto(label string) {}
  • func Continue(label ...string) {}
  • func Fallthrough() {}
  • func Return(results ...interface{}) {}
  • func Label(label string) {}

• 지원되는 failpoint 환경 변수

  failpoint는 다음 패턴의 환경 변수를 export하여 활성화할 수 있습니다. 이는 freebsd failpoint SYSCTL VARIABLES와 매우 유사합니다.

  참고: InjectCall은 환경 변수로 활성화할 수 없습니다.

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

  <type> 인자는 수행할 동작을 지정하며, 다음 중 하나일 수 있습니다:

  • off: 아무 작업도 수행하지 않음 (failpoint 코드를 트리거하지 않음)
  • return: 지정된 인자로 failpoint 트리거
  • sleep: 지정된 밀리초 수만큼 sleep
  • panic: 패닉
  • break: gdb를 실행하고 디버거로 중단
  • print: inject 변수의 failpoint 경로 출력
  • pause: failpoint가 비활성화될 때까지 일시 중지

프로그램에 failpoint를 주입하는 방법

• failpoint.Inject를 호출하여 호출 지점에 failpoint를 주입할 수 있습니다. 여기서 failpoint-name은 failpoint를 트리거하는 데 사용되고 failpoint-closure는 IF 문의 본문으로 확장됩니다.

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

  변환된 코드는 다음과 같습니다:

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

• failpoint.Value는 failpoint.Enable("failpoint-name", "return(5)")에 의해 전달되는 값이며 무시할 수 있습니다.

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

  또는

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

  그리고 변환된 코드는 다음과 같습니다:

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

• 또한 failpoint 클로저는 context.Context를 받는 함수일 수 있습니다. 병렬 테스트나 다른 경우에 failpoint가 활성화될지 제어하는 것처럼 context.Context로 몇 가지 맞춤 작업을 할 수 있습니다. 예를 들어,

  failpoint.InjectContext(ctx, "failpoint-name", func(val failpoint.Value) {
      fmt.Println("unit-test", val)
  })
  

  변환된 코드는 다음과 같습니다:

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

• context.Context를 무시할 수 있으며, 이 경우 위의 비컨텍스트 버전과 동일한 코드가 생성됩니다. 예를 들어,

  failpoint.InjectContext(nil, "failpoint-name", func(val failpoint.Value) {
      fmt.Println("unit-test", val)
  })
  

  다음과 같이 변환됩니다

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

• failpoint.InjectCall을 사용하여 함수 호출을 주입할 수 있습니다. 이 유형의 마커는 failpoint.EnableCall을 통해서만 활성화할 수 있으며 InjectCall 호출 지점과 동일한 프로세스에서 호출되어야 합니다. 이 마커를 사용하면 failpoint 코드가 소스 코드를 오염시키지 않도록 할 수 있습니다. examples를 참조하세요.

• failpoint.WithHook으로 failpoint를 제어할 수 있습니다