מסנני מעקב

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

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

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

אם אתם לא מכירים את התוויות, כדאי לעיין במאמר תוויות.

שימוש במסננים

אתם יכולים להשתמש במסננים ב-Monitoring API כדי לבצע את הפעולות הבאות:

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

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

בחירת מסננים

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

  • project: מתאים אם המדדים של הפרויקט שצוין גלויים לפרויקט ההיקף של היקף המדדים שמוזכר בפרמטר name.

    משתמשים בבורר project כשפרויקט Google Cloud יכול לראות את המדדים של כמה פרויקטים Google Cloud או חשבונות AWS, ואתם רוצים לראות רק את המדדים של פרויקט אחד. לדוגמה, אם היקף המדדים של Project-A כולל את Project-B, מתרחשת התאמה כשערך המאפיין name הוא Project-A ואתם משתמשים במסנן הבא:

    project = "Project-B"
  • group: התאמה למשאבים ששייכים ל- Group.

    המסנן הבא תואם לקבוצה עם המזהה group-id:

    group.id = "group-id"
        
  • resource: תואם ל משאבים במעקב מסוג מסוים או עם ערכי תוויות מסוימים.

    • המסנן הבא תואם לכל המשאבים שבמעקב שהם מכונות וירטואליות (VM) של Compute Engine:

      resource.type = "gce_instance"
    • המסנן הבא תואם לכל המשאבים שהאזור שלהם מתחיל ב-europe-:

      resource.labels.zone = starts_with("europe-")
  • metric: מתאים ל סוג מדד או סדרת זמן מסוימת עם תווית מסוימת שתואמת לערך ספציפי.

    • המסנן הבא תואם לסוג מסוים של מדד:

      metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    • המסנן הבא תואם לסדרות זמן עם תווית בשם instance_name, שהערך שלה מתחיל ב-gke-hipster או ב-gke-nginx:

      metric.labels.instance_name = monitoring.regex.full_match("gke-(hipster|nginx).*")

בטבלה הבאה מוצגים הסלקטורים שמותרים במסננים על סמך הקריאה ל-Monitoring API:

מטרת הסינון project selector group selector resource selector metric selector
הגדרת קבוצות כן כן*
רשימת חברי הקבוצה כן כן
רשימת פעולות על ציר הזמן כן כן כן yes
רשימת תיאורי מדדים כן כן
רשימת תיאורי משאבים במעקב כן
* לבוחר המשאבים יש אפשרויות נוספות כשמשתמשים בו כדי להגדיר חברות בקבוצה.
כשמפרטים סדרות עיתיות, צריך לציין בדיוק סוג מדד אחד.

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

אחזור נתונים של פעולות על ציר הזמן

Method: projects.timeSeries.list
Filter objects: project, group.id, resource.type, resource.labels.[KEY], metric.type, metric.labels.[KEY]

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

המסנן שצוין לשיטה timeSeries.list חייב לכלול בורר metric, והבורר הזה חייב לציין בדיוק סוג אחד של מדד:

  • כדי להחזיר את כל סדרות הזמן של סוג מסוים של מדד:
    metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    
  • כדי להחזיר את כל סדרות הזמן של קבוצה מסוימת. הבורר group פועל רק עם נתונים של סדרות זמן מיושרות. מידע נוסף זמין במאמר בנושא בורר קבוצות.

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
    group.id = "2468013579"
    
  • כדי לקבל את כל סדרות הזמן ממכונה ספציפית של Compute Engine, משתמשים במסנן הבא:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
    metric.labels.instance_name = "my-instance-name"
    

  • כדי להחזיר את כל סדרות הזמן ממכונות של Compute Engine שהשמות שלהן מתחילים ב-frontend-, משתמשים במסנן הבא:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
    metric.labels.instance_name = starts_with("frontend-")
    

  • כדי להחזיר את כל סדרות הזמן ממכונות של Compute Engine ששמותיהן מתחילים ב-gke-hipster או ב-gke-nginx, משתמשים במסנן הבא:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
    metric.labels.instance_name = monitoring.regex.full_match("^gke-(hipster|nginx).*")
    

הגדרת החברות בקבוצה

Method: projects.groups.create
Filter objects: project, resource.type, resource.labels.key, metadata.system_labels.[KEY], metadata.user_labels.[KEY]

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

לדוגמה, כדי ליצור קבוצה שכוללת רק מופעים של מכונות וירטואליות (VM) של Compute Engine באירופה, משתמשים במסנן הבא:

resource.type = "gce_instance" AND resource.labels.zone = starts_with("europe-")

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

קבוצה של כרטיסי מוצר

Method: projects.groups.members.list
Filter objects: ‏project, ‏ resource.type, ‏ resource.labels.[KEY]

הפרמטר name מציין פרויקט להגדרת היקף של היקף מדדים וקבוצה שהוגדרה באותו פרויקט. אם לא מציינים מסנן, הפונקציה projects.groups.members.list מחזירה רשימה של חברי הקבוצה.

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

לדוגמה, נניח שאתם יוצרים קבוצה שכוללת את כל המשאבים שהשם שלהם מכיל את המחרוזת test. כדי להציג רק את חברי הקבוצה שהם נושאי Pub/Sub, משתמשים במסנן הבא:

resource.type = "pubsub_topic"

תיאורי מדדים של כרטיסי מוצר

Method: projects.metricDescriptors.list
Filter objects: project, metric.type

אפשר להשתמש במסנן כדי להגביל את מתארי המדדים שמאחזרים.

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

metric.type = starts_with("compute.googleapis.com")

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

הצגת תיאורי משאבים במעקב

Method: projects.monitoredResourceDescriptors.list
Filter objects: resource.type

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

לדוגמה, כדי לאחזר רק את תיאורי המשאבים המפוקחים של Pub/Sub, משתמשים במסנן הבא:

resource.type = starts_with("pubsub")

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

דוגמאות

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

    # Metric descriptor:
    { "name": "projects/my-project-id/metricDescriptors/compute.googleapis.com%2Finstance%2Fdisk%2Fread_bytes_count"
      "type": "compute.googleapis.com/instance/disk/read_bytes_count",
      "labels": [ { "key": "device_name",
                    "description": "The name of the disk device." } ] }

    # Monitored resource descriptor:
    {  "name": "monitoredResourceDescriptors/gce_instance"
       "type": "gce_instance",
       "labels": [
         { "key": "instance_id",
           "description": "The instance ID provide by Google Compute Engine." },
         { "key": "zone",
           "description": "The Google Cloud Platform zone hosting the instance."
         } ] }

    # Resource descriptor for a virtual machine instance.
    { "type": "gce_instance",
      "instance_id": "1472038649266883453",
      "zone": "us-east-1b",
      "disks": [ "log_partition" ],
      "machine_type": "n1-standard-2",
      "tags": { "environment": "bleeding-edge",
                "role": "frobulator" },
      "project_id": "my-project-id" }

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

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

metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

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

metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND
metric.labels.device_name = "log_partition"

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

resource.type = "gce_instance" AND
resource.labels.instance_id = "1472038649266883453" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND
metric.labels.device_name = "log_partition"

סינון לפי קבוצות

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

{ "name": "projects/my-test-project/groups/024681012",
  "display_name": "My Redis Cluster",
  "filter": "metadata.user_labels.role=redis" }

בשיחה עם השיטה projects.timeSeries.list, הבקשה הבאה של המסנן מחזירה את השימוש ברוחב הפס של קריאת הדיסק עבור כל המכונות של Compute Engine בקבוצה מסוימת. הקבוצה צריכה להיות מוגדרת בפרויקט ההיקף של היקף המדדים שצוין בפרמטר name של השיטה:

resource.type = "gce_instance" AND
group.id = "024681012" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

הפניה: תחביר של מסננים

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

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

    <monitoring_filter> ::=  <project_selector> AND
                             <group_selector> AND
                             <resource_selector> AND
                             <metric_selector>

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

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

