פתרון בעיות שקשורות לסימוני תכונות

במדריך הזה מוסבר איך לאבחן ולפתור בעיות נפוצות שקשורות ל-feature flags ב-App Lifecycle Manager.

הערכת ה-SDK וזמן הריצה

ה-API של OpenFeature מתוכנן כך שקריאות להערכת דגלים לא יגרמו לחריגות לא מטופלות, אלא יחזירו את ערך ברירת המחדל אם תתרחש שגיאה בהערכה.

תסמין: הדגל מחזיר ערך ברירת מחדל בטוח

אם אין גישה לשירות של הדגל, אם הספק לא זמין או אם הדגל לא מוגדר כמו שצריך, ה-SDK מחזיר את ערך ברירת המחדל הנדרש שמופיע בקוד.

פתרון:

  1. בודקים את החיבור בין ספק OpenFeature לנקודת הקצה (endpoint) של saasconfig.googleapis.com.
  2. בודקים אם יש שגיאות אימות. מוודאים שלחשבון השירות של האפליקציה בזמן הריצה יש את התפקיד roles/saasconfig.viewer.
  3. מוודאים שהערך של FLAGD_SOURCE_PROVIDER_ID נכון.

הבעיה: תוצאות לא צפויות של הבדיקה

אם דגל לא מחזיר את הווריאנט הצפוי:

פתרון:

  1. בודקים את התנאים של ה-CEL ואת הקשר ההערכה.
  2. אם חסר מאפיין חובה בהקשר במהלך בדיקת תנאי, מנוע ההערכה מדלג על הכלל הספציפי הזה.
  3. אם חסר מאפיין במהלך הקצאה שמבוססת על אחוזים, ההערכה מחזירה את הערך INVALID_CONTEXT.

פתרון בעיות בסנכרון של תבניות App-Centric ובהשקות של מסופים

אם אתם משתמשים בתבניות מורכבות של Application Design Center ובמסוף Google Cloud כדי להגדיר את ה-feature flags, אתם יכולים להיעזר בשלבים הבאים כדי לפתור בעיות בסנכרון ובהשקה של התבניות.

הבעיה: לא נוצרים סוגי יחידות אחרי שמקשרים תבנית מורכבת של App Design Center

אם הכרטיסייה Unit kinds במוצר ה-SaaS נשארת ריקה אחרי שמקשרים תבנית מורכבת:

פתרון:

  1. לפני שאתם מייבאים את תבנית האפליקציה המשולבת ל-SaaS, ודאו שכל תבנית אפליקציה רגילה מוטמעת ותבנית האפליקציה המשולבת הראשית נוספו לקטלוג ב-Application Design Center.
  2. מוודאים שלסוכן השירות של App Lifecycle Manager‏ (service-PROJECT_NUMBER@gcp-sa-saasservicemgmt.) יש את התפקיד roles/saasservicemgmt.serviceAgent בפרויקט.
  3. כדי לבדוק את סטטוס הסנכרון של התבנית, צריך לבדוק את דף הפרטים של הצעת ה-SaaS במסוף Google Cloud או להריץ את הפקודה gcloud beta app-lifecycle-manager saas describe SAAS_OFFERING_ID --location=global.

מחליפים את מה שכתוב בשדות הבאים:

  • ‫PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .
  • ‫SAAS_OFFERING_ID: המזהה של מוצר ה-SaaS.

תסמין: השקת דגל במסוף לא מעדכנת יחידה שנוצרה מתבנית רגילה

אם השקת הדגל הושלמה במסוף Google Cloud , אבל יחידה שנוצרה מתבנית רגילה לא מקבלת את הגדרת הדגל המעודכנת:

פתרון:

  1. מוודאים שהיחידה שייכת לסוג היחידה המטורגט, נמצאת באזור שכלול בהשקה ותואמת לכל unitFilter שמוגדר בסוג ההשקה.
  2. מוודאים שהערך של FLAGD_SOURCE_PROVIDER_ID באפליקציה תואם לנתיב המשאב המלא של הגדרת ה-feature flag של היחידה (projects/PROJECT_ID/locations/LOCATION/featureFlagsConfigs/UNIT_ID).

