Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

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

לדוגמה, נניח שיש לכם אפליקציה שכותבת רשומה ביומן עם חומרת NOTICE כשהאפליקציה משנה כתובת רשת.syslog רשומות היומן של שינויים בכתובת הרשת כוללות 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. מזינים שם למדיניות ההתראות בשדה Alert Policy Name (שם מדיניות ההתראות). לדוגמה: 'כתובת רשת: ערך 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 ימים.
לוחצים על הבא.
בוחרים ערוץ התראות אחד או יותר למדיניות ההתראות. בדוגמה הזו, בוחרים ערוץ התראות באימייל.

אם כבר הגדרתם ערוץ התראות באימייל, תוכלו לבחור אותו מהרשימה. אם לא, לוחצים על Manage notification channels (ניהול ערוצי התראות) ומוסיפים ערוץ אימייל. מידע על יצירת ערוצי התראות זמין במאמר יצירה וניהול של ערוצי התראות.
לוחצים על 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. מחליפים את התוכן של השדה Request body ב-APIs Explorer ברשומה ביומן שהעתקתם בשלב הקודם.
2. לוחצים על Execute. אם תתבקשו, תצטרכו לבצע את תהליך האימות.
  
  אם הקריאה של logEntries.write מצליחה, מקבלים קוד תגובה מסוג HTTP 200 וגוף תגובה ריק, {}. מידע נוסף על APIs Explorer מופיע במאמר שימוש ב-APIs Explorer במסמכי התיעוד של Monitoring. השימוש ב-APIs Explorer זהה גם ב-Logging API.

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

הערך logName מציין את יומן הרישום syslog שנמצא בGoogle Cloud פרויקט.
הערך severity ברשומה הזו ביומן הוא 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.

השדה 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, השאילתה כולה מופיעה במרכאות, וכל מרכאות בשאילתה עצמה צריכות להיות עם escape באמצעות התו \ (קו נטוי הפוך).
המבנה 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, אפשר לבחור ערך אחר בתפריט Incident 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.

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

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

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