‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

הגדרת מדיניות התראות שמבוססת על יומנים

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

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

בדף הזה לא מוסבר איך ליצור או לנהל מדיניות התראות שעוקבת אחרי נתונים של מדדים – כולל מדדים שמבוססים על יומנים – או אחרי תוצאות של שאילתות SQL.

לפני שמתחילים

מוודאים שהחיוב מופעל בפרויקט Google Cloud .
מומלץ לעיין בהשוואה בין התראות כדי להבין אם מדיניות התראות שמבוססת על יומנים מתאימה לנתונים ביומנים שלכם. לדוגמה:
- מדיניות התראות שמבוססת על יומנים לא פועלת על יומנים מוחרגים.
- אי אפשר להשתמש במדיניות התראות שמבוססת על יומנים כדי להפיק ספירות מהיומנים. כדי לקבל ספירות, צריך להשתמש במקום זאת במדדים מבוססי-יומן.
כדי ליצור ולנהל מדיניות התראות שמבוססת על יומנים, התפקיד שלכם בניהול זהויות והרשאות גישה (IAM) צריך לכלול את ההרשאות שמתוארות במאמר הרשאות למדיניות התראות שמבוססת על יומנים.

יצירת מדיניות התראות מבוססת-יומן באמצעות Logs Explorer

התוכן בקטע הזה רלוונטי רק למדיניות התראות שמבוססת על יומנים. ההגדרה הזו לא רלוונטית למדיניות התראות שעוקבת אחרי נתוני מדדים – כולל מדדים שמבוססים על יומנים – או אחרי תוצאות של שאילתות SQL.

אפשר ליצור מדיניות התראות מבוססת-יומנים מהדף Logs Explorer במסוף Google Cloud או באמצעות Monitoring API. בקטע הזה מוסבר איך ליצור כללי מדיניות התראות מבוססי-יומנים באמצעות Logs Explorer. מידע על Monitoring API מופיע במאמר יצירת מדיניות התראות מבוססת-יומן באמצעות Monitoring API.

מדיניות התראות שמבוססת על יומנים לא מתחשבת בהגדרת ההיקף בדף Logs Explorer. במקום זאת, כשמאגר ברמת הפרויקט מעביר רשומה ביומן שמקורה בפרויקט למאגר יומנים, מדיניות ההתראות שמבוססת על יומנים ומוגדרת בפרויקט הזה סורקת את הרשומה ביומן. מידע נוסף זמין במאמר בנושא רשומות יומן זמינות.

ממשק Logs Explorer מנחה אתכם בשלבים הבאים:

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

לדוגמה, נניח שיש לכם אפליקציה שכותבת syslog רשומה ביומן עם חומרת NOTICE כשהאפליקציה משנה כתובת רשת. רשומות היומן של שינויים בכתובת הרשת כוללות payload של JSON שנראה כך:

"jsonPayload": {
  "type": "Configuration change",
  "action": "Set network address",
  "result": "IP_ADDRESS",
}

אתם רוצים ליצור מדיניות התראות שמבוססת על יומנים, שתשלח לכם התראה כשכתובת IPv4 לא תקינה מופיעה בשדה jsonPayload.result של רשומות ביומן ב-syslog עם חומרת NOTICE.

כדי ליצור את מדיניות ההתראות הזו:

במסוף Google Cloud , נכנסים לדף Logs Explorer:
כניסה אל Logs Explorer

אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Logging.
משתמשים בחלונית Query כדי ליצור שאילתה שתתאים להודעה שרוצים להשתמש בה במדיניות ההתראות שמבוססת על יומנים.

