קודי שגיאה של Spanner

בדף הזה מפורטים קודי שגיאה של Spanner ופעולות מומלצות לטיפול בשגיאות האלה. ממשקי Google API, כולל Spanner, משתמשים בקודי השגיאה הקנוניים שמוגדרים על ידי google.rpc.Code.

כשבקשת Spanner מצליחה, ה-API מחזיר קוד סטטוס 200 OK של HTTP יחד עם הנתונים המבוקשים בגוף התשובה.

כשבקשה נכשלת, Spanner API מחזיר קוד סטטוס HTTP‏ 4xx או 5xx שמזהה באופן כללי את הכשל, וגם תגובה שמספקת מידע ספציפי יותר על השגיאות שגרמו לכשל.

אובייקט התגובה מכיל שדה יחיד error שהערך שלו מכיל את הרכיבים הבאים:

רכיב תיאור
code קוד סטטוס של HTTP שמזהה באופן כללי את כשל הבקשה.
message מידע ספציפי על כשל בבקשה.
status קוד השגיאה הקנוני (google.rpc.Code) עבור Google APIs. קודי השגיאה שמוחזרים על ידי Spanner API מפורטים במאמר קודי שגיאה.

אם בקשה שנוצרה עם סוג תוכן application/x-protobuf מובילה לשגיאה, היא תחזיר הודעת google.rpc.Status שעברה סריאליזציה כמטען ייעודי.

קודי שגיאה

הדרך המומלצת לסיווג שגיאות היא לבדוק את הערך של קוד השגיאה הקנוני (google.rpc.Code). בשגיאות JSON, הקוד הזה מופיע בשדה status. בשגיאות application/x-protobuf, הערך מופיע בשדה code.

קוד שגיאה תיאור הפעולה המומלצת
ABORTED הפעולה בוטלה, בדרך כלל בגלל בעיה של בו-זמניות (concurrency), כמו כשל בבדיקת רצף או ביטול טרנזקציה. מציין שהבקשה התנגשה עם בקשה אחרת.

מידע נוסף על שגיאות Database schema has changed זמין במאמר שגיאה: סכימת מסד הנתונים השתנתה.		 אם מדובר בפעולת commit לא טרנזקציונלית:
מנסים לשלוח שוב את הבקשה או משנים את מבנה הישויות כדי לצמצם את התחרות.

אם מדובר בבקשות שמהוות חלק מפעולת commit טרנזקציונלית:
מנסים לשלוח שוב את כל הטרנזקציה או משנים את מבנה הישויות כדי לצמצם את התחרות.
ALREADY_EXISTS הישות שהלקוח ניסה ליצור כבר קיימת (לדוגמה, הוספת שורה עם מפתח ראשי קיים). אל תנסו שוב בלי לפתור את הבעיה.
CANCELLED הפעולה בוטלה, בדרך כלל על ידי המתקשר. מנסים שוב לבצע את הפעולה.
DEADLINE_EXCEEDED המועד האחרון חלף לפני שהפעולה הסתיימה. בודקים אם תאריך היעד מספיק. השתמשו במועד אחרון שמתאים לזמן שבו התשובה תהיה שימושית. שימו לב: בפעולות שמשנות את מצב המערכת, יכול להיות שתוחזר שגיאה גם אם הפעולה הושלמה בהצלחה.

