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

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

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

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

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

אפשר ליצור תוויות נוספות להגדרה על ידי המשתמש במדדים מסוג מונה ומסוג חלוקה, על ידי ציון ביטויי חילוץ. ביטוי לחילוץ מגדיר ל-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. בקטע Filter selection, לוחצים על Preview logs.
    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]+).*