failpoint

تنفيذ لنقاط الفشل failpoints بلغة Golang. تُستخدم نقاط الفشل لإضافة نقاط في الكود يمكن عندها حقن الأخطاء بطريقة يتحكم بها المستخدم. نقطة الفشل هي مقتطف برمجي لا يُنفَّذ إلا عندما تكون نقطة الفشل المقابلة نشطة.

البدء السريع (استخدام failpoint-ctl)

1. ابنِ failpoint-ctl من المصدر

   root@kitploit:~

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

2. احقن نقاط الفشل في برنامجك، مثال:

   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

   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. احقن نقاط الفشل في برنامجك، مثال:

   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

   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
   

مبادئ التصميم

• عرّف نقطة الفشل في كود Golang صالح، وليس في تعليقات أو أي شيء آخر

• لا تكلف نقطة الفشل أي عبء إضافي

  • لن تؤثر على المنطق العادي
  • لن تسبب تراجعًا في أداء الكود العادي
  • لن يظهر كود نقطة الفشل في الملف الثنائي النهائي

• روتين نقطة الفشل قابل للكتابة/القراءة ويجب أن يفحصه المترجم

• الكود المُولَّد من تعريف نقطة الفشل سهل القراءة

• الحفاظ على نفس أرقام الأسطر كما في الأكواد المُحقنة (أسهل للتنقيح)

• دعم الاختبارات المتوازية باستخدام context.Context

المفاهيم الأساسية

• نقطة الفشل

  نقطة الفشل هي مقتطف برمجي لا يُنفَّذ إلا عندما تكون نقطة الفشل المقابلة نشطة. لن يُنفَّذ الإغلاق أبدًا إذا تم تنفيذ 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.

  • سهلة الكتابة/القراءة

  • توفير فحص مترجم لنقاط الفشل التي قد لا تُترجم في الوضع العادي إذا كان كود نقطة الفشل غير صالح

• قائمة دوال العلامات

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

كيفية حقن نقطة فشل في برنامجك

• يمكنك استدعاء failpoint.Inject لحقن نقطة فشل في موقع الاستدعاء، حيث يُستخدم failpoint-name لتفعيل نقطة الفشل وسيتم توسيع 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")
  })
  

  والكود المحوَّل يبدو كالتالي:

  root@kitploit:~

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

بعض الأمثلة المعقدة لنقاط الفشل

• حقن نقطة فشل في جملة INIT التالية لـ 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)
      }
  }
  

• حقن نقطة فشل في جملة SELECT لحجب إحدى حالات CASE إذا كانت نقطة الفشل نشطة

أفضل الممارسات لاسم نقطة الفشل

كما ترى أعلاه، يقوم _curpkg_ تلقائيًا بلف اسم نقطة الفشل الأصلي في استدعاء failpoint.Eval. يمكنك اعتبار _curpkg_ ككليشيه يقوم تلقائيًا بإضافة مسار الحزمة الحالية إلى اسم نقطة الفشل. على سبيل المثال،

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.

نظرًا لأن جميع نقاط الفشل في حزمة واحدة تشترك في نفس مساحة الأسماء، يجب أن نكون حريصين على تجنب تعارض الأسماء. هناك بعض قواعد التسمية الموصى بها لتحسين هذا الوضع.

• حافظ على الاسم فريدًا في الحزمة الفرعية الحالية

• استخدم اسمًا واضحًا بذاته لنقطة الفشل

  يمكنك تفعيل نقاط الفشل عبر متغيرات البيئة

  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. افحص الاستيرادات واستبعد ملفات المصدر التي لا تستورد نقطة فشل
3. اجتاز شجرة AST للعثور على استدعاءات دوال العلامات
4. ستُعاد كتابة استدعاءات دوال العلامات بجملة IF، تستدعي failpoint.Eval لتحديد ما إذا كانت نقطة الفشل نشطة وتنفذ كود نقطة الفشل إذا كانت مفعّلة

شكر وتقدير

• شكرًا gofail لتوفير التنفيذ الأولي.