לדוגמה, כדי למצוא רשומות ביומן עם רמת חומרה NOTICE ביומן syslog, שמכילות כתובות IP לא חוקיות במטען הייעודי (payload) של JSON, אפשר להשתמש בשאילתה הבאה:
```
log_id("syslog")
severity = "NOTICE"
jsonPayload.result !~ "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.|$)){4}$"
```
לוחצים על Run query (הרצת שאילתה) כדי לאמת את השאילתה.
בסרגל הכלים Query results, מרחיבים את התפריט Actions ובוחרים באפשרות Create log alert.
בחלונית פרטי ההתראה:
1. מזינים שם למדיניות ההתראות בשדה שם מדיניות ההתראות. לדוגמה: 'כתובת רשת: ערך IPv4 לא תקין'.
2. בוחרים אפשרות מהתפריט רמת החומרה של המדיניות. בהתראות ובנוטיפיקציות מוצגת רמת החומרה.
3. אופציונלי: מוסיפים תיעוד למדיניות ההתראות. אפשר לכלול מידע שיעזור לנמען של ההתראה לאבחן את הבעיה. המחרוזת הבאה מסכמת את הסיבה להודעה:
```
Log-based alerting policy in project ${project} detected an invalid IPv4 value.
```
  במאמר שימוש ב-Markdown ובמשתנים בתבניות של מסמכים מוסבר איך לעצב את התוכן בשדה הזה ולהתאים אותו אישית.
כדי לעבור לשלב הבא, לוחצים על הבא.
בחלונית Choose logs to include in the alert:
1. מזינים שאילתה או עורכים את השאילתה הקיימת כדי לסנן את היומנים הזמינים. אם רשומות ביומן תואמות לשאילתה, כלל המדיניות להתראות מופעל.
2. כדי לאמת את השאילתה, לוחצים על תצוגה מקדימה של היומנים.
3. אופציונלי: חילוץ תוויות יומן. אפשר ליצור תוויות משדות ביומן כדי להציג אותן בכל ההתראות וההודעות שנוצרות על ידי ההתראה.
  
  בשדה התיעוד של מדיניות ההתראות, אתם מתייחסים לתוויות שחולצו באמצעות משתנה מהצורה ${log.extracted_label.KEY}, כאשר KEY הוא השם שנתתם לתווית שחולצה.
לוחצים על הבא.
בוחרים את הזמן המינימלי בין ההתראות. הערך הזה מאפשר לכם לשלוט במספר ההתראות שתקבלו מ-Monitoring אם התנאי הזה יתקיים כמה פעמים. בדוגמה הזו, בוחרים באפשרות 5 דקות.
אופציונלי: בוחרים את משך הזמן עד לסגירה אוטומטית של ההתראה. כברירת מחדל, משך הזמן עד לסגירה אוטומטית של ההתראה הוא 7 ימים.
לוחצים על הבא.
בוחרים ערוץ התראות אחד או יותר למדיניות ההתראות. בדוגמה הזו, בוחרים ערוץ התראות באימייל.

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

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

בדיקה של מדיניות התראות שמבוססת על יומן

כדי לבדוק את מדיניות ההתראות שיצרתם, אתם יכולים לכתוב ידנית רשומה ביומן שמתאימה לשאילתה. כדי לכתוב את רשומת היומן:

מגדירים את רשומת היומן הבאה על ידי שינוי המשתנה PROJECT_ID למזהה הפרויקט:

{
  "entries": [
  {
    "logName": "projects/PROJECT_ID/logs/syslog",
    "jsonPayload": {
      "type": "Configuration change",
      "action": "Set network address",
      "result": "999.027.405.1",
    },
    "severity": "NOTICE",
    "resource": {
      "type": "generic_task",
      "labels" : {
        "project_id": "PROJECT_ID",
        "location": "us-east1",
        "namespace": "fake-task-2",
        "job": "write-log-entry",
        "task_id": "11",
      },
    },
  },
  ],
}

עוברים לדף העזר logEntries.write או לוחצים על הלחצן הבא:

