יצירת מדיניות התראות מבוססת-PromQL‏ (API)

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

מידע כללי מופיע במאמר סקירה כללית על התראות שמבוססות על PromQL.

אם אתם עובדים בסביבת Prometheus מחוץ ל-Cloud Monitoring ויש לכם כללי התראות של Prometheus, אתם יכולים להשתמש ב-Google Cloud CLI כדי להעביר אותם למדיניות התראות מבוססת-PromQL ב-Monitoring. מידע נוסף זמין במאמר בנושא העברה של כללי התראות ומקבלים מ-Prometheus.

יצירת כללי מדיניות התראות באמצעות שאילתות PromQL

משתמשים ב-method‏ alertPolicies.create כדי ליצור כללי מדיניות התראות באופן פרוגרמטי.

ההבדל היחיד בין יצירת מדיניות התראות שמבוססת על PromQL לבין יצירת מדיניות התראות אחרת הוא שסוג Condition צריך להיות PrometheusQueryLanguageCondition. סוג התנאי הזה מאפשר להגדיר מדיניות התראות באמצעות PromQL.

בדוגמה הבאה מוצגת שאילתת PromQL לתנאי של מדיניות התראות שמשתמשת במדד מהכלי kube-state לייצוא נתונים כדי למצוא את מספר הפעמים שבהן קונטיינר הופעל מחדש ב-30 הדקות האחרונות:

rate(kube_pod_container_status_restarts[30m]) * 1800 > 1

יצירת מדיניות התראות

כדי ליצור מדיניות התראות מבוססת-PromQL, משתמשים בAlertPolicy סוג התנאי PrometheusQueryLanguageCondition. ל-PrometheusQueryLanguageCondition יש את המבנה הבא:

{
  "query": string,
  "duration": string,
  "evaluationInterval": string,
  "labels": {string: string},
  "ruleGroup": string,
  "alertRule": string
}

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

ההגדרות של השדות PrometheusQueryLanguageCondition הן:

• ‫query: ביטוי PromQL להערכה. שווה ערך לשדה expr מכלל התראות רגיל של Prometheus.
• ‫duration: מציין את משך הזמן שבמהלכו כל הערכה של השאילתה צריכה ליצור ערך של true לפני שהתנאי של מדיניות ההתראות מתקיים. הערך חייב להיות מספר של דקות, שמוצג בשניות. לדוגמה, 600s לפרק זמן של 10 דקות. מידע נוסף זמין במאמר בנושא התנהגות של כללי מדיניות להתראות שמבוססים על מדדים.

• ‫evaluationInterval: מרווח הזמן בשניות בין הערכות של השאילתה ב-PromQL. ערך ברירת המחדל הוא 30 שניות. אם ה-PrometheusQueryLanguageCondition נוצר על ידי העברה של כלל התראות של Prometheus, הערך הזה מגיע מקבוצת הכללים של Prometheus שהכילה את כלל ההתראות של Prometheus.

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

• ‫labels: דרך אופציונלית להוסיף או להחליף תוויות בתוצאה של ביטוי PromQL.

• ‫ruleGroup: אם מדיניות ההתראות הועברה מקובץ הגדרות של Prometheus, השדה הזה מכיל את הערך של השדה name מתוך קבוצת הכללים בקובץ ההגדרות של Prometheus. לא צריך למלא את השדה הזה כשיוצרים מדיניות התראות של PromQL ב-Cloud Monitoring API.

• ‫alertRule: אם מדיניות ההתראות הועברה מקובץ הגדרות של Prometheus, השדה הזה מכיל את הערך של השדה alert מכלל ההתראה בקובץ ההגדרות של Prometheus. לא צריך למלא את השדה הזה כשיוצרים מדיניות התראות של PromQL ב-Cloud Monitoring API.

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

"conditionPrometheusQueryLanguage": {
  "query": "rate(kube_pod_container_status_restarts[30m]) * 1800 > 1",
  "duration": "600s",
  "evaluationInterval": "60s",
  "alertRule": "ContainerRestartCount",
  "labels": {
    "action_required":"true",
    "severity":"critical/warning/info"}
}

משתמשים במבנה הזה כערך של שדה conditionPrometheusQueryLanguage בתנאי, שמוטמע במבנה של מדיניות התראות. מידע נוסף על המבנים האלה זמין במאמר AlertPolicy.

