הגדרת תוויות במדדים מבוססי-יומנים

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

אם אתם מכירים את התוויות, אתם יכולים לעבור ישירות אל יצירת תווית בדף הזה.

סקירה כללית על תוויות למדדים מבוססי-יומנים

תוויות מאפשרות למדדים מבוססי-יומן להכיל כמה סדרות זמנים – אחת לכל שילוב של ערכי תוויות. לכל המדדים שמבוססים על יומנים יש תוויות ברירת מחדל.

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

  • כל התוכן של שדה עם שם באובייקט LogEntry.
  • חלק משדה עם שם שתואם לביטוי רגולרי (regexp).

אפשר לחלץ תוויות מהשדות המובנים LogEntry, כמו httpRequest.status, או מאחד משדות המטען הייעודי (payload) textPayload, jsonPayload או protoPayload. עם זאת, אי אפשר לחלץ את המזהה של קבוצת שגיאות מהשדה errorGroups.

מידע על ביטויים רגולריים זמין במאמר בנושא תחביר RE2.

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

מגבלות של תוויות שהוגדרו על ידי משתמש

ההגבלות הבאות חלות על תוויות שהוגדרו על ידי המשתמש:

  • אפשר ליצור עד 10 תוויות שהמשתמש מגדיר לכל מדד.

  • אחרי שיוצרים תווית, אי אפשר למחוק אותה.

    • אפשר לשנות את ביטוי החילוץ ואת התיאור של התווית שכבר יצרתם.

    • אי אפשר לשנות את השם או את סוג הערך של תווית שכבר יצרתם.

  • המערכת שומרת רק את 1,024 התווים הראשונים של ערך התווית.

  • כל מדד שמבוסס על יומן מוגבל לכ-30,000 סדרות זמן פעילות, בהתאם למספר הערכים האפשריים לכל תווית, כולל תוויות ברירת מחדל.

    לדוגמה, אם רשומות היומן מגיעות מ-100 משאבים כמו מכונות וירטואליות, ואתם מגדירים תווית עם 20 ערכים אפשריים, יכולות להיות עד 2,000 סדרות זמן למדד.

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

תוויות ברירת מחדל

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

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

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

  • ‫log: התווית הזו מכילה את הערך של החלק LOG_ID בשדה logName ברשומות של יומן.

  • ‫severity: התווית הזו מכילה את הערך של השדה severity ברשומות של יומן. תווית החומרה מסופקת כברירת מחדל רק במדדים שמבוססים על יומן המערכת.

הצגת תוויות באמצעות Metrics Explorer

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

  1. נכנסים לדף Log-based Metrics במסוף Google Cloud :

    כניסה אל מדדים מבוססי-יומנים

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

  2. מחפשים את המדד שרוצים לראות, ואז בוחרים באפשרות View in Metrics Explorer (הצגה ב-Metrics Explorer) בתפריט More (עוד) של המדד.

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

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

    • לסוג המשאב gce_instance יש שלושה תוויות משאבים: ‏project_id, ‏instance_id ו-zone.

    • לסוג המדד logging/log_entry_count יש שני תוויות מדדים: log ו-severity. גם תוויות שהוגדרו על ידי המשתמש מופיעות בקטע הזה.

  4. כדי לוודא שתווית שהוגדרה על ידי המשתמש מחלצת את הנתונים הנכונים מרשומות היומן:

    1. משנים את הרכיב Aggregation ל-Unaggregated.

    2. בתרשים, בוחרים באפשרות טבלה או גם וגם.

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

      אם לא רואים תווית שיצרתם, צריך לוודא את שם השדה ואת ביטוי החילוץ.

יצירת תווית

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

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