מעבר אל logEntries.write
מעתיקים את רשומת היומן שהגדרתם קודם.
בחלונית Try this API:
1. מחליפים את התוכן של השדה גוף הבקשה ב-APIs Explorer ברשומה ביומן שהעתקתם בשלב הקודם.
2. לוחצים על Execute. אם תתבקשו, תצטרכו לפעול לפי תהליך האימות.
  
  אם הקריאה של logEntries.write מצליחה, מקבלים קוד תגובת HTTP 200 וגוף תגובה ריק, {}. מידע נוסף על APIs Explorer מופיע במאמר שימוש ב-APIs Explorer במסמכי התיעוד של Monitoring. ‏APIs Explorer פועל באותו אופן עם Logging API.

הרשומה ביומן תואמת למסנן שצוין במדיניות ההתראות בדרכים הבאות:

הערך logName מציין את יומן syslog שנמצא בGoogle Cloud פרויקט.
הערך severity ברשומה הזו ביומן הוא NOTICE.
הערך jsonPayload.result הוא לא כתובת IPv4 תקינה.

אחרי שכותבים את הרשומה ביומן, מתרחש הרצף הבא:

רשומת היומן החדשה מופיעה בכלי Logs Explorer. הרשומה ביומן עומדת בתנאי של מדיניות ההתראות.
התראה נפתחת ב-Cloud Monitoring.
תקבלו התראה על ההתראה. אם הגדרתם ערוץ התראות באימייל, ההתראה תיראה כמו בצילום המסך הבא:

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

תרחישים אחרים: התראות על יומני ביקורת

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

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

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

נניח שהפרויקט שלכם מאחסן סודות ב-Secret Manager, וחלק מהסודות האלה מיועדים לשימוש רק על ידי חשבונות שירות. למעט במקרים חריגים, משתמשים אנושיים אף פעם לא ניגשים לסודות האלה.

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

אתם יכולים ליצור מדיניות התראות שמבוססת על יומן, שתשלח לכם התראה כשמשתמש אנושי ניגש לסוד.

בדוגמה הבאה מוצג קטע מרשומה ביומן הביקורת שנכתבה על ידי Secret Manager. קטע היומן מציג את השדות ששימושיים ליצירת השאילתה להתראה שמבוססת על יומן:

{
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "serviceName": "secretmanager.googleapis.com",
    "methodName": "google.cloud.secretmanager.v1.SecretManagerService.AccessSecretVersion",
    "authenticationInfo": {
      "principalEmail": "my-svc-account@PROJECT_ID.iam.gserviceaccount.com",
      "serviceAccountDelegationInfo": [],
      "principalSubject": "serviceAccount:my-svc-account@PROJECT_ID.iam.gserviceaccount.com"
    },
    ...
  },
  ...
}

שדות המשנה הבאים protoPayload חשובים במיוחד:

‫@type: מציין שרשומת היומן הזו היא רשומה של יומן ביקורת.
‫serviceName: מתעד את השירות שכתב את הרשומה ביומן הביקורת. בשדה הזה מציינים את הרשומות שנכתבו על ידי Secret Manager.
‫methodName: מזהה את ה-method שעבורה נכתבה הרשומה הזו ביומן הביקורת. בשדה הזה מציינים את הפעולה שגרמה ליצירת הרשומה הזו. בדוגמה הזו, זו השיטה AccessSecretVersion.
‫authenticationInfo.principalEmail: מתעד את החשבון שהפעיל את השיטה בשדה methodName. הערך הצפוי בשדה הזה הוא חשבון שירות, שמסתיים ב-gserviceaccount.com.

כדי למצוא רשומות ביומן לגבי גישה לסודות על ידי משתמש אנושי, מחפשים רשומות ביומן הביקורת שנכתבו על ידי Secret Manager. אתם רוצים למצוא את רשומות היומן שבהן הופעלה השיטה AccessSecretVersion על ידי חשבון משתמש שלא מסתיים ב-gserviceaccount.com. השאילתה הבאה מבודדת את הרשומות האלה ביומן:

