הוספת הערות להודעות עם תיעוד שהוגדר על ידי המשתמש

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

מבנה מאמרי העזרה

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

נושאים

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

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

Cloud Monitoring API

מגדירים את שורת הנושא של ההתראה באמצעות השדה subject של מדיניות ההתראות documentation.

מסוף Google Cloud

מגדירים את שורת הנושא של ההתראה באמצעות השדה Notification subject line בקטע Notifications and name בדף Create alerting policy.

תוכן

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

  • אימייל, בקטע מסמכי מדיניות
  • PagerDuty
  • Pub/Sub
  • Slack
  • תגובות לפעולה מאתר אחר (webhook)

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

התוכן של המסמכים תומך באפשרויות הבאות:

Cloud Monitoring API

מגדירים את תוכן התיעוד באמצעות השדה content של מדיניות ההתראות documentation.

מסוף Google Cloud

מגדירים את תוכן התיעוד באמצעות השדה Documentation בקטע Notifications and name בדף Create alerting policy.

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

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

Cloud Monitoring API

כדי להוסיף קישורים לתיעוד, צריך להגדיר אובייקט Link אחד או יותר בשדה links של מדיניות ההתראות documentation. כל אובייקט Link מורכב מdisplay_name ומurl. אפשר להוסיף עד שלושה קישורים למסמכים.

ההגדרה הבאה מציגה את השדה links עם אובייקט Link אחד שמייצג כתובת URL של תוכנית פעולה לאירוע. כתובת ה-URL כוללת משתנה כדי שנמעני ההתראה יוכלו לגשת למדריך הנכון בהתאם למשאב שבמעקב שבו התרחש האירוע:

"links" [
  {
    "displayName": "Playbook",
    "url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
  }
]

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

  • אימייל, בקטע קישורים מהירים
  • PagerDuty
  • Pub/Sub
  • תגובות לפעולה מאתר אחר (webhook)

מסוף Google Cloud

אפשר להוסיף קישורים לתוכן התיעוד על ידי הוספתם לשדה Documentation במדיניות ההתראות. לדוגמה, במסמכי התיעוד הבאים מופיעה כתובת URL של מדריך הפעלה ללקוחות:

### Troubleshooting and Debug References

Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}

קישורים למסמכים שנוספו באמצעות המסוף Google Cloud מופיעים עם שאר התוכן של המסמכים בסוגי ההתראות הבאים:

  • אימייל, בקטע מסמכי מדיניות
  • PagerDuty
  • Pub/Sub
  • Slack
  • תגובות לפעולה מאתר אחר (webhook)

‫Markdown בתוכן של מסמכי תיעוד

אתם יכולים להשתמש ב-Markdown כדי לעצב את התוכן של התיעוד. תוכן התיעוד תומך בקבוצת המשנה הבאה של תגי Markdown:

  • כותרות, שמסומנות באמצעות תווי סולמית בתחילת השורה.
  • רשימות לא מסודרות, שמסומנות בתווי פלוס, מינוס או כוכבית בהתחלה.
  • רשימות ממוספרות, שמסומנות במספר התחלתי ואחריו נקודה.
  • טקסט נטוי, שמסומן על ידי קו תחתון יחיד או כוכבית יחידה מסביב לביטוי.
  • טקסט מודגש, שמסומן בשני קווים תחתונים או בשתי כוכביות סביב הביטוי.
  • קישורים, שמסומנים בתחביר [link text](url). כדי להוסיף קישורים להתראה, מומלץ להשתמש ב-Cloud Monitoring API ולהגדיר את האובייקט Link.

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

משתנים במאמרי עזרה

כדי להתאים אישית את הטקסט במסמכים, אפשר להשתמש במשתנים מהצורה ${varname}. כשמסמכים נשלחים עם התראה, המחרוזת ${varname} מוחלפת בערך שנלקח מהמשאב המתאים Google Cloud , כפי שמתואר בטבלה הבאה.

משתנה ערך
condition.name שם משאב ה-REST של התנאי, למשל
projects/foo/alertPolicies/1234/conditions/5678.
condition.display_name השם המוצג של תנאי, למשל CPU usage increasing rapidly.
log.extracted_label.KEY הערך של התווית KEY, שחולץ מתוך רשומה ביומן. רק למדיניות התראות מבוססת-יומן. מידע נוסף זמין במאמר יצירת מדיניות התראות מבוססת-יומן באמצעות Monitoring API.
metadata.system_label.KEY הערך של תווית המטא-נתונים של המשאב שסופקה על ידי המערכת KEY.1
metadata.user_label.KEY הערך של תווית המטא-נתונים של המשאב שהוגדרה על ידי המשתמש KEY.1,3
metric.type סוג המדד, למשל
compute.googleapis.com/instance/cpu/utilization.
metric.display_name השם המוצג של סוג המדד, למשל CPU utilization.
metric.label.KEY

