‫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 צריכים להיות בתוך מרכאות ולהיות מועברים לתוך הסוגריים המסולסלים. אם שמות התוויות מכילים תווים שלא תואמים לגרסאות קודמות, צריך להוסיף להם מרכאות. למדד Cloud Monitoring‏ kubernetes.io/container/cpu/limit_utilization, השאילתות הבאות שקולות:

  • {"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 שנוספת לשם המדד.

אפשר להשתמש בתוויות מטא-נתונים ב-PromQL בדיוק כמו בכל תוויות אחרות, אבל כמו שמות של מדדים, גם תוויות מטא-נתונים צריכות להיות תואמות ל-PromQL. התחביר להפניה לתווית מערכת של מטא-נתונים version הוא metadata_system_version, והתחביר לתווית משתמש של מטא-נתונים version הוא metadata_user_version. שאילתות PromQL תקינות שמשתמשות בתוויות של מטא-נתונים יכולות להיראות כך:

  • {"compute.googleapis.com/instance/cpu/utilization", monitored_resource="gce_instance",metadata_user_env="prod"}
  • sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_system_region)
  • sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_user_env)
  • {"compute.googleapis.com/instance/uptime_total", "metadata_user_i-love.special/chars"="yes"}
  • sum("compute.googleapis.com/instance/uptime_total") by ("metadata_user_i-love.special/chars")

אם מפתח התווית של המטא-נתונים מכיל תווים מיוחדים שאינם התו _ צריך להוסיף מרכאות כפולות (") למפתח התווית בהתאם למפרט UTF-8 של PromQL. עדיין צריך להוסיף את המחרוזת metadata_user_ כקידומת לתווית המטא-נתונים.

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

גישה ל-PromQL ב-Cloud Monitoring

אפשר להשתמש ב-PromQL בכרטיסייה Code בדפים הבאים במסוף Google Cloud :

  • Metrics Explorer
  • הוספת תרשים כשיוצרים מרכזי בקרה בהתאמה אישית

מידע על גישה לעורך ושימוש בו זמין במאמר שימוש בעורך PromQL.

כללים והתראות ב-PromQL

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

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

למידת PromQL

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

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

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

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

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

  • ב-Metrics Explorer, אפשר לבצע את הפעולות הבאות:

    1. מזינים את שם המדד בשדה Select a metric (בחירת מדד) ואז עוברים בין התפריטים כדי לבחור את המדד. בתפריט המשאבים מופיעים סוגי משאבים תקינים עבור המדד הזה, למשל, VM Instance.

    2. בסרגל הכלים של חלונית בניית השאילתות, לוחצים על הלחצן ששמו < > PromQL.

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

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

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

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

הערך של "" עבור התווית monitored_resource הוא מיוחד ומתייחס לסוג המשאב prometheus_target שמוגדר כברירת מחדל ומשמש למדדים של Cloud Monitoring.

אם לא משתמשים בתווית 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
kubernetes.io/container/cpu/limit_cores kubernetes_io:container_cpu_limit_cores
compute.googleapis.com/instance/cpu/utilization compute_googleapis_com:instance_cpu_utilization
logging.googleapis.com/log_entry_count logging_googleapis_com:log_entry_count
custom.googleapis.com/opencensus/opencensus.io/
http/server/request_count_by_method		 custom_googleapis_com:opencensus_opencensus_io_
http_server_request_count_by_method
agent.googleapis.com/disk/io_time agent_googleapis_com:disk_io_time

אפשר לשלוח שאילתות על מדדים של ערכי התפלגות ב-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 במעלה הזרם.