protoPayload.@type = "type.googleapis.com/google.cloud.audit.AuditLog"
protoPayload.serviceName = "secretmanager.googleapis.com"
protoPayload.methodName =~ "AccessSecretVersion$"
protoPayload.authenticationInfo.principalEmail !~ "gserviceaccount.com$"

כדי ליצור מדיניות התראות שמבוססת על יומנים לגבי גישה אנושית לסודות, משתמשים בשאילתה הזו בחלונית Choose logs to include in the alert (בחירת יומנים להכללה בהתראה).

מדיניות התראות למעקב אחרי אירועי פענוח

אפשר להתאים את הניתוח בדוגמה הקודמת לשירותים אחרים. לדוגמה, אם אתם משתמשים ב-Cloud Key Management Service כדי להצפין ולפענח מידע אישי רגיש, אתם יכולים להשתמש ביומני ביקורת שנוצרו על ידי Cloud KMS כדי לזהות מתי משתמש אנושי מפענח ערך.

כדי למצוא רשומות ביומן שמתייחסות לפענוח שבוצע על ידי משתמש אנושי, צריך לחפש רשומות ביומן הביקורת שנכתבו על ידי Cloud KMS. אתם רוצים למצוא את הרשומות ביומן שבהן הופעלה השיטה Decrypt על ידי חשבון משתמש שלא מסתיים ב-gserviceaccount.com, מה שמצביע על חשבון שירות. השאילתה הבאה מבודדת את הרשומות האלה ביומן:

protoPayload.@type = "type.googleapis.com/google.cloud.audit.AuditLog"
protoPayload.serviceName = "cloudkms.googleapis.com"
protoPayload.methodName = "Decrypt"
protoPayload.authenticationInfo.principalEmail !~ "gserviceaccount.com$"

כדי ליצור מדיניות התראות מבוססת-יומנים לפענוח שבוצע על ידי משתמש אנושי, משתמשים בשאילתה הזו בחלונית Choose logs to include in the alert.

ניהול מדיניות התראות מבוססת-יומן ב-Monitoring

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

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

כדי לנווט מתוך 'רישום ביומן':
1. במסוף Google Cloud , נכנסים לדף Logs Explorer:
  כניסה אל Logs Explorer
  
  אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Logging.
2. בסרגל הכלים Query results, מרחיבים את התפריט Actions ובוחרים באפשרות Manage log alerts.
כדי לנווט מהדף 'מעקב':
1. נכנסים לדף Alerting במסוף Google Cloud :
  כניסה אל התראות
  
  אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שבה הכותרת המשנית היא Monitoring.
2. כדי לראות את כל כללי המדיניות ולהפעיל סינון, בחלונית Policies (כללי מדיניות), לוחצים על See all policies (הצגת כל כללי המדיניות).

שתי הפעולות האלה מעבירות אתכם לדף Policies (כללי מדיניות) בקטע Monitoring, שבו מפורטים כל כללי ההתראה ב Google Cloud פרויקט.

כדי לצמצם את רשימת מדיניות ההתראות, מוסיפים מסננים. כל מסנן מורכב משם ומערך. לדוגמה, אפשר להגדיר את הערך כך שיתאים בדיוק לשם מדיניות או להתאמה חלקית. ההתאמות לא תלויות באותיות רישיות (case-sensitive). אם מציינים כמה מסננים, הם מצורפים באופן מרומז באמצעות האופרטור הלוגי AND, אלא אם מוסיפים מסנן OR. בצילום המסך הבא מפורטות מדיניות ההתראות שמופעלות ושנוצרו אחרי 1 בינואר 2021:

רשימה של מדיניות מופעלת בנושא התראות שנוצרה אחרי 1 בינואר 2021.

בדף Policies (מדיניות) אפשר לערוך, למחוק, להעתיק, להפעיל או להשבית מדיניות התראות:

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

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

יצירת מדיניות התראות מבוססת-יומן באמצעות Monitoring API

