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

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

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

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

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

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

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

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

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

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

דוגמה

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

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

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

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

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

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