הערך של תווית המדד KEY.1
כדי למצוא את התוויות שמשויכות לסוג המדד, אפשר לעיין ברשימת המדדים.

אם הערך של המשתנה ${metric.label.KEY} לא מתחיל בספרה, באות, בקו נטוי (/) או בסימן שווה (=), המערכת של Monitoring לא תכלול את התווית בהתראות.

כשמעבירים כלל התראה של Prometheus, תבניות השדות של ההתראה של Prometheus‏ {{$value}} ו-{{humanize $value}} מופיעות כ-${metric.label.value} בהגדרת מדיניות ההתראות. במקרה הזה, ${metric.label.value} מכיל את ערך הטריגר של כלל ההתראות של Prometheus.

אפשר גם להשתמש ב-${metric.label.value} כשיוצרים שאילתות PromQL ב- Google Cloud.
metric.label.metadata_system_VALUE

מפנה לתווית מערכת של מטא נתונים ב-PromQL, כאשר VALUE הוא שם התווית הספציפי, כמו region או version.

דוגמה לשימוש: ${metric.label.metadata_system_version}.
metric.label.metadata_user_VALUE

מפנה לתווית משתמש של מטא-נתונים ב-PromQL, כאשר VALUE הוא שם התווית הספציפי, כמו region או name.

דוגמה לשימוש: ${metric.label.metadata_user_name}.
metric_or_resource.labels

המשתנה הזה מעבד את כל ערכי התוויות של המדדים והמשאבים כרשימה ממוינת של צמדי key-value. אם לתווית מדד ולתווית משאב יש את אותו השם, רק תווית המדד תוצג.

כשמעבירים כלל התראה של Prometheus, תבניות השדות של ההתראה של Prometheus‏ {{$labels}} ו-{{humanize $labels}} מופיעות כ-${metric_or_resource.labels} בהגדרת מדיניות ההתראות במסמכי התיעוד.
metric_or_resource.label.KEY
  • אם KEY היא תווית תקינה, המשתנה הזה מוצג בהתראה כערך של ${metric.label.KEY}.
  • אם KEY הוא משאב תקין, המשתנה הזה מוצג בהתראה כערך של ${resource.label.KEY}.
  • אם KEY הוא לא תווית ולא משאב תקינים, המשתנה הזה יוצג בהתראה כמחרוזת ריקה.

כשמעבירים כלל התראה של Prometheus, תבניות השדות של ההתראה של Prometheus‏ {{$labels.KEY}} ו-{{humanize $labels.KEY}} מופיעות כ-${metric_or_resource.labels.KEY} בהגדרות של מסמכי מדיניות ההתראות.
policy.name שם המשאב של המדיניות ב-REST, למשל projects/foo/alertPolicies/1234.
policy.display_name השם המוצג של המדיניות, למשל High CPU rate of change.
policy.user_label.KEY הערך של תווית המשתמש KEY.1

המפתחות צריכים להתחיל באות קטנה. המפתחות והערכים יכולים להכיל רק אותיות קטנות, ספרות, קווים תחתונים ומקפים.
project המזהה של פרויקט ההיקף של היקף המדדים, למשל a-gcp-project.
resource.type סוג המשאב המנוטר, כמו gce_instance.
resource.project מזהה הפרויקט של המשאב המפוקח של מדיניות ההתראות.
resource.label.KEY הערך של תווית המשאב KEY.1,2,3
כדי למצוא את התוויות שמשויכות לסוג המשאב במעקב, אפשר לעיין ברשימת המשאבים.

‫1 לדוגמה, ${resource.label.zone} מוחלף בערך של התווית zone. הערכים של המשתנים האלה כפופים לקיבוץ. מידע נוסף זמין במאמר ערכי null.‫
 ‫2 כדי לאחזר את הערך של התווית project_id במשאב שבמעקב במדיניות ההתראות, משתמשים ב-${resource.project}.
 ‫3 אי אפשר לגשת לתוויות מטא-נתונים של משאבים שהוגדרו על ידי המשתמש באמצעות resource.label.KEY.. צריך להשתמש ב-metadata.user_label.KEY במקום זאת.

