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

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

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

התיעוד של מדיניות התראות מורכב מנושא, תוכן וקישורים. אפשר להגדיר תיעוד במסוף 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

מגדירים את תוכן התיעוד באמצעות השדה תיעוד בקטע התראות ושם בדף יצירת מדיניות התראות.

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

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

במדיניות התראות מבוססת-יומנים שיוצרים באמצעות Logs Explorer, הערך של השדה הזה הוא "Log match condition". כדי להתאים אישית את הערך של השדה הזה, צריך להשתמש ב-Cloud Monitoring API.
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}.
  • כדי לכלול את המחרוזת המילולית ${ בתיעוד, צריך להוסיף תו בריחה לסמל $ באמצעות סמל $ נוסף, ואז $${ יוצג כ-${ בתיעוד.
  • במדיניות ההתראות תמיד מוצגים מחרוזות משתנות כמו ${varname}.
  • בערוצים מסוימים של התראות, Cloud Monitoring מחליף מחרוזות משתנות כמו ${varname} בערכים המתאימים. מידע נוסף מופיע במאמר Variable resolution.
  • כשמוצג במסוף Google Cloud תצוגת הפרטים של אירוע, בדרך כלל מחרוזות משתנות כמו ${varname} מוחלפות בערכים המתאימים.
  • מוודאים שהגדרות הצבירה של התנאי לא מבטלות את התווית. אם התווית נמחקת, הערך של התווית בהתראה הוא 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, ‏ JSON schema version 1.2
  • תצוגת הפרטים של האירוע במסוף Google Cloud .

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

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

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

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

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

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

דוגמה

בדוגמה הבאה מוצגות גרסאות של מסמכי תבנית של מדיניות התראות על ניצול CPU, בפורמט של מסוף ושל Cloud Monitoring API. 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;.