פתרון בעיות ב-Monitoring API

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

‫Monitoring API הוא חלק מ-Cloud APIs. רשימה של קודי שגיאה משותפים והמלצות כלליות לטיפול בהם מופיעה במאמר טיפול בשגיאות.

שימוש ב-API Explorer לניפוי באגים

‫APIs Explorer הוא ווידג'ט שמוטמע בדפי העזר של שיטות API. הוא מאפשר להפעיל את השיטה על ידי מילוי שדות, בלי לכתוב קוד.

אם אתם נתקלים בבעיה עם קריאה לשיטה, השתמשו בווידג'ט APIs Explorer (נסה את ה-API הזה) בדף ההפניה של אותה שיטה כדי לאתר באגים. מידע נוסף זמין במאמר APIs Explorer.

שגיאות כלליות ב-API ובאימות

סעיף זה מפרט קודי שגיאה שניתן להחזיר על ידי מגוון שיטות של ממשק API לניטור.

401 UNAUTHENTICATED

קוד השגיאה 401 UNAUTHENTICATED מציין שפרטי הכניסה של OAuth2 או IAM חסרים, לא תקפים או שתוקפם פג.

שתי הודעות השגיאה הנפוצות עבור קוד שגיאה זה הן Request is missing required authentication credential ו-User is not authorized to access the project (or metric).

• סיבה: כותרת Authorization: Bearer <token> חסרה, אסימון OAuth2 או OIDC שפג תוקפו, או פרטי כניסה לא חוקיים לחשבון שירות.
• פתרון: רענון טוקנים לאימות באמצעות Application Default Credentials‏ (ADC) או gcloud auth print-access-token. כמו כן, צריך לוודא שמפתח חשבון השירות תקין.

אם אתם לא משתמשים ב-APIs Explorer, כדאי לנסות להשתמש בו. כאשר קריאה ל-API שלך פועלת ב-APIs Explorer, כנראה שיש בעיית הרשאה בסביבה שבה אתה מבצע את קריאה ל-API. עוברים אל הדף של API Manager כדי לוודא ש-Monitoring API מופעל בפרויקט.

403 PERMISSION_DENIED לגישה לפרויקט ולחיוב

קוד השגיאה 403 PERMISSION_DENIED מציין שאין לכם את ההרשאות הנדרשות לביצוע הפעולה המבוקשת.

יש כמה הודעות שגיאה שונות שיכולות להיות משויכות לקוד השגיאה הזה. שתי הודעות שגיאה נפוצות הן Billing check failed for project [PROJECT_ID] ו- Billing account disabled:

• הסיבה: החיוב ב-Cloud מושבת או מושעה בGoogle Cloud פרויקט. כדי להטמיע מדדים מותאמים אישית, צריך חשבון חיוב פעיל.
• פתרון: מקשרים חשבון לחיוב ב-Cloud פעיל לפרויקט במסוף Google Cloud .

אם קוד השגיאה הזה מופיע כשכותבים נתוני מדדים, כדאי לעיין גם במאמר 403 PERMISSION_DENIED כשכותבים נתוני מדדים.

404 NOT_FOUND

קוד השגיאה 404 NOT_FOUND מציין שמזהה פרויקט היעד לא קיים, או שהאזור או המיקום לא מזוהים.

בהמשך מפורטות הודעות שגיאה נפוצות שקשורות לקוד השגיאה הזה:

• Project [PROJECT_ID] not found

  • הסיבה: הפרויקט שצוין ב-URI של הבקשה לא קיים או שהוא נמחק.
  • פתרון: בודקים את האיות של מזהה הפרויקט ומוודאים שהפרויקט פעיל במסוף Google Cloud .

• Unavailable region or location או Unrecognized region or location

  • הסיבה: התווית של המיקום או האזור של המשאב שבמעקב לא תקינה או לא מזוהה.
  • פתרון: צריך להשתמש בשמות אזורים ואזורים תקפים Google Cloud , כמו us-central1 או us-central1-a.

