פתרון בעיות במאגרי נתונים של Gemini Enterprise

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

כדי לקבל תמונה מלאה של שגיאה, חשוב להבין איך כלי הניטור של Google Cloudפועלים יחד:

  • ‫Cloud Monitoring: מזהה מתי יש בעיה. אפשר להשתמש בו כדי לראות מגמות ברמה גבוהה, שיעורי שגיאות ולהגדיר התראות למאגרי הנתונים.
  • ‫Cloud Trace: מאפשר לגלות איפה הבעיה מתרחשת. אפשר להשתמש בו כדי לראות את מחזור החיים של בקשה, לנתח את הטווחים ולזהות בדיוק איזה שלב גרם לזמן אחזור ארוך או לכשל.
  • ‫Cloud Logging: הסבר למה הבעיה מתרחשת. הדוח הזה מאפשר לך לקרוא את הודעות השגיאה המדויקות ואת המטענים הייעודיים (payloads) שמשויכים לבקשה שנכשלה.
  • יומני ביקורת ב-Cloud: מזהים מי או איזו מדיניות חסמה את הפעולה. אפשר להשתמש בו כדי לעקוב אחרי תאימות אבטחה, שינויים בהרשאות ופעולות ניהוליות שעלולות לגרום לדחיית גישה.

תהליך העבודה של ניפוי באגים

כשבודקים בעיה במאגר נתונים, כדאי לפעול לפי תהליך העבודה הבא כדי לבודד את שורש הבעיה ולפתור אותה:

  1. בדיקת מגמות בשיעור השגיאות
  2. חיפוש הבקשה הספציפית שנכשלה
  3. הצגת המטען הייעודי (payload) של השגיאה
  4. הצלבת נתונים ביומני ביקורת

  1. נכנסים לדף Metrics Explorer במסוף Google Cloud .

    לדף Metrics Explorer

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

איתור הבקשה הספציפית שנכשלה

  1. במסוף Google Cloud , נכנסים לדף Trace explorer:

    כניסה אל Trace explorer

    אפשר גם להשתמש בסרגל החיפוש כדי למצוא את הדף הזה.

  2. בודקים בתרשים הפיזור אם יש עקבות עם סמל שגיאה (סימן קריאה אדום) או זמן אחזור ארוך באופן חריג.
  3. לוחצים על מעקב כדי לראות את תרשים הגאנט שלו.
  4. בודקים את טווח הזמן invoke_connector כדי לראות איפה התהליך נתקע או נכשל.
  5. בנוסף, אתם יכולים למצוא את אסימון הסיוע הייחודי שמשויך לבקשה ספציפית. אם אתם צריכים להעביר בעיה מורכבת לטיפול ברמה גבוהה יותר ב Google Cloud תמיכה, תוכלו לשתף את אסימון העזרה הזה כדי לזרז את הבדיקה.

הצגת מטען הייעודי (payload) של השגיאה

  1. לוחצים על ה-span שנכשל ב-Trace Explorer.
  2. בחלונית הפרטים, לוחצים על הצגת יומנים.
  3. כך תעברו אוטומטית ל-Cloud Logging, עם סינון לבקשה הספציפית הזו. כאן אפשר לקרוא את המטען הייעודי (payload) הגולמי של היומן כדי לזהות את חתימת השגיאה המדויקת (כמו RESOURCE_EXHAUSTED או PERMISSION_DENIED).

הצלבת נתונים עם יומני ביקורת