אפשר ליצור מדיניות התראות שמבוססת על יומנים באמצעות Monitoring API. אתם מספקים ל-Monitoring API את אותו מידע שאתם מספקים כשאתם משתמשים ב-Logs Explorer במסוף Google Cloud :

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

כדי ליצור מדיניות התראות באמצעות Monitoring API, יוצרים אובייקט AlertPolicy ושולחים אותו ל-method‏ alertPolicies.create.

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

המבנה של כללי מדיניות התראות

ה-API של Monitoring מייצג מדיניות התראות באמצעות המבנה AlertPolicy. המבנה AlertPolicy כולל כמה מבנים מוטמעים, כולל תיאור של התנאי של מדיניות ההתראות. יש כמה הבדלים בין מדיניות התראות שמבוססת על יומנים לבין מדיניות התראות שמבוססת על מדדים:

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

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

כללי התראות

כשיוצרים מדיניות התראות שמבוססת על יומן, שירות Logging יוצר אובייקט פנימי שנקרא כלל התראה. רישום ביומן משתמש בכלל ההתראה כדי להתאים רשומות ביומן הנכנסות למסנן של מדיניות ההתראה, ואז ליצור התראה כשרשומה תואמת לקריטריונים של המסנן. אין אינטראקציה ישירה עם כלל ההתראות. עם זאת, כדי ליצור מדיניות התראות שמבוססת על יומנים, צריך את ההרשאה logging.notificationRules.create.

תכנון מדיניות ההתראות

בקטע יצירת מדיניות התראות מבוססת-יומן באמצעות Logs Explorer מוסבר על דרך אחת ליצור מדיניות התראות מבוססת-יומן. בקטע הזה מוסבר איך ליצור מדיניות התראות שמבוססת על יומן, שתשלח לכם התראה כשערך syslog ביומן הוא ברמת חומרה NOTICE וכתובת IPv4 לא חוקית בשדה jsonPayload.result.

כדי ליצור את אותה מדיניות התראות שמבוססת על יומנים באמצעות Monitoring API, יוצרים אובייקט AlertPolicy שנראה כמו מבנה ה-JSON הבא:

{
  "displayName": "Network address: invalid IPv4 value (API)",
  "documentation": {
    "content": "Log-based alerting policy in project ${project} detected an invalid IPv4 value.",
    "mimeType": "text/markdown"
  },

  "conditions": [
    {
      "displayName": "Log match condition: invalid IP addr (API)",
      "conditionMatchedLog": {
        "filter": "log_id(\"syslog\") severity = \"NOTICE\" jsonPayload.result !~ \"^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\\.|$)){4}$\"",
      },
    }
  ],
  "combiner": "OR",

  "alertStrategy": {
    "notificationRateLimit": {
      "period": "300s"
    },
    "autoClose": "604800s",
  },

  "notificationChannels": [
    "projects/PROJECT_ID/notificationChannels/CHANNEL_ID"
  ]
}

קוד ה-JSON הזה מציין את אותם פרטים שאתם מציינים כשאתם יוצרים מדיניות התראות שמבוססת על יומנים באמצעות Logs Explorer. בקטעים הבאים מפורט מיפוי של התוכן במבנה AlertPolicy לשלבים שצריך לבצע כשמשתמשים ב-Logs Explorer כדי ליצור התראה שמבוססת על יומן. הערך בשדה conditionMatchedLog הוא מבנה LogMatch.

צריך לספק שם ותיעוד

למדיניות התראות יש שם מוצג ומסמכים משויכים שמצורפים להתראות כדי לעזור למגיבים. בכלי Logs Explorer, השדות האלה נקראים שם ההתראה ותיעוד. אפשר לייצג את הערכים האלה במבנה AlertPolicy באופן הבא:

{
  "displayName": "Network address: invalid IPv4 value (API)",
  "documentation": {
    "content": "Log-based alerting policy in project ${project} detected an invalid IPv4 value.",
    "mimeType": "text/markdown"
  },
  ...
}