המסוף

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

  2. לוחצים על הוספת תווית.

    טיפ: כדי לראות את השדות והערכים בתוך רשומה ביומן, מבצעים את הפעולות הבאות:

    1. בקטע בחירת מסנן, לוחצים על תצוגה מקדימה של היומנים.
    2. בחלונית View logs, בוחרים רשומה ביומן ולוחצים על החץ להרחבה שלידה.
    3. לוחצים על הרחבת שדות מקוננים.

  3. מגדירים את השדות הבאים בקטע תוויות:

    1. שם התווית: מזינים שם לתווית. לדוגמה, ID.

      השם צריך לעמוד בקריטריונים הבאים:

      • להיות באורך של עד 100 תווים.
      • התאמה לביטוי הרגולרי [a-zA-Z][a-zA-Z0-9_]*.
      • מכילים יותר מהמחרוזת log.

    2. תיאור: תיאור של התווית. כדאי לנסות להיות כמה שיותר ספציפיים לגבי הפורמט של ערכי היומנים הצפויים. לדוגמה, Instance number.

    3. סוג התווית: בוחרים באפשרות STRING,‏ BOOLEAN או INTEGER.

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

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

      labels."compute.googleapis.com/resource_id"

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

      לדוגמה, נניח שהשדה בדרך כלל מכיל טקסט כמו:

      The instance number is 0123456789; the ID is my-test-instance22

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

      The instance number is ([0-9]+); .*

      מידע נוסף על ביטויים רגולריים זמין במאמר בנושא תחביר RE2.

  4. לוחצים על סיום כדי ליצור את התווית. כדי להוסיף עוד תוויות, חוזרים על השלבים האלה.

  5. כדי לסיים את יצירת המדד, לוחצים על יצירת מדד.

gcloud

כדי ליצור מדד מבוסס-יומן עם תוויות בהתאמה אישית, צריך ליצור קובץ שמכיל ייצוג של הגדרת LogMetric בפורמט JSON או YAML, כולל התוויות בהתאמה אישית. לאחר מכן, יוצרים את המדד באמצעות הפקודה create עם הדגל --config-from-file, ומחליפים את FILENAME בשם של קובץ ה-JSON או ה-YAML:

gcloud logging metrics create METRIC_NAME --config-from-file FILENAME

מידע נוסף זמין במאמר gcloud logging metrics create.

API

תוויות מצוינות כחלק מאובייקט LogMetric בתוכן הבקשה של קריאות לשיטה projects.metrics.create של Logging API. מידע על קריאות מלאות לשיטות זמין במאמרים בנושא יצירת מדדים של מונה או יצירת מדדים של התפלגות.

לכל תווית, צריך להוסיף פלח לשדות metricDescriptor ו-labelExtractors ב-LogMetric.

התחביר הוא:

{
  ...
  metricDescriptor: {
      labels: [
        { key: LABEL_NAME, valueType: LABEL_TYPE,
          description: LABEL_DESCRIPTION },
        ...
      ]
  },
  labelExtractors: {
    LABEL_NAME: EXTRACTOR_EXPRESSION,
    ...
  },
}

לרכיבי התחביר יש את המשמעות הבאה:

  • ‫LABEL_NAME: השם של התווית כמחרוזת.
  • ‫VALUE_TYPE: סוג התווית: STRING,‏ BOOL או INT64.
  • ‫LABEL_DESCRIPTION: תיאור התווית.

  • ‫EXTRACTOR_EXPRESSION: מחרוזת שמשלבת את שם השדה של רשומת היומן עם ביטוי רגולרי אופציונלי. הביטוי של הכלי לחילוץ יכול להיות אחד מהבאים:

    EXTRACT(FIELD)

    REGEXP_EXTRACT(FIELD, REGEXP)

מידע נוסף על ביטויים רגולריים זמין במאמר בנושא תחביר RE2.

דוגמה עם שתי תוויות:

{
  ...
  metricDescriptor: {
      labels: [
        { key: "label_name_a", valueType: STRING },
        { key: "label_name_b", valueType: INT64 },
      ]
  },
  labelExtractors: {
    "label_name_a":
      "REGEXP_EXTRACT(jsonPayload.field_a, \"before ([a-zA-Z ]+) after\")",
    "label_name_b": "EXTRACT(jsonPayload.field_b)",
  },
}

פרטים נוספים זמינים במאמר בנושא סוג LogMetric.

דוגמאות

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

