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

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

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

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

תוכן

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

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

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

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

Cloud Monitoring API

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

מסוף Google Cloud

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

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

  • אימייל, בקטע Policy Documentation
  • 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}.
  • כדי לכלול את המחרוזת המילולית ${ בתיעוד, צריך להוסיף תו בריחה (escape) לסמל $ עם סמל $ נוסף, ואז $${ מוצג כ-${ בתיעוד.
  • במדיניות ההתראות תמיד מוצגות מחרוזות משתנים כמו ${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 גרסה 1.2
    • ‫PagerDuty, סכימת JSON גרסה 1.2
  • תצוגת פרטי ההתראה Google Cloud במסוף.

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

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

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

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

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

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

דוגמה

בדוגמה הבאה מוצגות גרסאות של מסוף Google Cloud ושל 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"
      }
    ]
  }

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

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

מסוף 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

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

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