בדוגמה הזו, הערך של displayName כולל את המחרוזת (API) כדי שתוכלו להבחין בין שתי המדיניות לדוגמה כשאתם צופים ברשימת המדיניות במסוף Google Cloud . בדף Monitoring Policies (מעקב אחר מדיניות) מופיעה רשימה של כללי מדיניות לפי השם המוצג שלהם, ומופיע בה גם אם המדיניות מבוססת על מדדים או על יומנים. מידע נוסף מופיע במאמר בנושא ניהול מדיניות התראות שמבוססת על יומנים ב-Monitoring.

השדה documentation כולל, בשדה המשנה content, את התיאור שאולי סיפקתם כשאתם משתמשים בכלי Logs Explorer. שדה המשנה השני, mimeType, נדרש כשמציינים ערך בשדה documentation. הערך החוקי היחיד הוא "text/markdown".

בוחרים את היומנים שעבורם רוצים לקבל התראה

למדיניות התראות שמבוססת על יומן יש תנאי אחד. ב-Logs Explorer, מציינים את התנאי כשמזינים שאילתה בשדה Define log entries to alert on (הגדרת רשומות ביומן להתרעה). אפשר לייצג את הערכים האלה במבנה AlertPolicy באופן הבא:

{ ...
  "conditions": [
    {
      "displayName": "Log match condition: invalid IP addr (API)",
      "conditionMatchedLog": {
        "filter": "log_id(\"syslog\" severity = \"NOTICE\" jsonPayload.result !~ \"^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\\.|$)){4}$\"",
      },
    }
  ],
  "combiner": "OR",
  ...
}

השדה conditions מקבל רשימה של מבני Condition, אבל למדיניות התראות שמבוססת על יומנים יכול להיות רק תנאי אחד. לכל Condition יש שם לתצוגה ותיאור של התנאי.

הערך של השדה displayName הוא תיאור קצר של התנאי. כשמשתמשים בכלי Logs Explorer כדי ליצור כללי מדיניות להתראות שמבוססים על יומנים, השם המוצג תמיד יהיה Log match condition (תנאי התאמה ליומן). כשמשתמשים ב-Monitoring API, אפשר לספק שם תצוגה מדויק יותר. חובה לציין ערך.
הערך של השדה conditionMatchedLog הוא מבנה LogMatch, והערך של השדה filter הוא השאילתה שציינתם ב-Logs Explorer. מכיוון שהשאילתה הזו מסופקת כערך של שדה JSON, השאילתה כולה מופיעה בתוך מרכאות, וכל מרכאות בשאילתה עצמה צריכות להיות מסומנות בתו בריחה \ (קו נטוי שמאלי).
המבנה LogMatch כולל גם שדה אופציונלי labelExtractors. אפשר להשתמש בכלי לחילוץ תוויות כדי ליצור תוויות מותאמות אישית מתוך רשומות היומן, ואז להפנות לתוויות האלה בהתראות.

הערה: אל תחלצו את התווית timestamp. אם תסירו את התווית הזו, מדיניות ההתראות לא תיצור התראות או תשלח התראות.

לדוגמה, כדי לחלץ את הערך של התווית labels."compute.googleapis.com/resource_id" מהרשומה ביומן לתווית שנקראת vm_identifier, התנאי הקודם יכול להיראות כך:
```
"conditions": [
  {
    "displayName": "Log match condition: invalid IP addr (API)",
    "conditionMatchedLog": {
      "filter": "log_id(\"syslog\" severity = \"NOTICE\" jsonPayload.result !~ \"^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\\.|$)){4}$\")",
      "labelExtractors": {
        "vm_identifier": "EXTRACT(labels.\"compute.googleapis.com/resource_id\")"
      }
    },
  }
],
```
אפשר להשתמש בפונקציה EXTRACT כדי להתאים את כל הערך, או להשתמש בפונקציה REGEXP_EXTRACT כדי להתאים מחרוזות משנה על סמך ביטויים רגולריים. זו אותה פונקציה שמשמשת לחילוץ תוויות במדדים מבוססי-יומן. מידע נוסף זמין במאמר יצירת תווית.