אם מטען הייעודי (payload) של היומן מציין בעיה ב-IAM, היקף חסר או דחיית הרשאה, כדאי להצליב נתונים עם יומני הביקורת של Cloud:

  1. נכנסים לדף Logs Explorer במסוף Google Cloud .

    כניסה לדף Logs Explorer

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

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

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

  1. בדיקת מגמות שגיאות: לפני שמחפשים שגיאות ספציפיות, כדאי לדעת עד כמה הבעיה נפוצה. פותחים את Metrics Explorer ב-Cloud Monitoring ומסננים את מדדי הבקשות של מאגר הנתונים לפי tool_id: get_issue. יכול להיות שתראו עלייה חדה ופתאומית בשגיאות RESOURCE_EXHAUSTED. כך אפשר לוודא שמדובר בבעיה מערכתית, ולא רק בשגיאת הקלדה חד-פעמית של משתמש.
  2. מאתרים את הבקשה שנכשלה: פותחים את Trace Explorer ומגדירים את מסנן הזמן לשעה האחרונה. בתרשים הפיזור, אפשר לראות קבוצה של עקבות עם סמל שגיאה אדום שמציין כשלים. לוחצים על אחד מהמעקבים האחרונים כדי לבדוק אותו.
  3. בודקים את תרשים הגאנט: תרשים הגאנט ממחיש את מסלול הבקשה. אתם רואים טווח הורה תקין לניתוב הראשוני של הנציג, אבל מתחתיו יש טווח invoke_connector לא תקין שמטרגט באופן ספציפי את מאגר הנתונים של Jira Cloud.
  4. מעבר ליומנים: לוחצים על ה-span של invoke_connector שנכשל. בחלונית פרטי מעקב, לוחצים על Show logs.

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

    
"message": "Connector Error: Cause: Failed to execute spec-based tool 'get_issue': Request failed: HTTP error 403: {\"errorMessages\":[\"permission denied: [User] does not have access to [Resource]"],\"errors\":{}}"

    בהודעת השגיאה הזו, אפשר לראות את הכלי הספציפי (get_issue) שנכשל ואת ההודעה המפורשת שמציינת שלמשתמש שמבצע את הבקשה אין גישה למשאב הספציפי במערכת היעד.

  6. פתרון: בעזרת הקטע שגיאות נפוצות, אפשר לזהות את השגיאה הזו כגישה חסרה למשאב של משתמש קצה. הסוכן של Gemini Enterprise התחבר בהצלחה ל-Jira Cloud, אבל Jira Cloud דחה את השאילתה כי למשתמש אין הרשאות. כדי לפתור את הבעיה, צריך לבקש מהאדמין של Jira Cloud לתת למשתמש גישה למשאב הספציפי.

שגיאות נפוצות

כשאתם בודקים את המטען הייעודי (payload) של השגיאות ב-Cloud Logging, התמקדו בחתימות השגיאה הרחבות. את רוב השגיאות במאגרי הנתונים אפשר לפתור לבד. כדי להבין מה שורש הבעיה ולתקן אותה, חפשו את השגיאה שקיבלתם ברשימה הבאה.

שגיאות שקשורות לאימות ולגישה

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

טוקן OAuth לא תקין או שפג תוקפו

  • חתימת שגיאה: HTTP request failed with status code 401 / 401 Unauthorized
  • שורש הבעיה: פג התוקף של טוקן ה-OAuth או שהוא לא תקין.
  • פתרון: צריך להעניק מחדש הרשאה למאגר הנתונים בהגדרות של Gemini Enterprise כדי ליצור טוקן חדש.

הכלי נחסם על ידי מסנן פעולות

  • חתימת השגיאה: Permission "connectors.tool.execute" denied ... rejected by admin filter configuration
  • הגורם הבסיסי: האדמין חסם את הכלי באמצעות מסנן פעולות.
  • פתרון: האדמין צריך לעדכן את רשימת ההיתרים של הפעולה או הכלי.

היקפי הרשאות חסרים של OAuth

  • חתימות שגיאה: Access to [Resource] in [Third-Party API] requires [Scope] ... only [Scope] granted או Cause: Insufficient Permission
  • סיבת השורש: ברישום האפליקציה בפלטפורמת הצד השלישי חסרים ההיקפים הנדרשים.
  • פתרון: אדמין צריך להעניק את ההיקפים המדויקים שמופיעים ביומן ולתת לאפליקציה הרשאה מחדש.

