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