אפשר להשתמש בתוויות שחולצו במסמכי מדיניות ההתראות, כדי שהן ידווחו בהתראות. בשדה documentation של מדיניות ההתראות, מתייחסים לתוויות שחולצו באמצעות משתנה מהצורה ${log.extracted_label.KEY}, כאשר KEY הוא השם שנתתם לתווית שחולצה.

בדוגמה הבאה מוצג איך מתייחסים למפתח של התווית שחולצה vm_identifier, כדי שהערך של תווית היומן labels."compute.googleapis.com/resource_id" ייכלל בהתראות:
```
"documentation": {
  "content": "Log-based alerting policy in project ${project} detected an
   invalid IPv4 value on VM with ID ${log.extracted_label.vm_identifier}.",
  "mimeType": "text/markdown"
},
```

הערך בשדה combiner מציין איך לשלב את התוצאות של כמה תנאים במדיניות של התראות שמבוססות על מדדים. אפשר להשתמש רק בתנאי אחד במדיניות התראות שמבוססת על יומנים, וחובה לציין את השדה combiner עם הערך "OR". אי אפשר ליצור מדיניות התראות שמבוססת על יומנים עם כמה תנאים.

הגדרת ערכים של התראות וסגירה אוטומטית

מדיניות התראות שמבוססת על יומן מציינת את הזמן המינימלי בין ההתראות. ב-Logs Explorer, בוחרים ערך בתפריט Time between notifications (הזמן בין ההתראות). כדי לציין את הערך הזה במבנה AlertPolicy, צריך להזין ערך בשניות בשדה period של מבנה NotificationRateLimit שמוטמע במבנה AlertStrategy.

באופן דומה, מדיניות ההתראות כוללת את התקופה שבה ההתראות נסגרות באופן אוטומטי. ערך ברירת המחדל הוא 7 ימים. ב-Logs Explorer, אפשר לבחור ערך אחר בתפריט Alert autoclose duration. האפשרות הזו תואמת לשדה autoclose במבנה של AlertStrategy API. כשמשתמשים בשדה הזה, צריך לציין את הערך בשניות. הערך המינימלי הוא 1,800 שניות, או 30 דקות.

{ ...
  "alertStrategy": {
    "notificationRateLimit": {
      "period": "300s"
    },
    "autoClose": "604800s",
  },
  ...
}

הערך בשדה period בדוגמה הזו, 300s, שווה ל-5 דקות. הערך של autoclose, ‏ 604800s, שווה ל-7 ימים.

מציינים למי לשלוח התראה

מדיניות התראות יכולה לכלול רשימה של ערוצי התראות. ב-Logs Explorer, בוחרים ערוצים מתוך תפריט. כדי לייצג את הערכים האלה במבנה AlertPolicy, צריך לספק רשימה של שם משאב אחד או יותר לאובייקטים מוגדרים של NotificationChannel:

{ ...
  "notificationChannels": [
    "projects/PROJECT_ID/notificationChannels/CHANNEL_ID"
  ]
}

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

שליחת מדיניות ההתראות אל Monitoring API

כדי ליצור מדיניות התראות באמצעות Monitoring API, יוצרים אובייקט AlertPolicy ושולחים אותו ל-method‏ alertPolicies.create. אפשר להפעיל את alertPolicies.create באמצעות Google Cloud CLI או באמצעות קריאה ישירה ל-Monitoring API.