• The requested URL was not found on this server

  • הסיבה: נתיב המשאב בכתובת ה-URL שגוי.
  • פתרון: השווה את כתובת ה-URL לכתובת ה-URL של השיטה המוצגת בדף ההפניה של השיטה. יכול להיות שהשגיאה הזו מצביעה על שגיאת איות, למשל "project" במקום "projects", או על שגיאת רישיות, למשל "TimeSeries" במקום "timeSeries".

500 INTERNAL, 503 UNAVAILABLE, 504 DEADLINE_EXCEEDED

יש שתי הודעות שגיאה נפוצות לקודי השגיאה האלה: Internal error encountered. Please retry after a few seconds ו- The service is currently unavailable.

• הסיבה: שגיאות זמניות בתשתית העורפית, בעיות ברשת או איזון מחדש של מחיצת מסד נתונים פנימי.
• רזולוציה: הטמעת השהיה מעריכית מקוצרת לפני ניסיון חוזר (exponential backoff) עם ריצוד בניסיונות חוזרים, החל משנייה אחת ועד 32 שניות. הגדרת מועדים אחרונים ללקוח RPC ל-15 שניות או יותר. מידע נוסף מופיע במאמר ניסיון חוזר לתיקון שגיאות ב-API.

תוצאות חסרות

אם קריאה ל-API מחזירה את קוד הסטטוס 200 ותגובה ריקה, כדאי לבדוק את הדברים הבאים:

• יכול להיות שהמסנן לא התאים לשום דבר בשיחה. ההתאמה של המסנן היא תלוית אותיות רישיות (case-sensitive). כדי לפתור בעיות במסננים, מתחילים בציון רכיב מסנן אחד בלבד, כמו metric.type, ומוודאים שמתקבלות תוצאות. הוסף את רכיבי המסנן האחרים אחד אחד כדי לבנות את הבקשה שלך.

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

יכולות להיות כמה סיבות לכך שנקודות נתונים חסרות כשמשתמשים בשיטה timeSeries.list:

• יכול להיות שהנתונים מיושנים. מידע נוסף זמין במאמר שמירת נתונים.

• יכול להיות שהנתונים עדיין לא הועברו לניטור. מידע נוסף זמין במאמר זמן האחזור של נתוני המדדים.

• המרווח לא תקין:

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

שגיאות בשאילתות של נתוני מדדים

בקטע הזה מפורטות השגיאות שיכולות להתרחש כשקוראים נתוני מדדים באמצעות שיטה כמו timeSeries.list.

400 INVALID_ARGUMENT כששולחים שאילתה לגבי נתוני מדדים

קוד השגיאה 400 INVALID_ARGUMENT מציין שגיאת אימות כלשהי בצד הלקוח. הודעת השגיאה שמשויכת לקוד השגיאה מספקת מידע מפורט יותר וספציפי לשיטת ה-API.

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

• Field filter had an invalid value או Field filter had an invalid value of "[FILTER]": [EXPLANATION]

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