מחליפים את מה שכתוב בשדות הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫LOCATION: האזור של היחידה.
  • ‫UNIT_ID: מזהה היחידה.

מעקב אחרי השקות

כדי לעקוב אחרי השקה של feature flag, צריך לוודא את מצב התזמור (האם ההשקה הושלמה?) ואת תקינות האפליקציה (האם הקובץ הבינארי זיהה את ה-flag?).

מצב תזמור ההשקה

המערכת עוקבת אחרי שיעור ההצלחה של הפעולות בזמן אמת.

השהיה אוטומטית

כדי למנוע מצב שבו הגדרה שגויה תגיע לכל הצי, המערכת משהה באופן אוטומטי את ההשקה אם שיעור הכשלים במיקום מסוים חורג מתקציב השגיאות שהוגדר בסוג ההשקה (errorBudget.allowedCount או errorBudget.allowedPercentage, למשל סף של 10% לכל מיקום).

בדיקת הנתונים הסטטיסטיים המסכמים

משתמשים בפקודה describe כדי לראות את מספר הכשלים המצטבר ולקבוע אם ההשקה היא PAUSED או FAILED.

gcloud beta app-lifecycle-manager rollouts describe ROLLOUT_ID --location=global

סינון עדכוני יחידות שנכשלו

אחרי שמוודאים שיש כשלים, צריך למצוא את היחידות הספציפיות שלא קיבלו את העדכון. אפשר להשתמש במסנן הזה כדי לבודד רק את עדכוני הדגלים שנכשלו באזור ספציפי:

gcloud beta app-lifecycle-manager unit-operations list \
    --location=LOCATION \
    --filter="state:UNIT_OPERATION_STATE_FAILED AND flag_update:*"

אבחון שורש הבעיה

לכל פעולה שנכשלה, אפשר לאחזר הודעת שגיאה מפורטת שסופקה על ידי מנוע ההפעלה בשדה conditions (message ו-reason) וב-errorCategory (או לבדוק את stateMessage במשאב ההשקה).

gcloud beta app-lifecycle-manager unit-operations describe OPERATION_ID --location=LOCATION

מחליפים את מה שכתוב בשדות הבאים:

  • ‫ROLLOUT_ID: מזהה ההשקה.
  • ‫LOCATION: האזור של פעולת היחידה.
  • ‫OPERATION_ID: המזהה של הפעולה ביחידה.

יחידה ללא הגדרות

בקטע הזה מוסבר איך הצמדת יחידה יכולה למנוע ממנה לקבל הגדרות של feature flag, ואיך לשחזר את היחידה.

הסבר על הצמדת יחידות

הצמדה מקפיאה יחידה בגרסה הנוכחית שלה, ומונעת את העדכון שלה על ידי השקות אוטומטיות או ידניות. יחידה מוצמדת מוחרגת באופן מפורש מפעולות השקה עד שתקופת ההצמדה שלה מסתיימת או עד שמבטלים את ההצמדה שלה באופן ידני.

חסרה הגדרה ביחידות המוצמדות

תרחיש קריטי מתרחש כשמצמידים יחידה במהלך השקה של feature flag. הצמדה חוסמת את כל העדכונים, כלומר היחידה מדלגת על הפעולה FlagUpdate שנדרשת כדי לקבל את ההגדרות שלה.

התופעה: אחרי שמבטלים את ההצמדה של היחידה ומשדרגים אותה לקובץ בינארי שדורש feature flags, האפליקציה לא מצליחה לבצע אתחול או נכנסת ללולאה אינסופית של ניסיונות חוזרים. כתוצאה מכך, בדיקות המוכנות נכשלות והקונטיינר מופעל מחדש שוב ושוב.

שורש הבעיה: כשהיחידה הייתה מוצמדת, ההשקות עדכנו את השדה defaultFlagRevisions של משאב סוג היחידה ההורה, אבל היחידה המוצמדת דילגה על הפעולה FlagUpdate ולא קיבלה הגדרה פעילה.

פקודות אבחון