טיפים:

  • כשמציינים ביטוי לחילוץ, צריך להשתמש בקבוצת לכידה.
  • אם לא מציינים ביטוי לחילוץ, המערכת מחלצת את כל הערך של השדה.

  • חשוב לוודא שקבוצת הערכים האפשריים של כל תווית מוגבלת. הגישה המומלצת היא להשתמש במספר קטן של ערכים נפרדים (כמו 'אדום', 'ירוק' ו'כחול'). לדוגמה, אם מחלצים את ערכי ה-RGB של תווית צבע ב-8 ביט, יכולים להיות יותר מ-16 מיליון ערכים שונים. המשמעות היא שיכולים להיות לכם יותר מ-16 מיליון סדרות זמן.

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

שליפת קוד הסטטוס מיומן ביקורת

אם שדה לא מכיל תווים מיוחדים, אפשר להשתמש בשם השדה בתווית של המדד מבוסס-היומן.

לדוגמה, ביומני ביקורת, השדה protoPayload תואם למבנה AuditLog. לכן, כדי לחלץ את השדה status מיומן ביקורת, אפשר להגדיר את שם השדה ל-protoPayload.status.code ולהשאיר את ביטוי החילוץ ריק.

אם רוצים לחלץ רק את הספרה הראשונה של קוד השגיאה, אפשר להגדיר את ביטוי החילוץ ל-(\d)\d\d.

חילוץ ערך משדה עם תווים מיוחדים

אם שדה ברשומה ביומן מכיל תווים מיוחדים, צריך להוסיף מירכאות כפולות מסביב לשדה.

לדוגמה, כדי לחלץ את כל הערך של התווית k8s-pod/k8s-app, צריך להגדיר את שם השדה כ-labels."k8s-pod/k8s-app" ולהשאיר את הביטוי ריק.

חילוץ ערך ממטען ייעודי (payload) של טקסט

נבחן רשומה ביומן בפורמט הבא:

textPayload: "unfinished_task_instance_count.py:61 Unfinished task instance count metric value 0 for state: deferred"

כדי לחלץ את הערך של המדינה, כמו deferred מתוך רשומות ביומן בפורמט הקודם, אפשר לעשות משהו כזה:

  • שם השדה: textPayload
  • ביטוי לחילוץ: ^unfinished.*state: ([a-z]+)

חילוץ ערך משדה חוזר

רשומה ביומן יכולה להכיל שדה עם שדות חוזרים. ב-JSON, השדות האלה מוצגים באמצעות סוגריים מרובעים ([]). מבחינת התוויות, השדות החוזרים נחשבים כקבוצה, והכלי לחילוץ תוויות נחשב כאיטרטור. אתם מספקים את הקריטריונים להתאמה כשאתם מגדירים את התווית, והכלי לחילוץ נתונים חוזר על הפעולה שוב ושוב עד שהוא מוצא התאמה. ההתאמה הראשונה תמיד מוחזרת, גם אם כמה איברים בקבוצה תואמים לקריטריונים.

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

{
  ...
  protoPayload: {
    @type: "type.googleapis.com/google.cloud.audit.AuditLog"
    authenticationInfo: {1}
    authorizationInfo: [
      0: {
        granted: true
        permission: "io.k8s.coordination.v1.leases.get"
        resource: "coordination.k8s.io/v1/namespaces/kube-system/leases/maintenance-controller"
      }
    ]
    requestMetadata: {2}
    status: {1}
    ...
  }
  ...
}

אתם מחליטים ליצור תווית למדד מבוסס-יומן שמאחסן מידע מהשדה permission. אפשר לראות שהשדות האלה מעוצבים כמו io.k8s.xyz, כאשר xyz היא מחרוזת שמספקת פרטים נוספים על הבקשה. למחרוזת הזו יכול להיות ערך כמו get, או שהיא יכולה לכלול עיצוב מורכב יותר כמו io.k8s.coordination.v1.leases.get.

כדי לצמצם את מספר הערכים של התוויות, לא כדאי לחלץ את המידע המפורט. אתם רוצים לאחסן בתווית רק ערכים כמו get או coordination. בנוסף, אתם מחליטים שלא לכלול את הקידומת המשותפת io.k8s. בערך התווית.

בשלב הבא מגדירים את התווית. מכיוון שהשדה permission הוא שדה חוזר, והשדה authorizationInfo הוא שדה ההורה, צריך להגדיר את שם השדה באופן הבא:

protoPayload.authorizationInfo.permission

לבסוף, יוצרים את הביטוי הרגולרי הבא:

io.k8s.([a-z]+).*