קודי שגיאה של 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), כמו כשל בבדיקת רצף או ביטול עסקה. מציין שהבקשה התנגשה עם בקשה אחרת. אם מדובר בפעולת 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 לא חרגו מהקיבולת שלהם. ספריית הלקוח מנסה לבצע שוב את הפעולות שגרמו לשגיאות האלה ב-Spanner. אם כל הניסיונות החוזרים נכשלים, כדאי לעיין במאמר בנושא שגיאות במנגנון בקרה על זרימת נתונים.

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

שגיאות בסשן

‫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 בהגדרות של מאגר הסשנים.
הבקשות נמשכות זמן רב מדי. בקשות קריאה או כתיבה שפועלות לאורך זמן יכולות לתפוס את כל הסשנים הזמינים למשך תקופות ארוכות. אם הבקשות האלה נמשכות יותר מהזמן הקצוב לתפוגה של הגדרת השגת הסשן, בקשות חדשות לא יכולות לקבל סשן ממאגר הסשנים. בודקים למה לוקח הרבה זמן להשלים את הבקשות. אופטימיזציה של השאילתות או של הלוגיקה של האפליקציה כדי לקצר את זמן הביצוע. אפשר להגדיל את הזמן הקצוב לתפוגה של בקשת סשן. אפשר גם להפעיל סשנים מרובי-ערוצים בספריות לקוח שעומדות בדרישות כדי לשפר את ניצול הסשנים.
יש דליפות של נתוני סשנים. דליפת סשן מתרחשת כשהאפליקציה מוציאה סשן מהמאגר אבל לא מחזירה אותו אחרי השלמת הבקשה. בדרך כלל זה קורה כשאיטרטורים או קבוצות תוצאות לא נסגרים בצורה תקינה בקוד. אם כל הסשנים דולפים, אין סשנים זמינים לבקשות חדשות. מנפים באגים בקוד האפליקציה כדי לזהות ולתקן את דליפות הסשנים. חשוב לוודא שהקוד סוגר בצורה תקינה את כל האיטרטורים ואת כל קבוצות התוצאות. מידע נוסף זמין במאמר פתרונות לזיהוי דליפות של סשנים. אפשר גם להשתמש בתכונה ניקוי אוטומטי של דליפות סשנים כדי להגדיר את מאגר הסשנים כך שיפתור אוטומטית עסקאות לא פעילות.
יצירת הסשן איטית. יצירת סשן היא פעולה שדורשת הרבה משאבי מחשוב. ספריות לקוח שולחות BatchCreateSessions APIs כדי ליצור סשנים ראשוניים (על סמך ההגדרה של minSession) ו-CreateSessions APIs לסשנים נוספים (עד maxSession). אם יצירת הסשן נמשכת יותר מהזמן הקצוב לתפוגה של קבלת סשן, יכול להיות שהבקשות החדשות יגיעו לזמן קצוב לתפוגה בזמן ההמתנה לסשנים. בודקים את זמן האחזור של קריאות ל-API של BatchCreateSessions ושל CreateSessions. יכול להיות שייקח זמן רב ליצור סשן בגלל בעיות במשאבים בצד של Spanner או בגלל מספר גדול של פעולות ליצירת סשנים בו-זמנית.

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

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

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

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

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

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