בדוגמה הבאה מוצגת מדיניות מלאה עם PrometheusQueryLanguageConditionתנאי בפורמט JSON:

הערה: בשדה documentation בדוגמה הבאה נעשה שימוש במשתני מסמך.

{
  "displayName": "Container Restarts",
  "documentation": {
    "content": "Pod ${resource.label.namespace_name}/${resource.label.pod_name} has restarted more than once during the last 30 minutes.",
    "mimeType": "text/markdown",
    "subject": "Container ${resource.label.container_name} in Pod ${resource.label.namespace_name}/${resource.label.pod_name} has restarted more than once during the last 30 minutes."
  },
  "userLabels": {},
  "conditions": [
    {
      "displayName": "Container has restarted",
      "conditionPrometheusQueryLanguage": {
        "query": "rate(kubernetes_io:container_restart_count[30m]) * 1800",
        "duration": "600s",
        "evaluationInterval": "60s",
        "alertRule": "ContainerRestart",
        "labels": {
          "action_required":"true",
          "severity":"critical/warning/info"}
      }
    }
  ],
  "combiner": "OR",
  "enabled": true
}

יצירת מדיניות התראות

כדי ליצור את מדיניות ההתראות, מכניסים את ה-JSON של מדיניות ההתראות לקובץ בשם POLICY_NAME.json, ואז מריצים את הפקודה הבאה:

curl -d @POLICY_NAME.json -H "Authorization: Bearer $TOKEN"
-H 'Content-Type: application/json'
-X POST https://monitoring.googleapis.com/v3/projects/${PROJECT}/alertPolicies

מידע נוסף על Monitoring API למדיניות התראות זמין במאמר ניהול מדיניות התראות באמצעות API.

מידע נוסף על השימוש ב-curl זמין במאמר בנושא הפעלת curl.

השבתה של בדיקת קיום המדד

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

כדי להשבית את הבדיקה של קיום המדד, מוסיפים את השדה "disableMetricValidation": true אל PrometheusQueryLanguageCondition:

{
  "query": string,
  "duration": string,
  "evaluationInterval": string,
  "labels": {string: string},
  "ruleGroup": string,
  "disableMetricValidation": true,
  "alertRule": string
}

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

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

שימוש ב-Terraform

הוראות להגדרת מדיניות התראות מבוססת PromQL באמצעות Terraform מופיעות בקטע condition_prometheus_query_language במאגר google_monitoring_alert_policy Terraform.

מידע כללי על שימוש ב- Google Cloud עם Terraform זמין במאמר Terraform עם Google Cloud.

הפעולה curl מבוצעת

כל הפעלה של curl כוללת קבוצה של ארגומנטים, ואחריה כתובת ה-URL של משאב API. הארגומנטים הנפוצים כוללים מזהה פרויקט Google Cloud ואסימון אימות. הערכים האלה מיוצגים כאן על ידי משתני הסביבה PROJECT_ID ו-TOKEN.

יכול להיות שתצטרכו לציין גם ארגומנטים אחרים, למשל כדי לציין את סוג בקשת ה-HTTP (לדוגמה, -X DELETE). בקשת ברירת המחדל היא GET, ולכן לא מצוין סוג הבקשה בדוגמאות.

לכל קריאה של curl יש את המבנה הכללי הזה:

curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

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

כדי להגדיר את המשתנים האלה:

1. יוצרים משתנה סביבה שיכיל את המזהה של פרויקט ההיקף של היקף המדדים. בשלבים הבאים מוגדר המשתנה PROJECT_ID:

   PROJECT_ID=a-sample-project
   

2. מאמתים את ה-CLI של Google Cloud:

   gcloud auth login
   

3. זה שינוי אופציונלי. כדי שלא תצטרכו לציין את מזהה הפרויקט בכל פקודת gcloud, אתם יכולים להגדיר את מזהה הפרויקט כברירת מחדל באמצעות ה-CLI של gcloud:

   gcloud config set project ${PROJECT_ID}
   

4. יוצרים אסימון הרשאה ושומרים אותו במשתנה סביבה. בשלבים הבאים מוגדר המשתנה TOKEN:

   TOKEN=`gcloud auth print-access-token`
   

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

5. כדי לוודא שקיבלתם אסימון גישה, מריצים את הפקודה הבאה:TOKEN

   echo ${TOKEN}
   ya29.GluiBj8o....