failpoint

Golang के लिए failpoints का एक कार्यान्वयन। फेल पॉइंट्स (fail points) का उपयोग कोड पॉइंट्स जोड़ने के लिए किया जाता है जहाँ त्रुटियाँ उपयोगकर्ता-नियंत्रित तरीके से इंजेक्ट की जा सकती हैं। फेल पॉइंट एक कोड स्निपेट है जो केवल तब निष्पादित होता है जब संबंधित failpoint सक्रिय हो।

Quick Start (use 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. GO_FAILPOINTS पर्यावरण चर के साथ failpoints सक्षम करें

   root@kitploit:~

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

   नोट: GO_FAILPOINTS InjectCall प्रकार के मार्कर के साथ काम नहीं करता है।

6. यदि आप परीक्षण चलाने के लिए go run का उपयोग करते हैं, तो अपने कमांड में जनरेट की गई को जोड़ना न भूलें, जैसे:

Quick Start (use 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. GO_FAILPOINTS पर्यावरण चर के साथ failpoints सक्षम करें

   root@kitploit:~

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

5. आप go run या go test का भी उपयोग कर सकते हैं, जैसे:

   root@kitploit:~

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

Design principles

• Failpoint को मान्य Golang कोड में परिभाषित करें, टिप्पणियों या किसी और चीज़ में नहीं

• Failpoint की कोई अतिरिक्त लागत नहीं होती

  • नियमित लॉजिक पर प्रभाव नहीं डालेगा
  • नियमित कोड के प्रदर्शन में गिरावट नहीं लाएगा
  • Failpoint कोड अंतिम बाइनरी में दिखाई नहीं देगा

• Failpoint रूटीन लिखने/पढ़ने योग्य है और कंपाइलर द्वारा जाँचा जाना चाहिए

• Failpoint परिभाषा द्वारा जनरेट किया गया कोड पढ़ने में आसान है

• इंजेक्टिंग कोड के साथ लाइन नंबर समान रखें (डिबग करना आसान)

• context.Context के साथ समानांतर परीक्षणों का समर्थन करें

Key concepts

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

• Marker functions

  • यह सिर्फ एक खाली फ़ंक्शन है

    • रीराइटर को समानता वाले स्टेटमेंट के साथ रीराइट करने का संकेत देने के लिए
    • रीराइट नियम के रूप में कुछ पैरामीटर प्राप्त करने के लिए
    • यह कंपाइल समय पर इनलाइन होगा और बाइनरी में कुछ भी एमिट नहीं करेगा (शून्य लागत)
    • बाहरी स्कोप के चर कैप्चर करके क्लोज़र में एक्सेस किए जा सकते हैं, और परिवर्तित कोड अभी भी मान्य है क्योंकि सभी कैप्चर किए गए चर IF स्टेटमेंट के बाहरी स्कोप में स्थित होते हैं।

  • यह लिखना/पढ़ना आसान है

  • Failpoints के लिए एक कंपाइलर जाँच प्रस्तुत करता है जो failpoint कोड अमान्य होने पर नियमित मोड में संकलित नहीं हो सकता

• Marker funtion list

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

How to inject a failpoint to your program

• आप कॉल साइट पर failpoint इंजेक्ट करने के लिए failpoint.Inject को कॉल कर सकते हैं, जहाँ 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")
  })
  

  OR

  root@kitploit:~

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

Some complicated failpoints demo

• IF इनिशियल स्टेटमेंट या CONDITIONAL एक्सप्रेशन में failpoint इंजेक्ट करें

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

• SELECT स्टेटमेंट में failpoint इंजेक्ट करें ताकि failpoint सक्रिय होने पर यह एक CASE को ब्लॉक कर दे

Failpoint name best practice

जैसा कि आप ऊपर देखते हैं, _curpkg_ स्वचालित रूप से failpoint.Eval कॉल में मूल failpoint नाम को लपेटेगा। आप _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)"
  

Implementation details

1. मार्कर फ़ंक्शन का एक समूह परिभाषित करें
2. इम्पोर्ट्स को पार्स करें और ऐसी सोर्स फ़ाइल को प्रून करें जो failpoint इम्पोर्ट नहीं करती
3. मार्कर फ़ंक्शन कॉल खोजने के लिए AST को ट्रैवर्स करें
4. मार्कर फ़ंक्शन कॉल को एक IF स्टेटमेंट के साथ फिर से लिखा जाएगा, जो यह निर्धारित करने के लिए failpoint.Eval को कॉल करता है कि failpoint सक्रिय है या नहीं और यदि failpoint सक्षम है तो failpoint कोड निष्पादित करता है।

Acknowledgments

• प्रारंभिक कार्यान्वयन प्रदान करने के लिए gofail को धन्यवाद।