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

• ‫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,המערכת מבצעת אימות כדי לוודא שהמדדים שאליהם יש הפניה בתנאי כבר קיימים ב-Monitoring. Google Cloudעם זאת, אפשר לבטל את האימות הזה אם רוצים ליצור מדיניות להתראות לפני שהמדדים קיימים. לדוגמה, יכול להיות שתרצו לעשות זאת כשאתם משתמשים באוטומציה כדי ליצור פרויקטים חדשים שמגיעים עם קבוצה סטנדרטית של מדיניות התראות מוגדרת מראש. אם לא משביתים את האימות, יצירת מדיניות ההתראות תיכשל עד ליצירת המדדים הבסיסיים.

כדי להשבית את הבדיקה של קיום המדד, מוסיפים את השדה "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 של מאגר Terraform‏ google_monitoring_alert_policy.

מידע כללי על שימוש ב- 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. מאמתים את הזהות ב-Google Cloud CLI:

   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....