הערות שימוש

  • יש תמיכה רק במשתנים שבטבלה. אי אפשר לשלב אותם בביטויים מורכבים יותר, כמו ${varname1 + varname2}.
  • כדי לכלול את המחרוזת המילולית ${ בתיעוד, צריך להוסיף תו בריחה (escape) לסמל $ באמצעות סמל $ נוסף, ואז $${ יוצג כ-${ בתיעוד.
  • המשתנים האלה מוחלפים בערכים שלהם רק בהתראות שנשלחות דרך ערוצי התראות. במסוף Google Cloud , כשמוצגת התיעוד, רואים את המשתנים ולא את הערכים. דוגמאות במסוף כוללות את תיאורי האירועים ותצוגה מקדימה של התיעוד כשיוצרים מדיניות התראות.
  • מוודאים שהגדרות הצבירה של התנאי לא מבטלות את התווית. אם התווית נמחקת, הערך של התווית בהתראה הוא null. מידע נוסף זמין במאמר משתנה של תווית מדד הוא null.

ערכים של null

הערכים של המשתנים metric.*, resource.* ו-metadata.* נגזרים מסדרות עיתיות. הערכים שלהם יכולים להיות null אם לא מוחזרים ערכים משאילתת סדרת הזמן.

  • המשתנים resource.label.KEY ו-metric.label.KEY יכולים לקבל ערכים של null אם מדיניות ההתראות שלכם משתמשת בצבירה (צמצום) של נתונים מסדרות שונות, למשל, חישוב הסכום של כל סדרות הזמן שתואמות למסנן. כשמשתמשים בצבירה של נתונים מסדרות שונות, כל התוויות שלא משמשות לקיבוץ נמחקות, וכתוצאה מכך הן מוצגות כ-null כשמחליפים את המשתנה בערך שלו. כל התוויות נשמרות כשאין צבירה בין סדרות. מידע נוסף זמין במאמר משתנה של תווית מדד הוא null.

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

רזולוציה משתנה

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

  • אימייל
  • Google Chat
  • Slack
  • ‫Pub/Sub, גרסה 1.2 של סכימת JSON
  • Webhooks, JSON schema version 1.2
  • ‫PagerDuty, גרסה 1.2 של סכימת JSON

אמצעי בקרה בערוץ

הטקסט בשדה התיעוד יכול לכלול גם תווים מיוחדים שמשמשים את ערוץ ההתראות עצמו כדי לשלוט בעיצוב ובהתראות.

לדוגמה, ב-Slack נעשה שימוש ב-@ לתיוגים. אפשר להשתמש ב-@ כדי לקשר את ההתראה למזהה משתמש ספציפי. אי אפשר לתייג אנשים בשם. נניח שאתם כוללים מחרוזת כזו בשדה התיעוד:

<@backendoncall> Incident created based on policy ${policy.display_name}

כששדה התיעוד מתקבל בערוץ הרלוונטי ב-Slack כחלק מההתראה, המחרוזת הקודמת גורמת ל-Slack לשלוח הודעה נוספת למזהה המשתמש backendoncall. ההודעה שנשלחת מהתראה ב-Slack למשתמש יכולה להכיל מידע רלוונטי מההתראה. לדוגמה: 'נוצר אירוע על סמך מדיניות: שיעור שינוי גבוה של CPU'.

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

דוגמה

בדוגמה הבאה מוצגות גרסאות של מסוף ושל Cloud Monitoring API של תיעוד תבנית למדיניות התראות על ניצול CPU. Google Cloud בדוגמאות האלה אנחנו משתמשים באימייל בתור סוג ערוץ ההתראות. תבניות התיעוד כוללות כמה משתנים לסיכום האירוע ולהפניה למשאבי REST של מדיניות ההתראות והתנאים.

Cloud Monitoring API 

  "documentation": {
    "content": "### CPU utilization exceeded\n\n### Summary\n\nThe ${metric.display_name} of the ${resource.type} ${resource.label.instance_id} in the project ${resource.project} has exceeded 5% for over 60 seconds.\n\n#### Additional resource information\n\nCondition resource name: ${condition.name}  \nAlerting policy resource name: ${policy.name}",
    "mimeType": "text/markdown",
    "subject": "Alert: ${metric.display_name} exceeded",
    "links": [
      {
        "displayName": "Playbook",
        "url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
      },
      {
        "displayName": "Repository with debug scripts",
        "url": "https://altostrat.com"
      },
      {
        "displayName": "Google Cloud dashboard",
        "url": "https://example.com"
      }
    ]
  }

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

דוגמה לאופן שבו תיעוד מוצג בהתראה. הקישורים מוצגים בקטע &#39;קישורים מהירים&#39;.

מסוף Google Cloud 

### CPU utilization exceeded

#### Summary

The ${metric.display_name} of the ${resource.type}
${resource.label.instance_id} in the project ${resource.project} has
exceeded 5% for over 60 seconds.

#### Additional resource information

Condition resource name: ${condition.name}  
Alerting policy resource name: ${policy.name}  

#### Troubleshooting and Debug References

Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}  
Repository with debug scripts: https://altostrat.com  
${resource.type} dashboard: https://example.com

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

דוגמה לאופן שבו תיעוד מוצג בהתראה. הקישורים מוצגים מתחת לכותרת &#39;חומר עזר לפתרון בעיות ולניפוי באגים&#39;.