טיפים נוספים זמינים במאמר פתרון בעיות שגיאה מסוג 'חריגה מהמועד האחרון'.
FAILED_PRECONDITION הפעולה נדחתה כי לא התקיים תנאי מוקדם לבקשה. בשדה ההודעה בתגובת השגיאה מופיע מידע על התנאי המוקדם שנכשל. לדוגמה, קריאה או שליחת שאילתה מחותמת זמן שחרגה מהזמן המקסימלי של חוסר עדכניות חותמת הזמן. אל תנסו שוב בלי לפתור את הבעיה.
INTERNAL השרת החזיר שגיאה. חלק מהכללים הקבועים שהמערכת הבסיסית מצפה להם נשברו. אל תנסו שוב אלא אם אתם מבינים את הנסיבות הספציפיות ואת הסיבה לשגיאה.
INVALID_ARGUMENT הלקוח ציין ערך לא חוקי. בשדה ההודעה בתגובת השגיאה מפורט הערך הלא תקין. אל תנסו שוב בלי לפתור את הבעיה.
NOT_FOUND מציין שישות מסוימת שנדרשה, כמו עדכון ישות או שאילתה של טבלה או עמודה, לא קיימת. אל תנסו שוב בלי לפתור את הבעיה.
OUT_OF_RANGE הניסיון לבצע את הפעולה היה אחרי הטווח התקף. אל תנסו שוב בלי לפתור את הבעיה.
PERMISSION_DENIED למשתמש לא הייתה הרשאה להגיש את הבקשה. אל תנסו שוב בלי לפתור את הבעיה.
RESOURCE_EXHAUSTED אחד מהמשאבים מוצה.

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

במישור הנתונים, יכול להיות שהעומס על צמתי Spanner גדול מדי.

מידע נוסף זמין גם במאמר קודי שגיאה שקשורים לסשן.		 במישור האדמין, מוודאים שלא חרגתם מהמכסה של Spanner או של הפרויקט. אם חרגתם ממכסה, אתם יכולים לבקש להגדיל את המכסה או להמתין עד שהמכסה תתאפס ולנסות שוב. מגדירים את הניסיונות החוזרים כך שישתמשו בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff).

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

באופן כללי, אם האפליקציה נתקלת בשגיאות RESOURCE_EXHAUSTED, צריך להתייחס למצב כאילו מדובר בשגיאה UNAVAILABLE ולנסות שוב עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
UNAUTHENTICATED בבקשה לא צוינו פרטי כניסה תקינים לאימות לצורך ביצוע הפעולה. אל תנסו שוב בלי לפתור את הבעיה.
UNAVAILABLE השרת לא זמין. צריך לנסות שוב באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff). חשוב לזכור שלא תמיד בטוח לנסות שוב פעולות שהן לא אידמפוטנטיות.
UNIMPLEMENTED הפעולה לא יושמה או שהיא לא אפשרית או לא מופעלת בשירות הזה. אל תנסו שוב בלי לפתור את הבעיה.
UNKNOWN השרת החזיר שגיאה לא ידועה. יכול להיות ששגיאות שמוחזרות על ידי ממשקי API שלא מחזירים מספיק מידע על השגיאה יומרו לשגיאה הזו. בודקים שהבקשה בטוחה. ואז לנסות שוב עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).

שגיאה: סכימת מסד הנתונים השתנתה

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

  • Database schema has changed
  • Transaction aborted. Database schema probably changed during transaction, retry may succeed.

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

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

שגיאות בסשן

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

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

הסשן לא נמצא

השגיאה Session not found מתרחשת כשהאפליקציה מנסה להשתמש בסשן שכבר לא קיים. יכולות להיות לכך כמה סיבות.

  • יכול להיות שאפליקציית הלקוח תמחק סשן באופן מפורש. לדוגמה, סגירה של לקוח מסד נתונים בקוד או קריאה ישירה ל-API‏ deleteSessions מסירה את הסשן. אם אתם לא משתמשים באחת מספריות הלקוח של Spanner, צריך ליצור סשן חדש כשהשגיאה הזו מתרחשת. מוסיפים את הסשן החדש למאגר הסשנים ומסירים את הסשן שנמחק מהמאגר.

  • בנוסף, Spanner מוחק סשנים באופן אוטומטי בתנאים מסוימים.

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

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

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

המשאב מוצה

השגיאות RESOURCE_EXHAUSTED: No session available in the pool או RESOURCE_EXHAUSTED: Timed out after waiting X ms for acquiring session מציינות שהאפליקציה לא יכולה לקבל סשן ממאגר הסשנים. המצב הזה קורה כשאין סשנים זמינים לעיבוד של בקשות קריאה או כתיבה חדשות.

בטבלה הבאה מתוארות כמה סיבות אפשריות לשגיאות האלה, ומומלצות פעולות מתאימות.