אפשר גם ליצור מדיניות התראות שמבוססת על יומנים באמצעות ספריות הלקוח של C#,‏ Go,‏ Java,‏ Python ו-Ruby. יכול להיות שתוכלו להשתמש גם בספריות לקוח אחרות. הספרייה שמתאימה לשפה שלכם צריכה לכלול את סוג התנאי LogMatch.

כדי ליצור מדיניות התראות באמצעות ה-CLI של gcloud, מבצעים את הפעולות הבאות:

מכניסים את ייצוג ה-JSON של מדיניות ההתראות לקובץ טקסט, לדוגמה, לקובץ בשם alert-invalid-ip.json.
מעבירים את קובץ ה-JSON הזה ל-CLI של gcloud באמצעות הפקודה הבאה:
```
gcloud monitoring policies create --policy-from-file="alert-invalid-ip.json"
```
אם הפקודה מסתיימת ללא שגיאות, היא מחזירה את שם המשאב של המדיניות החדשה, למשל:
```
Created alerting policy [projects/PROJECT_ID/alertPolicies/POLICY_ID].
```

כדי ליצור מדיניות התראות על ידי קריאה ישירה ל-alertPolicies.create, אפשר להשתמש בכלי APIs Explorer באופן הבא:

עוברים לדף העזר של alertPolicies.create.
בחלונית Try this API:
1. בשדה name, מזינים את הערך הבא:
```
projects/PROJECT_ID
```
2. מעתיקים את ייצוג ה-JSON של מדיניות ההתראות ומחליפים את התוכן של השדה גוף הבקשה ב-APIs Explorer במדיניות ההתראות שהועתקה.
3. לוחצים על Execute.
  
  אם הקריאה של alertPolicies.create מצליחה, מקבלים קוד תגובת HTTP 200 וגוף תגובה ריק, {}. מידע נוסף על APIs Explorer מופיע במאמר שימוש ב-APIs Explorer במסמכי העזרה של Monitoring.

מידע נוסף על יצירת מדיניות התראות באמצעות Monitoring API זמין במאמר יצירת מדיניות. בדוגמאות במסמך הזה נעשה שימוש בסוגי תנאים למדיניות התראות מבוססת-מדדים, אבל העקרונות זהים.

בדיקת מדיניות ההתראות

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

דוגמה: יצירת מדיניות התראות כשרישום ביומן מכיל מחרוזת טקסט

בדוגמה הזו נעשה שימוש במסוף Google Cloud כדי ליצור מדיניות התראות, ב-Logs Explorer כדי להציג רשומות ביומן וב-Google Cloud CLI כדי לכתוב רשומה ביומן:

במסוף Google Cloud , נכנסים לדף Logs Explorer:
כניסה אל Logs Explorer

אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Logging.
בחלונית Query, מזינים את השאילתה הבאה אחרי עדכון הערך של PROJECT_ID:
```
logName="projects/PROJECT_ID/logs/test-log"
textPayload:"Oops"
```
השאילתה מחפשת ביומן עם השם test-log רשומות ביומן שיש להן שדה textPayload שמכיל את המחרוזת Oops.
בסרגל הכלים Query results, מרחיבים את התפריט Actions ובוחרים באפשרות Create log alert. אחר כך משלימים את תיבת הדו-שיח.

צריך להזין שם למדיניות, כמו Alert on Oops. השאילתה שהזנתם בשלב הקודם נכללת אוטומטית במדיניות ההתראות.
כדי לבדוק את מדיניות ההתראות, פותחים את Cloud Shell ומריצים את הפקודה הבאה:
```
gcloud logging write test-log --severity=ERROR --payload-type=text 'This log entry contains Oops'
```
הפקודה הקודמת כותבת רשומה ליומן בשם test-log. הערך כולל רמת חומרה של ERROR ושדה textPayload.
ב-Logs Explorer, לוחצים על Run query (הרצת שאילתה).

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

אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שבה הכותרת המשנית היא Monitoring.

בחלונית התראות מוצגת ההתראה ופרטים על מדיניות ההתראות.

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

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