‫PromQL for Cloud Monitoring

במאמר הזה מוסבר על השימוש בשפת השאילתות של Prometheus‏ (PromQL) ב-Cloud Monitoring. ‫PromQL מספקת חלופה לממשק מבוסס התפריטים של Metrics Explorer ליצירת תרשימים ולוחות בקרה.

אפשר להשתמש ב-PromQL כדי לשלוח שאילתות על נתוני Cloud Monitoring מהמקורות הבאים וליצור תרשימים שלהם:

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

אפשר גם לייבא את מרכזי הבקרה של Grafana אל Cloud Monitoring.

שליחת שאילתות על מדדי Cloud Monitoring באמצעות PromQL

אפשר לשלוח שאילתות על מדדי Cloud Monitoring באמצעות מפרט UTF-8 ל-PromQL. שמות של מדדים בקידוד UTF-8 צריכים להיות בתוך מרכאות ובתוך הסוגריים המסולסלים. אם שמות התוויות מכילים תווים שלא תואמים לגרסאות קודמות, צריך להוסיף להם גם מרכאות. השאילתות הבאות שקולות למדד kubernetes.io/container/cpu/limit_utilization ב-Cloud Monitoring:

  • {"kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}
  • {__name__="kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}.
  • {"__name__"="kubernetes.io/container/cpu/limit_utilization", "pod_name"="foo"}.

אפשר לשלוח שאילתות על מדדים של ערכי התפלגות ב-Cloud Monitoring כמו על היסטוגרמות של Prometheus, עם הסיומת _count, _sum או _bucket שנוספת לשם המדד.

תרשימים ולוחות בקרה שנוצרו לפני התאימות ל-UTF-8 שולחים שאילתות למדדים של Cloud Monitoring על ידי המרה של השמות שלהם למקבילות תואמות ל-PromQL מדור קודם. מידע נוסף על כללי המרה של PromQL מדור קודם זמין במאמר מיפוי מדדים של Cloud Monitoring ל-PromQL מדור קודם.

למידת PromQL

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

ציון סוג של משאב במעקב

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

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

אם מדד משויך ליותר מסוג משאב אחד, צריך לציין את סוג המשאב בשאילתת PromQL. יש תווית מיוחדת, monitored_resource, שאפשר להשתמש בה כדי לבחור את סוג המשאב.

סוגי משאבים שבמעקב הם ברוב המקרים מחרוזת קצרה, כמו gce_instance, אבל לפעמים הם מופיעים כמזהי URI מלאים, כמו monitoring.googleapis.com/MetricIngestionAttribution. דוגמאות לשאילתות PromQL תקינות:

  • logging_googleapis_com:byte_count{monitored_resource="k8s_container"}
  • loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

אם לא משתמשים בתווית monitored_resource כשצריך, מקבלים את השגיאה הבאה:

metric is configured to be used with more than one monitored resource type; series selector must specify a label matcher on monitored resource name

פתרון בעיות שקשורות לתוויות

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

לדוגמה, נניח שיש לכם תווית משאב ותווית מדד ששתיהן נקראות pod_name במדד example.googleapis.com/user/widget_count.

  • כדי לסנן לפי הערך של תווית המשאב, משתמשים ב-
    example_googleapis_com:user_widget_count{pod_name="RESOURCE_LABEL_VALUE"}

  • כדי לסנן לפי הערך של תווית המדד, משתמשים בפונקציה
    example_googleapis_com:user_widget_count{metric_pod_name="METRIC_LABEL_VALUE"}

מיפוי של שמות מדדים ב-Cloud Monitoring ל-PromQL מדור קודם

שמות המדדים ב-Cloud Monitoring כוללים שני רכיבים: דומיין (כמו compute.googleapis.com/) ונתיב (כמו instance/disk/max_read_ops_count). מכיוון ש-PromQL מדור קודם תומך רק בתווים המיוחדים : ו-_, צריך להחיל את הכללים הבאים כדי ששמות המדדים ב-Monitoring יהיו תואמים ל-PromQL מדור קודם:

  • מחליפים את / הראשון ב-:.
  • מחליפים את כל התווים המיוחדים האחרים (כולל . ותווים אחרים של / ) ב-_.

בטבלה הבאה מפורטים כמה שמות של מדדים והמקבילים שלהם ב-PromQL מדור קודם:

שם המדד ב-Cloud Monitoring שם מדד מדור קודם ב-PromQL
compute.googleapis.com/instance/cpu/utilization compute_googleapis_com:instance_cpu_utilization
logging.googleapis.com/log_entry_count logging_googleapis_com:log_entry_count

אפשר לשלוח שאילתות על מדדים של ערכי התפלגות ב-Cloud Monitoring כמו על היסטוגרמות של Prometheus, עם הסיומת _count,‏ _sum או _bucket שנוספת לשם המדד:

שם המדד ב-Cloud Monitoring שמות מדדים בגרסה הקודמת של PromQL
networking.googleapis.com/vm_flow/rtt networking_googleapis_com:vm_flow_rtt_sum
networking_googleapis_com:vm_flow_rtt_count
networking_googleapis_com:vm_flow_rtt_bucket

תאימות ל-PromQL

יכול להיות ש-PromQL ל-Cloud Monitoring יפעל בצורה שונה מעט מ-PromQL במעלה הזרם.

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

יכול להיות שלא תהיה תמיכה בפונקציות PromQL שנוספו אחרי גרסה 2.44 של Prometheus.

תמיכה ב-UTF-8

‫PromQL for Cloud Monitoring תומך בשאילתות UTF-8.

אם שם המדד של Prometheus כולל רק תווים אלפאנומריים בתוספת התווים _ או :, ואם מפתחות התווית כוללים רק תווים אלפאנומריים בתוספת התו _, אפשר להריץ שאילתות באמצעות תחביר PromQL רגיל. לדוגמה, שאילתה תקינה יכולה להיראות כך: job:my_metric:sum{label_key="label_value"}.

עם זאת, אם שם המדד של Prometheus כולל תווים מיוחדים כלשהם מלבד התווים _ או :, או אם מפתחות התוויות כוללים תווים מיוחדים כלשהם מלבד התו _, צריך ליצור את השאילתה בהתאם למפרט UTF-8 עבור PromQL.

שמות של מדדים בקידוד UTF-8 צריכים להיות במירכאות ולהיות מוזזים לתוך הסוגריים המסולסלים. צריך להוסיף מרכאות גם לשמות של תוויות אם הם מכילים תווים שלא תואמים לגרסאות קודמות. הדוגמאות הבאות לשאילתות חוקיות הן שקולות:

  • {"my.domain.com/metric/name_bucket", "label.key"="label.value"}
  • {__name__="my.domain.com/metric/name_bucket", "label.key"="label.value"}
  • {"__name__"="my.domain.com/metric/name_bucket", "label.key"="label.value"}

התאמה לפי שמות של מדדים

יש תמיכה רק בהתאמה מדויקת של שמות המדדים. צריך לכלול התאמה מדויקת של שם המדד בשאילתה.

אנחנו ממליצים על הפתרונות הבאים לתרחישים נפוצים שבהם נעשה שימוש בהתאמה של ביטוי רגולרי בתווית __name__:

  • בדרך כלל משתמשים באופרטור =~ בהגדרות של Prometheus adapter כדי להתאים לכמה שמות של מדדים. כדי לתקן את השימוש הזה, צריך להרחיב את ההגדרה כך שתשתמש במדיניות נפרדת לכל מדד, ולתת שם לכל מדד באופן מפורש. בנוסף, כך אפשר למנוע התאמה אוטומטית לעומס בטעות על סמך מדדים לא צפויים.
  • לרוב משתמשים בביטויים רגולריים כדי להציג בתרשים כמה מדדים לא ממדיים. לדוגמה, אם יש לכם מדד כמו cpu_servicename_usage, תוכלו להשתמש בתו כללי כדי ליצור תרשים של כל השירותים שלכם יחד. שימוש במדדים לא ממדיים כמו אלה הוא שיטה פסולה ב-Cloud Monitoring, והוא מוביל לביצועים גרועים במיוחד של השאילתות. כדי לתקן את השימוש הזה, צריך להעביר את כל המאפיינים לתוויות של המדדים במקום להטמיע אותם בשם המדד.
  • לעתים קרובות משתמשים בשאילתות על כמה מדדים כדי לראות אילו מדדים זמינים לשאילתה. במקום זאת, מומלץ להשתמש בקריאה /labels/__name__/values כדי לגלות מדדים. אפשר גם לגלות מדדים באמצעות ממשק המשתמש של Cloud Monitoring.
  • התאמה של כמה מדדים שימושית כדי לראות כמה דוגמאות נסרקו, נבלעו וחויבו על בסיס כל מדד. המידע הזה מוצג ב-Cloud Monitoring בדף Metrics Management. אפשר גם לגשת למידע הזה כנתוני מדדים באמצעות המדד Samples Ingested (דגימות שהועברו) או המדד Samples Written by Attribution ID (דגימות שנכתבו לפי מזהה שיוך).

לא פעיל

אין תמיכה בנתונים לא עדכניים בשרת העורפי של Monarch.

חישוב של irate

אם חלון מבט לאחור של הפונקציה irate קטן מגודל השלב, אנחנו מגדילים את החלון לגודל השלב. השינוי הזה נדרש ב-Monarch כדי להבטיח שאף אחד מנתוני הקלט לא יתעלם לחלוטין בפלט. ההבדל הזה רלוונטי גם לחישובים של rate.

חישוב של rate ושל increase

אם חלון מבט לאחור של הפונקציה rate קטן מגודל השלב, אנחנו מגדילים את החלון לגודל השלב. השינוי הזה נדרש ב-Monarch כדי לוודא שאף אחד מנתוני הקלט לא יתעלם לחלוטין בפלט. ההבדל הזה רלוונטי גם לחישובים של irate.

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

חישוב של histogram_quantile

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

ההבדלים בחישוב השערים יכולים להשפיע גם על הקלט של שאילתות histogram_quantile.

פונקציות ספציפיות לסוגים של מדדים עם סוגים שונים

למרות ש-Prometheus במעלה הזרם הוא בעל הקלדה חלשה, Monarch הוא בעל הקלדה חזקה. המשמעות היא שאי אפשר להפעיל פונקציות שספציפיות לסוג אחד על מדד מסוג אחר (לדוגמה, הפעלת rate() על מדד GAUGE או histogram_quantile() על מדד COUNTER או על מדד ללא סוג) ב-Cloud Monitoring, גם אם הפונקציות האלה פועלות ב-Prometheus במעלה הזרם.