כדי לבדוק את הפעולות של עדכון הדגלים שנכשלו ואת סטטוס היחידה, משתמשים בפקודות הבאות.

1. הצגת רשימה של פעולות סימון שנכשלו

כדי למצוא יחידות שלא עודכנו, מסננים את פעולות היחידה לפי המצב UNIT_OPERATION_STATE_FAILED והסוג flag_update.

gcloud beta app-lifecycle-manager unit-operations list \
    --location="LOCATION" \
    --filter="state:UNIT_OPERATION_STATE_FAILED AND flag_update:*"

2. סינון ספציפי של השקות דגלים שנכשלו

כדי לאתר עדכוני דגלים שנכשלו בכל המכשירים או ביחידה ספציפית, מוסיפים תנאי למצב UNIT_OPERATION_STATE_FAILED.

gcloud beta app-lifecycle-manager unit-operations list \
    --location="LOCATION" \
    --filter="unit:UNIT_ID AND state:UNIT_OPERATION_STATE_FAILED AND flag_update:*"

3. בדיקת הסיבה לכישלון

משתמשים בפקודה describe כדי לבדוק את השדה conditions (message ו-reason) ואת errorCategory.

gcloud beta app-lifecycle-manager unit-operations describe "OPERATION_ID" --location="LOCATION"

4. בדיקת מצב היחידה

אפשר גם לבדוק את המצב הנוכחי של יחידה באופן ישיר. אם השקת הדגל נכשלה או שהפעולה האחרונה גרמה לשגיאה, הרשימה conditions של היחידה מכילה רשומה עם type: TYPE_OPERATION_ERROR.

gcloud beta app-lifecycle-manager units describe "UNIT_ID" --location="LOCATION"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫LOCATION: האזור של היחידה או של פעולת היחידה.
  • ‫UNIT_ID: מזהה היחידה.
  • ‫OPERATION_ID: המזהה של הפעולה ביחידה.

השבתה ידנית של אותות אכיפה

כדי לשחזר יחידה מוצמדת שלא קיבלה עדכוני דגלים, צריך להחיל את גרסאות הדגלים שמוגדרות כברירת מחדל מסוג היחידה שמעליה.

החלת תיקונים על סימון ברירת המחדל של סוג היחידה

אם חסרה הגדרה ביחידה כי היא הוצמדה במהלך השקה אחת או יותר, אפשר לשחזר אותה על ידי איפוס ידני של היחידה לקו הבסיס הנוכחי שמוגדר בסוג היחידה שלה.

  1. מבטלים את ההצמדה של היחידה (אם היא מוצמדת):

    gcloud beta app-lifecycle-manager units update "UNIT_ID" \
    --location="LOCATION" \
    --maintenance-pinned-until-time=""

  2. אחזור גרסאות ברירת המחדל מסוג היחידה הראשית:

    gcloud beta app-lifecycle-manager unit-kinds describe "UNIT_KIND_ID" \
    --location="LOCATION" \
    --format="value(defaultFlagRevisions.join(','))"

  3. יוצרים FlagRelease חדש שמכיל את הגרסאות האלה:

    gcloud beta app-lifecycle-manager flags releases create "recovery-release-1" \
    --location="LOCATION" \
    --unit-kind="UNIT_KIND_ID" \
    --revisions="REVISIONS"

  4. מפעילים באופן ידני פעולה ביחידת FlagUpdate כדי להחיל את גרסת התיקון:

    gcloud beta app-lifecycle-manager unit-operations create "recovery-op" \
    --unit="UNIT_ID" \
    --flag-update="projects/PROJECT_ID/locations/LOCATION/flagReleases/recovery-release-1" \
    --location="LOCATION"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫UNIT_ID: המזהה של היחידה שרוצים לשחזר.
  • ‫LOCATION: האזור של היחידה.
  • ‫UNIT_KIND_ID: המזהה של סוג היחידה הראשית.
  • ‫REVISIONS: רשימה מופרדת בפסיקים של שמות המשאבים של גרסאות ברירת המחדל של הדגלים שהוחזרו בשלב 2.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .