הגדרת מדדי הפצה

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

סקירה כללית

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

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

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

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

  1. כדי להשתמש במדדים מבוססי-יומן, צריך Google Cloud פרויקט שמופעל בו חיוב:

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

    2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

      Roles required to select or create a project

      • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
      • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

      Go to project selector

    3. Verify that billing is enabled for your Google Cloud project.

    4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

      Roles required to select or create a project

      • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
      • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

      Go to project selector

    5. Verify that billing is enabled for your Google Cloud project.

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

יצירת מדד התפלגות

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

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

המסוף

כדי ליצור מדד מונה מבוסס-יומן במסוףGoogle Cloud בפרויקט Google Cloud :

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

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

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

  2. לוחצים על יצירת מדד. החלונית Create logs metric (יצירת מדד של יומנים) מופיעה.

  3. מגדירים את סוג המדד: בוחרים באפשרות הפצה.

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

    • שם המדד מבוסס-היומן: בוחרים שם ייחודי בין המדדים מבוססי-היומן בפרויקט Google Cloud . יש הגבלות מסוימות על שמות. פרטים נוספים זמינים במאמר פתרון בעיות.
    • תיאור: מזינים תיאור למדד.
    • יחידות: (אופציונלי) במדדי התפלגות, אפשר להזין יחידות כמו s ו-ms. מידע נוסף זמין בשדה unit של MetricDescriptor.

  5. מגדירים את מסנן המדדים בקטע Filter selection.

    1. בתפריט Select project or log bucket בוחרים אם המדד יספור את רשומות היומן בפרויקט Google Cloud או רק את רשומות היומן בדלי יומן ספציפי.

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

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

      protoPayload.latency

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

      דוגמה. נניח שהשדה latency של הרשומה ביומן כולל מספר שאחריו ms של אלפיות השנייה. הביטוי הרגולרי הבא בוחר את המספר בלי הסיומת של היחידה:

      ([0-9.]+)

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

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

  6. (אופציונלי) מוסיפים תווית בקטע Labels (תוויות). הוראות ליצירת תוויות זמינות במאמר יצירת תווית.

  7. לוחצים על יצירת מדד כדי ליצור את המדד.

gcloud

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

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

מידע על תיאור של קטגוריות בהיסטוגרמה של התפלגות זמין במאמר קטגוריות בהיסטוגרמה.

API

כדי ליצור מדד הפצה, משתמשים ב-method‏ projects.metrics.create של Logging API. אם משתמשים בחלונית APIs Explorer בדף ההפניה, צריך להכין את הארגומנטים באופן הבא:

  1. מגדירים את השדה parent לפרויקט או לקטגוריה שבהם רוצים ליצור את המדד:

    • כדי להגדיר מדד מבוסס-יומן ברמת הפרויקט, מציינים את הפרויקט:
    projects/PROJECT_ID
    • לגבי מדד מבוסס-יומן עם היקף של קטגוריה, מציינים את הקטגוריה:
    projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID

  2. מגדירים את גוף הבקשה לאובייקט LogMetric. בקטע Example JSON for a distribution metric (דוגמה ל-JSON של מדד חלוקה) מופיעה דוגמה לתוכן הבקשה.

דוגמה ל-JSON של מדד הפצה

זוהי דוגמה לאובייקט LogMetric. כשמשתמשים ב-API, צריך להעביר אובייקט LogMetric. אפשר גם לשמור את האובייקט בקובץ ולציין את שם הקובץ בפקודה של Google Cloud CLI:

{
  name:        "my-metric"
  description: "Description of my-metric."
  filter:      "resource.type=gce_instance AND log_id(\"syslog\")",
  valueExtractor: "REGEXP_EXTRACT(jsonPayload.latencyField, \"([0-9.]+)ms\")",

  labelExtractors: {
    "my-label-1":
      "REGEXP_EXTRACT(jsonPayload.someField, \"before ([[:word:]]+) after\")",
    "my-label-2":
      "EXTRACT(jsonPayload.anotherField, \"before ([0-9]+) after\")",
  },
  bucketOptions: { [SEE_BELOW] },

  metricDescriptor: {
      metricKind: DELTA,
      valueType: DISTRIBUTION,
      unit: "ms",

      labels: [
        {
          key: "my-label-1",
          valueType: STRING,
          description: "Description of string my-label-1.",
        },
        {
          key: "my-label-2",
          valueType: INT64,
          description: "Description of integer my-label-2.",
        }
      ]
  },
}

הערות:

  • יש הגבלות מסוימות על שמות. פרטים נוספים זמינים במאמר פתרון בעיות.

  • השדה metricDescriptor תואם לאובייקט MetricDescriptor. צריך להגדיר את metricKind לערך DELTA ואת valueType לערך DISTRIBUTION.

  • חובה לאכלס את השדה bucketOptions. בקטע הבא מוסבר איך להגדיר את השדה הזה.

קטגוריות בהיסטוגרמה

מדדי ההתפלגות כוללים היסטוגרמה שסופרת את מספר הערכים שנמצאים בטווחים (buckets) שצוינו. אפשר להגדיר עד 200 קטגוריות במדד של התפלגות.

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

אפשר לציין את כל פריסות הקטגוריות על ידי הצגת רשימה של ערכי הגבול בין הקטגוריות השונות, בסדר עולה. הדלי הראשון הוא underflow bucket, שסופר ערכים שקטנים מהגבול הראשון. הדלי האחרון הוא דלי הגלישה, שסופר ערכים שגדולים מהגבול האחרון או שווים לו. במשבצות האחרות נספרים ערכים שגדולים מהגבול התחתון או שווים לו, וקטנים מהגבול העליון. אם יש n ערכי סף, יש n+1 קטגוריות. לא כולל את דלי הגלישה התחתונה והגלישה העליונה, יש n-1 דליים סופיים.

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

  • לינארי(היסט, רוחב, i): לכל קטגוריה יש את אותו הרוחב. הגבולות הם offset + width * i, כאשר i=0,1,2,...,N. למידע נוסף על דליים ליניאריים, ראו הפניית API.

  • ‫Exponential(scale, growth_factor, i): רוחב הדלי גדל עבור ערכים גבוהים יותר. הגבולות הם scale * growth_factori, for i=0,1,2,...,N. מידע נוסף על דליים אקספוננציאליים זמין בהפניית ה-API.

  • מפורש: אתם מפרטים את כל הגבולות של הדליים במערך bounds. הגבולות של קטגוריית i הם:

    Upper bound: bounds[*i*] for (0 <= *i* < *N*-1)
Lower bound: bounds[*i* - 1] for (1 <= *i* < *N*)

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

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

המסוף

תפריט המשנה Histogram buckets נפתח כשיוצרים מדד של התפלגות ולוחצים על More בטופס Metric editor. טופס המשנה הבא מיועד לפריסת קטגוריות לינארית:

קטגוריות בהיסטוגרמה

קטגוריות לינאריות: ממלאים את טופס הקטגוריות של ההיסטוגרמה באופן הבא.

  • סוג: ליניארי
  • ערך התחלה (a): הגבול התחתון של הדלי הסופי הראשון. הערך הזה נקרא offset ב-API.
  • מספר הדליים (N): מספר הדליים הסופי. הערך חייב להיות גדול מ-0 או שווה לו.
  • רוחב הקטגוריה (b): ההפרש בין הגבול העליון לגבול התחתון בכל קטגוריה סופית. הערך חייב להיות גדול מ-0.

לדוגמה, אם ערך ההתחלה הוא 5, מספר הקטגוריות הוא 4 ורוחב הקטגוריה הוא 15, טווחי הקטגוריות הם:

(-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)

קטגוריות מפורשות: ממלאים את הטופס של קטגוריות ההיסטוגרמה באופן הבא:

  • סוג: מפורש
  • גבולות (b): רשימה מופרדת בפסיקים של ערכי הגבולות של הדליים הסופיים. הערך הזה קובע גם את מספר הדליים ואת הרוחב שלהם.

לדוגמה, אם רשימת הגבולות היא:

0, 1, 2, 5, 10, 20

אז יש חמש קטגוריות סופיות עם הטווחים הבאים:

(-INF, 0), [0, 1), [1, 2), [2,5), [5, 10), [10, 20), [20, +INF)

תאים אקספוננציאליים: ממלאים את הטופס של תאי ההיסטוגרמה באופן הבא:

  • סוג: מעריכי

  • מספר הדליים (N): המספר הכולל של הדליים הסופיים. הערך חייב להיות גדול מ-0.

  • סולם לינארי (א): הסולם הלינארי של הדליים. הערך חייב להיות גדול מ-0.

  • גורם הגידול האקספוננציאלי (b): גורם הגידול האקספוננציאלי של הקטגוריות. הערך חייב להיות גדול מ-1.

לדוגמה, אם N=4,‏ a=3 ו-b=2, טווחי הדלי הם:

(-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)

מידע נוסף על קטגוריות ביומן מופיע במאמר BucketOptions ב-Cloud Monitoring API.

API

פריסת הקטגוריה האופציונלית מצוינת בשדה bucketOptions באובייקט LogMetric שמועבר אל projects.metrics.create. לעיון באובייקט LogMetric המלא, אפשר לעבור אל יצירת מדד הפצה בדף הזה. התוספות לפריסות של דליים הן כמו שמוצג:

קטגוריות לינאריות:

{ # LogMetric object
  ...
  bucketOptions: {
    linearBuckets: {
      numFiniteBuckets: 4,
      width: 15,
      offset: 5
    }
  },
  ...
}

בדוגמה הקודמת נוצרות הקטגוריות הבאות:

(-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF)

קטגוריות מפורשות: הגבולות מפורטים בנפרד.

{ # LogMetric object
  ...
  bucketOptions: {
    explicitBuckets: {
      bounds: [0, 1, 2, 5, 10, 20 ]
    }
  },
  ...
}

בדוגמה הקודמת נוצרות הקטגוריות הבאות:

(-INF, 0), [0, 1), [1, 2), [2, 5), [5, 10), [10, 20), [20, +INF)

קטגוריות אקספוננציאליות: הגבולות הם scale * growthFactor ^ i, ‏ ל-i=0,1,2, ..., numFiniteBuckets

{ # LogMetric object
  ...
  bucketOptions: {
    exponentialBuckets: {
      numFiniteBuckets: 4,
      growthFactor: 2,
      scale: 3
    }
  },
  ...
}

בדוגמה הקודמת נוצרות הקטגוריות הבאות:

(-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF)

זמן האחזור של המדד החדש

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

בדיקת מדדי ההפצה

כדי להציג את רשימת המדדים מבוססי-היומן שהוגדרו על ידי המשתמש בפרויקט Google Cloud או כדי לבדוק מדד מסוים בפרויקט Google Cloud :

המסוף

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

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

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

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

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

gcloud

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

gcloud logging metrics list

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

gcloud logging metrics describe METRIC_NAME

כדי לקבל עזרה, משתמשים בפקודה הבאה:

gcloud logging metrics --help

אי אפשר לקרוא נתונים של סדרת זמן של מדד מ-Google Cloud CLI.

API

רשימת מדדים

כדי להציג את המדדים מבוססי-היומן שהוגדרו על ידי המשתמש בפרויקט Google Cloud , משתמשים בשיטת ה-API‏ projects.metrics.list. ממלאים את הפרמטרים של השיטה באופן הבא:

  • ‫parent: שם המשאב של Google Cloud הפרויקט: projects/PROJECT_ID.
  • ‫pageSize: המספר המקסימלי של התוצאות.
  • ‫pageToken: אחזור הדף הבא של התוצאות. מידע על השימוש באסימוני דפים זמין במאמר projects.metrics.list.

אחזור הגדרות של מדדים

כדי לאחזר מדד יחיד מבוסס-יומן שהוגדר על ידי המשתמש, משתמשים ב-method ‏projects.metrics.get של API. ממלאים את הפרמטרים של השיטה באופן הבא:

  • ‫metricName: שם המשאב של המדד:

    projects/PROJECT_ID/metrics/METRIC_ID

קריאת נתוני מדדים

כדי לקרוא את נתוני סדרת הזמנים במדד מבוסס-יומן, משתמשים ב-projects.timeseries.list ב-Cloud Monitoring API. לפרטים על נתוני סדרות זמנים, ראו קריאת סדרות זמנים.

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

logging.googleapis.com/user/METRIC_ID

עדכון מדדי ההפצה

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

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

כדי לערוך מדד מבוסס-יומן:

המסוף

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

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

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

  2. לוחצים על עריכת מדד בתפריט של המדד מבוסס-היומן שרוצים לשנות.

  3. לשנות את הפריטים המותרים במדד.

  4. לוחצים על עדכון המדד.

gcloud

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

gcloud logging update METRIC_NAME \
  --description="METRIC_DESCRIPTION" \
  --log-filter="FILTER" \
  --bucket-name=BUCKET_NAME

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

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

gcloud logging update METRIC_NAME --config-from-file FILENAME

לפרטים נוספים, משתמשים בפקודה הבאה:

gcloud logging metrics update --help

API

כדי לערוך מדד שמבוסס על יומן, משתמשים ב-method‏ projects.metrics.update ב-API. מגדירים את השדות באופן הבא:

  • ‫metricName: שם המשאב המלא של המדד:

    projects/PROJECT_ID/metrics/METRIC_ID

    לדוגמה:

    projects/my-gcp-project/metrics/my-error-metric

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

מחיקת מדדי הפצה

כדי למחוק מדד מבוסס-יומן שהוגדר על ידי המשתמש:

המסוף

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

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

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

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

    לחלופין, לוחצים על מחיקת מדד בתפריט של המדד מבוסס-היומן שרוצים למחוק.

gcloud

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

gcloud logging metrics delete METRIC_NAME

לפרטים נוספים, משתמשים בפקודה הבאה:

gcloud logging metrics delete --help

API

כדי למחוק מדד מבוסס-יומן שהוגדר על ידי המשתמש, משתמשים ב-method ‏projects.metrics.delete ב-API.

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