השוואות

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

  • [OBJECT]: בוחר ערך לבדיקה. אחת מהאפשרויות הבאות:

    project
    group.id
    metric.type
    metric.labels.[KEY]
    resource.type
    resource.labels.[KEY]
    metadata.system_labels.[KEY]
    metadata.user_labels.[KEYSTRING]
        

    ‫[KEY]: שם, למשל zone או instance_id.

    [KEYSTRING] יכול להיות שם, אבל אם הוא מכיל תווים מיוחדים, צריך להוסיף לו מירכאות (").

  • [OPERATOR]: אופרטור השוואה; אחת מהאפשרויות הבאות:

    =            # equality (case-sensitive)
    > < >= <=    # numeric ordering
    !=           # not equal
    :            # "has" substring match and test for key (case-sensitive)
        
  • [VALUE]: ליטרל או בקשה להפעלת פונקציה מובנית; אחת מהאפשרויות הבאות:

    <string>     # "a Unicode string". Don't use apostrophes (`'`) to quote strings.
    <bool>       # true or false
    <number>     # 0, -2, 123456, 3.14156
    <function>   # operators on the right side of '=' or '!=':
                 #   starts_with(<string>)
                 #   ends_with(<string>)
                 #   has_substring(<string> [, ignore_case=false])
                 #   one_of(<string>,...,<string>) for up to 100 strings
                 #   monitoring.regex.full_match(<RE2-string>)
        

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

    • תלוי אותיות רישיות: display_name=has_substring("Demo")
    • תלוי אותיות רישיות: display_name=has_substring("Demo", false)
    • לא תלוי-רישיות: display_name=has_substring("Demo", true)

    כשמשתמשים בשיטה timeSeries.list, נתמך רק הטופס has_substring(<string>).

    המסנן monitoring.regex.full_match מקבל מחרוזת של ביטוי רגולרי בתחביר של RE2.

אפשר להשתמש באופרטורים הבאים כדי לקבץ או לשנות השוואות. OR יש עדיפות גבוהה יותר על AND. האופרטורים צריכים להיות כתובים באותיות רישיות:

(...)        # grouping comparisons
AND          # conjunction (optional but recommended)
OR           # disjunction

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

ההשוואה x = one_of("a", "b", "c") שקולה ל:

(x = "a" OR x = "b" OR x = "c")
אפשר להשתמש באופרטור השלילה האונרי, NOT, לפני השוואה, אבל לא עם אופרטור exists ‏ (:) או לפני ביטוי בסוגריים:

NOT          # negates the following comparison

בחירת מסננים

אפשר להשתמש בבוררים כדי להגביל את הבחירות של המסננים לפריטים מסוימים. בסעיפים הבאים, סוגריים מסולסלים משמשים לציון חזרה. לדוגמה, הסימון <x> {OR <y>} אומר שאפשר לכתוב כל אחת מהאפשרויות הבאות:

<x>
<x> OR <y>
<x> OR <y> OR <y>
<x> OR <y> OR <y> OR <y>
...

בורר הפרויקטים

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

<project_selector> ::= project '=' (<number> | <string>) {OR project '=' (<number> | <string>)}

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

(project=12345 OR project="my-project-id") AND resource.type="gce_instance"

בורר קבוצות

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

<group_selector> ::= group.id '=' <string>

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

group.id = 12345 AND
resource.type = "gce_instance" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

מותר להשתמש בבורר הקבוצות רק במסננים שמועברים לשיטה projects.timeSeries.list. בנוסף, כדי לבחור קבוצה צריך נתונים מיושרים. כלומר, הקריאה projects.timeSeries.list צריכה לכלול ערכים בשדות perSeriesAligner ו-alignmentPeriod. הסיבה לכך היא שהחברות בקבוצה היא בעצמה סוג של סדרת זמנים שצריך לצרף לנתוני המדדים, ואספקת פרמטרים של התאמה מאפשרת לכם לשלוט באופן הצירוף. מידע נוסף על פרמטרים של התאמה זמין במאמר בנושא צבירת נתונים.

בוחר משאבים

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

<resource_selector> ::= <resource_type_expression>
                      | <resource_label_expression>
                      | <resource_type_expression> AND <resource_label_expression>

<resource_type_expression> ::= resource.type '=' <string>
                             | resource.type ':' <string>
                             | resource.type '=' starts_with '(' <string>')'
                             | resource.type '=' ends_with '(' <string> ')'

<r_label_comparison> ::= resource.labels.[KEY] '=' (<string> | <bool>)
                       | resource.labels.[KEY] ':' <string>
                       | resource.labels.[KEY] '=' (starts_with | ends_with) '(' <string> ')'
                       | resource.labels.[KEY] ('=' | '>' | '<' | '>=' | '<=') <number>

<resource_label_expression> ::= <r_label_comparison> {AND <r_label_comparison>}
                              | <r_label_comparison> {OR <r_label_comparison>}

אם משתמשים ביותר מ-<r_label_comparison> בסלקטור, כדאי להוסיף סוגריים מסביב לכולם כדי לשפר את הקריאות. לדוגמה, אפשר להשתמש במסנן הבא כדי להגדיר קבוצה שכוללת את כל המכונות הווירטואליות של Compute Engine בארה"ב ובאירופה.

resource.type = "gce_instance" AND
(resource.labels.zone = starts_with("us-") OR resource.labels.zone = starts_with("europe-"))

בוחר משאבים להגדרות של קבוצות

בוררי המשאבים שמשמשים להגדרת חברות בקבוצה משתמשים בתוספים לתחביר <resource_selector>:

  • אתם כוללים מסננים שמבוססים על הערך של תוויות מערכת של מטא-נתונים, metadata.system_labels.[KEY], ושל תוויות משתמש של מטא-נתונים, metadata.user_labels.[KEYSTRING]. מומלץ להוסיף מרכאות למפתחות של metadata.user_labels כי הם יכולים להכיל תווים מיוחדים כמו מקפים.

    כשסלקטור מכיל מסנן מטא-נתונים ומסנן משאבים, צריך לשלב אותם עם AND. אי אפשר להשתמש ב-OR. לדוגמה, בתרשים עם הבורר הבא מוצג ניצול המעבד של כל המכונות הווירטואליות עם סוג מכונה e2-medium או e2-micro:

    metric.type="compute.googleapis.com/instance/cpu/utilization"
    resource.type="gce_instance" AND
    (metadata.system_labels."machine_type"="e2-medium" OR
    metadata.system_labels."machine_type"="e2-micro")
    
  • אפשר להשתמש באופרטור 'לא שווה' (!=) כדי להשוות בין סוגי משאבים, תוויות משאבים ומטא-נתונים. אפשר להשתמש באופרטור הזה כשמשווים מחרוזות, מספרים, ערכים בוליאניים או פונקציות של מחרוזות משנה. לדוגמה, התנאי resource.type!=starts_with("gce") מתקיים אם סוג המשאב לא מתחיל ב-"gce".

  • אפשר להשתמש באופרטור NOT יחיד לפני השוואת משאבים. לדוגמה, NOT resource.labels.zone="europe" הוא true אם האזור של המשאב לא כולל את "europe". אי אפשר להשתמש ב-NOT לפני אופרטור exists‏ (:) או לפני ביטוי שמוקף בסוגריים.

  • אפשר להשתמש באופרטור 'קיים' (:) כדי לבדוק אם יש מפתחות. לדוגמה, ההשוואה resource.labels:zone מחזירה את הערך true אם מפתח התווית zone קיים במשאב.

לדוגמה, אחד ממפתחות המטא-נתונים של משאבי הפלטפורמה למכונות וירטואליות הוא spot_instance. בדוגמה הבאה, בוחרים מופעים שהם מופעי Spot:

resource.type = "gce_instance" AND metadata.system_labels.spot_instance = true

בורר המדדים

בורר מדדים מציין מדדים מסוימים או תיאורי מדדים על ידי הגבלת סוג המדד ותוויות המדד. כשמשתמשים בבורר המדדים עם השיטה projects.timeSeries.list, צריך לציין בו סוג מדד יחיד:

<metric_selector> ::= <metric_name_expression> [AND <metric_label_expression>]

<metric_name_expression> ::= metric.type '=' <string>
                           | metric.type ':' <string>
                           | metric.type '=' starts_with '(' <string> ')'
                           | metric.type '=' ends_with '(' <string> ')'

<metric_label_comparison> ::= metric.labels.[KEY] '=' <string> | <bool>
                            | metric.labels.[KEY] ':' <string>
                            | metric.labels.[KEY] '=' starts_with '(' <string> ')'
                            | metric.labels.[KEY] '=' ends_with '(' <string> ')'
                            | metric.labels.[KEY] ('=' | '>' | '<' | '>=' | '<=') <number>

<metric_label_expression> ::= <metric_label_comparison> {[AND] <metric_label_comparison>}
                            | <metric_label_comparison> {OR <metric_label_comparison>}

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

metric.type = "cloudsql.googleapis.com/database/state" AND
(metric.labels.resource_type = "instance" AND
 metric.labels.resource_id = "abc-123456")