חסרות הרשאות IAM בפרויקט

  • חתימת השגיאה: Access Denied: User does not have [permission] / mcp.tools.call permission
  • הסיבה: למבצע הקריאה או לחשבון השירות אין את הרשאות ה-IAM הנדרשות ב- Google Cloud בפרויקט היעד.
  • פתרון: צריך לתת למבצע הקריאה החוזרת את הרשאת ה-IAM שצוינה.

שגיאות שקשורות לביצועים ולהגבלת קצב הנתונים

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

הגבלת קצב של API של צד שלישי (שגיאה 429)

  • חתימת שגיאה: Cause: Request has been rate limited
  • שורש הבעיה: אתם שולחים בקשות בקצב מהיר יותר ממה שה-API של הצד השלישי מאפשר.
  • פתרון: צריך להפחית את קצב הבקשות, להטמיע אסטרטגיות השהיה או לבקש מספק הצד השלישי להגדיל את המכסה.

הלחצן 'הפעלת פעולות' לא מוצג

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

שגיאות שקשורות לחשיפה ולמשאבים

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

הגבלת החשיפה של צד שלישי

  • חתימת שגיאה: 422 ... you do not have permission to view [Resource/Users]
  • הסיבה: הגבלת הרשאות צפייה או מדיניות ארגונית בפלטפורמה של הצד השלישי מונעת את אחזור הנתונים.
  • פתרון: משנים את המינוי של הארגון של הצד השלישי או מקטינים את המגבלה של היקף השאילתה.

חסרה גישה למשאבים של משתמשי קצה

  • חתימת השגיאה: permission denied: [user] does not have access to [Resource]
  • שורש הבעיה: למשתמש הקצה שמבצע את הבקשה אין גישה לרכיב או למשאב הספציפי במערכת היעד.
  • פתרון: נותנים למשתמש גישה למשאב ישירות במערכת היעד.

שגיאות במערכת ובצד השרת

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

נקודת קצה איטית או עמוסה מדי של צד שלישי

  • חתימת השגיאה: context deadline exceeded
  • הסיבה הבסיסית: נקודת הקצה של הצד השלישי איטית או שיש עליה עומס יתר, ולכן הבקשה בצד של Google נכשלת בגלל חריגה מזמן קצוב לתפוגה.
  • פתרון: צריך לנסות לשלוח את הבקשה שוב. אם השגיאה נמשכת, צריך לפנות אל Google Cloud התמיכה כדי לקבל עזרה בהתאמת הגדרות הזמן הקצוב לתפוגה.

הגדרה שגויה של שיוך פרטי הכניסה לשרת ה-MCP

  • חתימת שגיאה: CredsPermissionException: auth.creds.useNormalUserEUC not granted / EUC_PRESENTER
  • שורש הבעיה: יש בעיה במדיניות בצד השרת, שבה קישור פרטי הכניסה של שרת ה-MCP לא מוגדר בצורה נכונה. אין פעולה שהלקוח יכול לבצע.
  • פתרון: פנו לתמיכה של Google Cloud .

פנייה לתמיכה

אם נתקלתם בשגיאה context deadline exceeded או CredsPermissionException שלא נפתרת, יכול להיות שתצטרכו לשלוח כרטיס תמיכה לצוות התמיכה של Google Cloud .

כדי לזרז את הטיפול בבעיה, לפני שפותחים כרטיס תמיכה כדאי לאסוף את פריטי המידע הבאים מכלי הניטור:

  • מ-Cloud Logging: המטען הייעודי (payload) המלא של יומן ה-JSON של השגיאה.
  • מ-Cloud Trace: אסימון העזרה ופרטי הטווח הספציפיים (כולל מזהה המעקב) שמשויכים לבקשה שנכשלה.
  • מיומני הביקורת של השימוש: חותמות זמן רלוונטיות של שינויים ב-IAM או שינויים במדיניות שאולי גרמו לבעיה.