סיבה הפעולה המומלצת
כל הסשנים במאגר נמצאים בשימוש. יכול להיות שהאפליקציה שלכם תקבל יותר בקשות בו-זמניות ממספר הסשנים המקסימלי שהוגדר. כל הסשנים במאגר תפוסים, ואין סשנים זמינים לבקשות חדשות. הפעלת סשנים מרובים. סשנים עם ריבוב מאפשרים לכמה טרנזקציות וקריאות לחלוק סשן אחד, מה שיכול להקטין את המספר הכולל של הסשנים שנדרשים לאפליקציה. אפשר גם להגדיל את ההגדרה maxSession או minSession בהגדרות של מאגר הסשנים.
הבקשות נמשכות זמן רב מדי. בקשות קריאה או כתיבה ארוכות יכולות לתפוס את כל הסשנים הזמינים למשך תקופות ארוכות. אם הבקשות האלה נמשכות יותר זמן מההגדרה של הזמן הקצוב לתפוגה של סשן, אי אפשר לקבל סשן ממאגר הסשנים לבקשות חדשות. בודקים למה לוקח הרבה זמן להשלים את הבקשות. אופטימיזציה של השאילתות או של הלוגיקה של האפליקציה כדי לקצר את זמן הביצוע. אפשר להגדיל את הזמן הקצוב לתפוגה של בקשת סשן. אפשר גם להפעיל סשנים מרובי-ערוצים בספריות לקוח שעומדות בדרישות כדי לשפר את ניצול הסשנים.
יש דליפות של נתוני סשנים. דליפת סשן מתרחשת כשהאפליקציה מוציאה סשן מהמאגר אבל לא מחזירה אותו אחרי השלמת הבקשה. בדרך כלל זה קורה כשאיטרטורים או קבוצות תוצאות לא נסגרים בצורה תקינה בקוד. אם כל הסשנים דולפים, אין סשנים זמינים לבקשות חדשות. מנפים באגים בקוד האפליקציה כדי לזהות ולתקן את דליפות הסשן. חשוב לוודא שהקוד סוגר בצורה תקינה את כל האיטרטורים ואת כל קבוצות התוצאות. מידע נוסף זמין במאמר פתרונות לזיהוי דליפות של סשנים. אפשר גם להשתמש בתכונה ניקוי אוטומטי של דליפות סשן כדי להגדיר את מאגר הסשנים כך שיפתור אוטומטית טרנזקציות לא פעילות.
יצירת הסשן איטית. יצירת סשן היא פעולה שדורשת הרבה משאבי מחשוב. ספריות לקוח שולחות בקשות ל-API‏ BatchCreateSessions כדי ליצור סשנים ראשוניים (על סמך ההגדרה minSession) ובקשות ל-API‏ CreateSessions כדי ליצור סשנים נוספים (עד maxSession). אם יצירת הסשן נמשכת יותר מהזמן שמוגדר לזמן קצוב לתפוגה של קבלת סשן, יכול להיות שהבקשות החדשות יגיעו לזמן קצוב לתפוגה בזמן ההמתנה לסשנים. בודקים את זמן האחזור של קריאות ל-API של BatchCreateSessions ושל CreateSessions. יצירת סשנים איטית יכולה לנבוע מבעיות במשאבים בצד של Spanner או ממספר גדול של פעולות מקבילות ליצירת סשנים.

שגיאות במנגנון הבקרה על זרימת נתונים

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

  • יש שימוש גבוה ב-CPU בצומת Spanner. אם אתם חושדים שהבקשה שלכם גורמת לשימוש גבוה ב-CPU, אתם יכולים להשתמש במדדי ניצול ה-CPU כדי לבדוק את הבעיה.
  • יכול להיות שיש נקודות חמות, ולכן זמן העיבוד של הבקשה ארוך יותר. אם אתם חושדים שהבקשה גורמת לנקודות חמות, כדאי לעיין במאמר בנושא איתור נקודות חמות במסד הנתונים כדי לבדוק את הבעיה. מידע נוסף זמין במאמר בנושא Key Visualizer.

מנגנון בקרה על זרימת נתונים נתמך בספריות הלקוח הבאות:

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

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