• Request was missing field interval.endTime או Field interval.endTime had an invalid value

  • הסיבה: מציין שבבקשה חסרה שעת הסיום או שהערך לא תקין.

  • פתרון: אם אתם משתמשים ב-APIs Explorer, אל תשימו גרשיים סביב הערך של שדה הזמן. אלה הפורמטים התקינים:

    2026-05-11T01:23:45Z
    2026-05-11T01:23:45.678Z
    2026-05-11T01:23:45.678+05:00
    2026-05-11T01:23:45.678-04:30
    ```
    

שגיאות בכתיבת נתוני מדדים

בקטע הזה מפורטות השגיאות שיכולות לקרות כשמשתמשים בשיטה timeSeries.create כדי לכתוב נתוני מדדים, כולל:

• סיכום של קודי שגיאה.
• רשימה של הודעות שגיאה שמשויכות לכל קוד שגיאה. הערכים האלה כוללים גם את הסיבה וגם מידע על הפתרון. השגיאות הכלליות ב-API רלוונטיות גם לשיטה create.

אם לא מפעילים יומני ביקורת לגבי גישה לנתונים ב-Monitoring, יכול להיות שיהיו כשלים בשיטה timeSeries.create שלא יתועדו. עם זאת, אפשר:

• אפשר להשתמש בMetrics Explorer כדי לקבל מידע על שיעורי השגיאות. משתמשים בהגדרות הבאות:

  • מדד: monitoring.googleapis.com/api/request_count
  • מסנן: method = "google.monitoring.v3.MetricService.CreateTimeSeries"
  • צבירה: קיבוץ לפי response_code

• אפשר להשתמש בLogs Explorer כדי לשלוח שאילתות ליומני הפעילות שלכם ב-Admin. המערכת יוצרת את היומנים האלה כשהיא מנסה ליצור באופן אוטומטי תיאור מדד, והפעולה הזו נכשלת. כדי לראות את הרשומות האלה ביומן, מריצים את השאילתה הבאה אחרי שמחליפים את PROJECT_ID במזהה הפרויקט Google Cloud :

  logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"
  protoPayload.serviceName="monitoring.googleapis.com"
  protoPayload.methodName="google.monitoring.v3.MetricService.CreateMetricDescriptor"
  severity>=ERROR
  

• אפשר להשתמש ב-Logs Explorer כדי לשלוח שאילתות ליומנים בצד הלקוח.

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

• הסבר על הפעלת יומני ביקורת של גישה לנתונים מופיע במאמר הגדרת יומני ביקורת של גישה לנתונים.

• כדי לראות את הרשומות האלה ביומן, משתמשים ב-Logs Explorer ומריצים את השאילתה הבאה, אחרי שמחליפים את PROJECT_ID במזהה של פרויקטGoogle Cloud :

  logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access"
  protoPayload.serviceName="monitoring.googleapis.com"
  protoPayload.methodName="google.monitoring.v3.MetricService.CreateTimeSeries"
  severity>=ERROR
  

סיכום של קודי השגיאה timeSeries.create

קוד HTTP	קוד סטטוס gRPC	גורמים ראשוניים
400	INVALID_ARGUMENT	אימות המטען הייעודי (payload) נכשל – גודל אצווה, גודל תווית או מפתח, סדר חותמות הזמן, חוסר התאמה בין סכימה או סוג, מבנה היסטוגרמת ההתפלגות.
400	FAILED_PRECONDITION	חריגה מקצב הדגימה, סוג מדד לא נתמך או הגעה מאוחרת מחוץ לחלון השמירה.
401	UNAUTHENTICATED	פרטי כניסה חסרים, לא חוקיים או שתוקפם פג של OAuth2 או IAM.
403	PERMISSION_DENIED	חסר roles/monitoring.metricWriter תפקיד IAM, החיוב ב-Cloud מושבת או שיש ניסיון לא מורשה לכתוב לדומיינים שמורים של מדדים במערכת.
404	NOT_FOUND	מזהה פרויקט היעד לא קיים, או שהאזור או המיקום לא מזוהים.
429	RESOURCE_EXHAUSTED	חרגתם ממגבלת עוצמה (cardinality) של סדרות זמנים פעילות במשאב במעקב, הגעתם למגבלות של תיאור מדד הפרויקט או חרגתם ממגבלות קצב בקשות ה-API.
500	INTERNAL	שגיאה בשירות הסכימה או באחסון הפנימי.
503	UNAVAILABLE	שירות קצה עורפי לא זמין באופן זמני.
504	DEADLINE_EXCEEDED	הבקשה הסתיימה לפני כתיבת נקודות הנתונים לצמתי האחסון.

400 INVALID_ARGUMENT כשכותבים נתוני מדדים

‫400 INVALID_ARGUMENT מציין שגיאות באימות בצד הלקוח במבנה הבקשה, במטא-נתונים של המדד, בהגדרות של התוויות, בהתאמה של חותמות הזמן או בערכי הנקודות.

הפרות שקשורות למבנה הבקשה ולצירוף בקשות

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

• Request was missing field timeSeries

  • הסיבה: המערך time_series בבקשה היה ריק.
  • רזולוציה: צריך לכלול לפחות אובייקט TimeSeries אחד בכל בקשה.

• The maximum number of TimeSeries objects per Create request is 200

  • הסיבה: הבקשה מכילה יותר מ-200 אובייקטים TimeSeries.
  • פתרון: כותבים באצווה עד 200 סדרות עיתיות לכל בקשה.

• Field points had an invalid value: Only one point can be written per TimeSeries per request

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

• Duplicate TimeSeries encountered. Only one point can be written per TimeSeries per request

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

• user defined metrics are not supported on the metric domain "[DOMAIN]"

  • הסיבה: אין תמיכה במדדים שהוגדרו על ידי המשתמש בדומיין שצוין.
  • פתרון: אין.

תוויות ומגבלות על שמות

בהמשך מפורטות הודעות שגיאה שקשורות לתוויות ולמגבלות על שמות:

• Field metric.labels had an invalid value of "[KEY]": Label value exceeds the maximum string size of 1024 characters

  • הסיבה: ערך של מדד או של תווית משאב חורג מ-1,024 תווים.
  • פתרון: צריך להגדיר את כלי האיסוף או את האפליקציה כך שיחתכו את ערכי התווית ל-1,024 תווים או פחות. מומלץ להימנע מאחסון טקסט בכמות גדולה בתוויות של מדדים, ולכתוב את הפרטים האלה ב-Cloud Logging במקום זאת.

• Field metric.labels had an invalid value of "[KEY]": Label key contains invalid characters

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

• The metric type must be a URL-formatted string with a domain and non-empty path

  • הסיבה: התבנית metric.type לא תקינה או שחסרה בה קידומת דומיין.
  • רזולוציה: צריך להגדיר את סוגי המדדים המותאמים אישית בפורמט custom.googleapis.com/<category>/<name> או workload.googleapis.com/<name>.

• Field metric.labels had an invalid value: The metric [METRIC_NAME] has more than [LIMIT] labels

  • הסיבה: מספר התוויות בתיאור מדד מותאם אישית חורג מ-30, או חורג מ-200 במקרה של מדדי Prometheus.
  • פתרון: צריך להסיר תוויות מיותרות כדי לא לחרוג ממגבלת התיאורים.

• unrecognized metric label "[LABEL_KEY]"

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

חוסר התאמה בין מזהה הפרויקט למזהה המשאב

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

• Field resource.labels.project_id had an invalid value of "[VAL]": if present, must be the project number or ID in the request name ([PROJECT]) או Field resource.labels.project_id had an invalid value of "[VAL]": if present, must be the resource container ID in the request name [PROJECT]

  • הסיבה: התווית project_id או resource_container שצוינה ב-resource.labels לא תואמת למזהה הפרויקט או למספר הפרויקט בשם הבקשה.
  • פתרון: מגדירים את התווית project_id של המשאב כך שתתאים לפרויקט הבקשה, או משמיטים את התווית project_id מ-resource.labels כדי שהיא תוגדר כברירת מחדל לפרויקט הבקשה.

• unrecognized resource type "[RESOURCE_TYPE]" או missing resource type

  • הסיבה: המדד resource.type לא מזוהה על ידי Cloud Monitoring, או שהוא מושמט כי הוא לא מדד מותאם אישית.
  • פתרון: צריך להשתמש בסוג משאב מפוקח תקין, כמו gce_instance,‏ k8s_container,‏ generic_task או global.

חותמות זמן ומרווחים

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

• Points must be written in order. One or more of the points specified had an older end time than the most recent point

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

• Field points[0].interval.start_time had an invalid value of "[START]": The start time must be equal to the end time ([END]) for the gauge metric '[METRIC]'

  • הסיבה: נשלח GAUGE מדד נקודות שבו start_time לא שווה ל-