יצירה וניהול של משתנים ומסננים מוצמדים

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

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

במאמר הזה מוסבר איך ליצור משתנים ומסננים מוצמדים במסוף Google Cloud . מידע על השימוש ב-Cloud Monitoring API זמין במאמר יצירה וניהול של מרכזי בקרה באמצעות API: מסנני מרכזי בקרה.

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

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

מידע על מסננים מוצמדים

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

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

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

לדוגמה, נניח שמוסיפים את המסנן המוצמד cluster_name: mycluster. לאחר מכן, בתרשימים יוצגו באופן אוטומטי רק סדרות הזמן שיש להן תווית cluster_name עם הערך mycluster. באופן דומה, השאילתות בווידג'טים של חלונית היומנים ישונו ל-resource.labels."cluster_name"="mycluster", ובתרשימים יוצגו באופן אוטומטי רק סדרות הזמן שכוללות את התווית במסנן המוצמד.
המסנן המוצמד לא נלקח בחשבון בווידג'ט אם הווידג'ט כולל מסנן עם אותו מפתח תווית, או אם הנתונים שמוצגים בווידג'ט לא כוללים את מפתח התווית שצוין במסנן המוצמד.

מידע על משתנים

למשתנה יש שם וסוג. משתנה מוחל על ווידג'ט מסוים על ידי שינוי השאילתה שהווידג'ט מכיל. מידע על המבנה של מסנן זמין במאמר DashboardFilter.

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

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

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

יש שלושה סוגים של משתנים עם ערך בלבד: Custom,‏ Text Input ו-SQL Query.
- מותאם אישית: משתמשים באפשרות הזו כשרוצים לפרט את רשימת כל הערכים האפשריים וגם להגדיר ערך ברירת מחדל אחד או יותר. לדוגמה, אפשר להגדיר את רשימת כל הערכים האפשריים כ-prod, staging, dev ולהגדיר את ערך ברירת המחדל כ-prod.
- הזנת טקסט: משתמשים באפשרות הזו כשלא יודעים את כל הערכים האפשריים. לדוגמה, יכול להיות שתרצו לסנן לפי כתובת URL, אבל כשתיצרו את המשתנה לא תדעו את הרשימה המדויקת של כתובות ה-URL. אחר כך, כשתשתמשו בתפריט המסננים של הווידג'ט, תוכלו להזין כתובות URL חדשות ולשמור את השינויים עבור ההפעלה הנוכחית או בהגדרת המשתנה.
- שאילתת SQL: משתמשים באפשרות הזו כשרוצים ליצור את רשימת הערכים האפשריים באמצעות שאילתת SQL. המשתנים האלה מיועדים להחלה על תרשימים שנוצרו באמצעות Log Analytics.
  
  לגבי המשתנים האלה, צריך לוודא שתוצאת השאילתה היא טבלה עם עמודה אחת, שסוג הנתונים של העמודה הזו הוא מחרוזת, וכל שורה בטבלה מכילה ערך מחרוזת ייחודי:
```
SELECT log_name
FROM `VIEW`
GROUP BY log_name
```
  שאילתת ה-SQL לא יכולה להיות תלויה במשתנה.

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

עדכון השאילתה של ווידג'ט
הגדרת החשיפה של ווידג'ט

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

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

כדי לקבל את ההרשאות שנדרשות להוספה או לשינוי של משתנים או מסננים מוצמדים באמצעות מסוף Google Cloud , צריך לבקש מהאדמין להקצות לכם בפרויקט את תפקיד ה-IAM‏ Monitoring Editor (roles/monitoring.editor). להסבר על מתן תפקידים, קראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

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

יצירה של מסנן והצמדה שלו

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

במסוף Google Cloud , עוברים לדף Dashboards:
מעבר אל מרכזי בקרה

אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Monitoring.
בסרגל הכלים של מסוף Google Cloud , בוחרים את הפרויקט הרלוונטי ב- Google Cloud . בהגדרות של מרכז האפליקציות, בוחרים את פרויקט המארח או את פרויקט הניהול של מרכז האפליקציות.
בוחרים לוח בקרה, עוברים לסרגל הכלים של לוח הבקרה ולוחצים על הגדרות.
בקטע Filters (מסננים), לוחצים על Add a filter (הוספת מסנן).
לוחצים על תווית ובוחרים תווית. לדוגמה, אפשר לבחור באפשרות zone.
כדי לאפשר למשתמש לבחור כמה ערכים בתפריט הערכים של המשתנה, בוחרים באפשרות בחירה מרובה. אם האפשרות בחירה מרובה לא מופעלת, המשתמשים יכולים לבחור רק אפשרות אחת מתוך תפריט הערכים.
לוחצים על ערך ברירת מחדל ואז בוחרים את ערך ברירת המחדל או הערכים של התווית. כדי להתאים את כל הערכים, בוחרים באפשרות *.

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

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

יצירת משתנה

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

במסוף Google Cloud , עוברים לדף Dashboards:
מעבר אל מרכזי בקרה

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

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

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

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

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

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

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

כדי לנהל את הערך של משתנה באמצעות ווידג'ט במרכז הבקרה:

במסוף Google Cloud , עוברים לדף Dashboards:
מעבר אל מרכזי בקרה

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

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

הגדרת החשיפה של ווידג'ט

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

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

כדי להגדיר את החשיפה של ווידג'ט:

במסוף Google Cloud , עוברים לדף Dashboards:
מעבר אל מרכזי בקרה

אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Monitoring.
בוחרים מרכז שליטה.
עוברים לסרגל הכלים של הווידג'ט שרוצים להגדיר את הנראות שלו, ואז לוחצים על עריכה.
בחלונית Display (תצוגה), מרחיבים את Widget visibility (חשיפת הווידג'ט).
בוחרים משתנה ומשלימים את תיבת הדו-שיח.

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

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

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

מגבלות

המגבלות הבאות חלות כשמגדירים את רמת החשיפה של ווידג'ט:

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

עדכון השאילתה של ווידג'ט

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

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

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

תחביר כללי לביטול ההפניה למשתנה
ווידג'טים בחלונית היומנים
תרשימים עם שאילתות PromQL
תרשימים עם שאילתות SQL
תרשימים עם שאילתות של מסנני מעקב

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

יצירה של מסננים ומשתנים

המסוף

במסמכים הבאים מוסבר איך משתמשים במסוף Google Cloud כדי ליצור מסננים ומשתנים מוצמדים:

API

כדי להגדיר מסננים ומשתנים מוצמדים, משתמשים במבנה הנתונים dashboardFilters.

כדי ליצור משתנה, מגדירים את הערך של השדה templateVariable לשם המשתנה. כדי ליצור מסנן מוצמד, משמיטים את השדה הזה או מגדירים את הערך למחרוזת ריקה.
כדי ליצור מסנן מוצמד או משתנה שמבוסס על תווית, צריך לציין את השדה labelKey. משמיטים את השדה הזה כשרוצים משתנה עם ערך בלבד.
מגדירים את ערך ברירת המחדל של המסנן או המשתנה. ההגדרה של השדה הזה קובעת אם המשתמש יכול לבחור בדיוק אפשרות אחת מתוך תפריט הערכים, או אם הוא יכול לבחור כמה ערכים.
- כדי להגדיר ערך ברירת מחדל יחיד ולמנוע מהמשתמשים לבחור יותר מאפשרות אחת בתפריט הערכים, צריך להגדיר את השדה valueType כ-STRING וגם להגדיר את השדה stringValue:
```
"valueType": "STRING",
"stringValue": "my-default-value",
```
- כדי להגדיר לפחות ערך ברירת מחדל אחד ולאפשר למשתמשים לבחור כמה אפשרויות בתפריט הערכים, צריך להגדיר את השדה valueType כ-STRING_ARRAY ולהגדיר גם את השדה stringArrayValue. בדוגמה הבאה, יש שלושה ערכי ברירת מחדל.
```
"valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},
```
הערה: אם לא מציינים ערך ברירת מחדל, המערכת בוחרת אוטומטית את התו הכללי, (*). אם אתם מתכננים להשתמש במשתנה בחלונית היומנים, אתם צריכים להשתמש בביטוי הרגולרי ככלי השוואה. בשביל שאילתות SQL, צריך להשתמש בהצהרת IF. מידע נוסף זמין במאמר תרשימים עם שאילתות SQL.
אופציונלי: כדי לציין את רשימת כל הערכים האפשריים למשתנה מסוג ערך בלבד, מגדירים את השדה stringArray או את השדה timeSeriesQuery. אם מציינים שאילתה, היא חייבת להיות שאילתת ניתוח נתונים.

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

לדוגמה, אובייקט dashboardFilters הבא:

{
  "dashboardFilters": [
      {
        "labelKey": "zone"
        "stringValue": "us-central1-c",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL"
      },
      {
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL",
        "templateVariable": "my_label_based_variable"
      },
      {
        "filterType": "VALUE_ONLY",
        "templateVariable": "my_value_only_variable",
        timeSeriesQuery: {
          opsAnalyticsQuery: {
            sql: "
              SELECT log_name
              FROM `MY_TABLE`
              GROUP BY log_name
            ",
          }
        }
      }
    ],
  "displayName": "Illustrate Variables",
  ...
}

קובץ ה-JSON הקודם מגדיר מסנן מוצמד אחד ושני משתנים:

למסנן המוצמד יש מפתח תווית zone, שמוצג בסרגל הכלים. בשדות valueType ו-stringValue מצוין ערך ברירת המחדל היחיד. מידע נוסף מופיע בדף הפניות ל-API בנושא מבנה הנתונים של dashboardFilters.
למשתנה מבוסס-התוויות יש את השם my_label_based_variable, ומפתח התווית שלו הוא instance_id. ערך ברירת המחדל של המשתנה הזה מוגדר למזהה ספציפי של מופע. אפשר גם להגדיר את ערך ברירת המחדל באמצעות מערך. בסרגל הכלים, המסנן מוצג עם השם my_label_based_variable.
המשתנה עם הערך בלבד נקרא my_value_only_variable. במאפיין הזה לא מציינים ערך ברירת מחדל, ולכן מוחל באופן אוטומטי האופרטור של התו הכללי לחיפוש, (*). בנוסף, המשתנה הזה משתמש בשאילתת SQL כדי ליצור את רשימת הערכים האפשריים של המשתנה.

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

תחביר כללי לביטול ההפניה למשתנה

לכל הווידג'טים, חוץ מאלה שמוגדרים על ידי SQL, משתמשים בתחביר הבא כדי להחיל משתנה על שאילתה:

כדי להחיל משתנה מבוסס-תווית ולפתור את מפתח התווית ואת ערך התווית לביטוי מסנן תקין בשפת השאילתות, משתמשים ב-${my_label_based_variable}.
כדי להחיל רק את הערך של משתנה מבוסס-תווית, משתמשים ב-${my_label_based_variable.value}. ההשוואה חייבת להתבצע באמצעות ביטוי רגולרי.
כדי להחיל רק את הערך של משתנה מסוג value-only, משתמשים בפונקציה ${my_value_only_variable}. למשתנים שהם רק ערכים, לא צריך לכלול פסקה של .value. ההשוואה חייבת להתבצע באמצעות ביטוי רגולרי.

ווידג'טים של חלונית היומנים

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

המסוף

לדוגמה, בשאילתה הבאה נעשה שימוש בביטוי רגולרי כדי להשוות בין הערך של השדה jsonPayload.message לבין ערך מחרוזת שכולל את הערך של משתנה מבוסס-תווית:

jsonPayload.message=~"Connected to instance: ${my_label_based_variable.value}"

דוגמה נוספת: נניח שיש משתנה עם ערך בלבד, value_only_severity_variable, ושבתפריט הערכים נבחרו שלושה ערכים: ERROR,‏ INFO ו-NOTICE. בשלב הבא, מוסיפים את הרכיבים הבאים לחלונית השאילתות של הווידג'ט של חלונית היומנים:

severity =~ "${value_only_severity_variable}"

האיור הבא מציג את הטופס שעבר רינדור:

severity =~ "^(ERROR|INFO|NOTICE)$"

API

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

"logsPanel": {
  "filter": "${my_label_based_variable}",
  "resourceNames": [
    "projects/1234512345"
  ]
},

"logsPanel": {
  "filter": "resource.type=\"gce_instance\"\n
             resource.labels.project_id=~\"${my_label_based_variable.value}\"\n",
  "resourceNames": [
    "projects/012345"
  ]
}

דוגמה נוספת: נניח שיש משתנה עם ערכים בלבד, value_only_severity_variable, ושלושה ערכים נבחרו בתפריט: ERROR, INFO ו-NOTICE. בשלב הבא, מוסיפים את הרכיבים הבאים לחלונית השאילתות של הווידג'ט של חלונית היומנים:

"logsPanel": {
  "filter": "severity =~ \"${value_only_severity_variable}\"\n",
  ...
}

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

severity =~ "^(ERROR|INFO|NOTICE)$"

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

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

תחביר	הערך שנבחר	ביטוי בחלונית היומנים שנפתר
`${my_label_based_variable}`	`12345`	`resource.labels."instance_id"="12345"` משתנה הדוגמה מבוסס על תווית המשאב `instance_id`.
`${my_label_based_variable}`	`*`	`""`
`${my_label_based_variable.value}` `${my_value_based_variable}`	`12345`	`12345`
`${my_label_based_variable.value}` `${my_value_based_variable}`	`*`	`.*`

תרשימים עם שאילתות PromQL

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

המסוף

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

compute_googleapis_com:instance_cpu_utilization{
    monitored_resource="gce_instance", ${my_label_based_variable} }

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

compute_googleapis_com:instance_cpu_utilization{
    instance_id=~"${my_label_based_variable.value}"
}

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

zone=~"${my_value_only_variable}"

API

לדוגמה, קטע ה-JSON הבא ממחיש שאילתה שמסתמכת על המשתנה מבוסס התווית, my_label_based_variable, שמומר לביטוי סינון:

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
      monitored_resource=\"gce_instance\",
      ${my_label_based_variable}
      }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
    monitored_resource=\"gce_instance\",
    instance_id=~\"${my_label_based_variable.value}\"
    }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

zone=~\"${my_value_only_variable}\"

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

תחביר	הערך שנבחר	ביטוי PromQL שנפתר
`${my_label_based_variable}`	`12345`	`instance_id == '12345'` משתנה הדוגמה מבוסס על תווית המשאב `instance_id`.
`${my_label_based_variable}`	`*`	`noop_filter=~".*"`
`${my_label_based_variable.value}` `${my_value_based_variable}`	`12345`	`12345`
`${my_label_based_variable.value}` `${my_value_based_variable}`	`*`	`.+`

תרשימים עם שאילתות SQL

יש שני מקומות שבהם אפשר להשתמש במשתנים בשאילתות SQL:

הסעיף FROM יכול להיות תלוי במשתנה שהוגדר על ידי המערכת בשם @__project_id, שמוביל לערך של הפרויקט שנבחר.
הפסקה WHERE יכולה להיות תלויה במשתנים שמוגדרים על ידי המשתמש.

עדכון הסעיף FROM כך שיהיה תלוי במשתנה שמוגדר על ידי המערכת

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

בדוגמה הבאה מוצג סעיף FROM שתלוי במשתנה שמוגדר על ידי המערכת:

FROM `@__project_id.global._Default._Default`

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

עדכון סעיף WHERE כך שיהיה תלוי במשתנה שהוגדר על ידי המשתמש

בקטע הזה מוסבר איך לעדכן את הסעיף WHERE של ווידג'ט שמוגדר באמצעות SQL, כך שהוא יהיה תלוי במשתנה שהוגדר על ידי המשתמש. לכל המשתנים, מוסיפים לפני שם המשתנה את הסימן @, לדוגמה: @variable_name. למשתנים מבוססי-תוויות, מוסיפים את הערך .value לשם המשתנה, @my_label_based_variabe.value.

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

המסוף

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

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

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

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

מומלץ להשתמש בהצהרה IF שמוצגת בדוגמאות הקודמות, כי SQL לא מפרש את האופרטור של התו הכללי לחיפוש כ'כל ערך'. לכן, אם לא תכללו את ההצהרה IF ואם תבחרו בתו כללי, תוצאת השאילתה תהיה טבלה ריקה. בדוגמה השנייה, הפונקציה UNNEST ממירה את המערך לטבלה.

כדי להוסיף סעיף WHERE בפורמט תקין:

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

לדוגמה, נניח שיוצרים משתנה בשם LogName שמפיק רשימה של שמות יומנים ומציג את התוצאה בטבלה עם עמודה אחת בשם log_name. לאחר מכן יוצרים תרשים, בוחרים באפשרות הוספת מסנן משתנה ובוחרים במשתנה LogName. נוצר הקוד הבא:
```
WHERE IF(@LogName = '*', TRUE, LogName = @LogName)
```
בדוגמה הזו, צריך לערוך את הקוד שנוצר ולהחליף את LogName = ב-log_name =, כדי שאפשר יהיה לבצע את צירוף הטבלה:
```
WHERE IF(@LogName = '*', TRUE, log_name = @LogName)
```
לוחצים על הפעלה ואז על אישור.
כדי לשמור את מרכז הבקרה ששיניתם, בסרגל הכלים לוחצים על שמירה.

API

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

לדוגמה, כאן מוצג ייצוג חלקי של תרשים ב-JSON שמציג את התוצאות של שאילתת SQL. כדי לתמוך בסינון התוצאות לפי שם יומן, נוסף סעיף WHERE שמפנה למשתנה בשם LogName:

"plotType": "STACKED_BAR",
"targetAxis": "Y1",
"timeSeriesQuery": {
  "opsAnalyticsQuery": {
    "queryExecutionRules": {},
    "queryHandle": "",
    "sql": "SELECT\n timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload\n
            FROM\n `my-project.global._Default._Default`\n
            WHERE \n IF (@LogName = \"*\", TRUE, log_name=@LogName)\nLIMIT 10000"
  }
}

המשתנה LogName גם מנפיק שאילתה כדי לקבוע את רשימת שמות היומנים האפשריים:

"dashboardFilters": [
  {
    "filterType": "VALUE_ONLY",
    "templateVariable": "LogName",
    "valueType": "STRING",
    "timeSeriesQuery": {
      "opsAnalyticsQuery": {
        "savedQueryId": "",
        "sql": "SELECT log_name FROM `my-project.global._Default._Default` GROUP BY log_name LIMIT 1000",
        "queryHandle": ""
      },
      "unitOverride": "",
      "outputFullDuration": false
    }
  }
],

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

תרשימים עם שאילתות סינון של Monitoring

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

המסוף

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

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

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

לדוגמה, קטע ה-JSON הבא ממחיש שאילתה שמסתמכת על משתנה מבוסס-תווית, my_label_based_variable, שמומר לביטוי סינון:

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance" ${my_label_based_variable}"

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

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance"
resource.label."zone"=monitoring.regex.full_match(${my_value_only_variable})

API

לדוגמה, קטע ה-JSON הבא ממחיש שאילתה שמסתמכת על משתנה מבוסס-תווית, my_label_based_variable, שמומר לביטוי סינון:

"timeSeriesQuery": {
  "timeSeriesFilter": {
    "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
               resource.type=\"gce_instance\"
               ${my_label_based_variable} ",
    "aggregation": {
      "alignmentPeriod": "60s",
      "perSeriesAligner": "ALIGN_MEAN",
      "groupByFields": []
    }
  },
  "unitOverride": "",
  "outputFullDuration": false
},

ווידג'טים שמשתמשים בשאילתה בצורה של מסנן Monitoring לא יכולים לסנן את סדרת הזמן לפי הערך במשתנים מבוססי-תוויות, אבל הם יכולים לסנן לפי משתנים מבוססי-ערכים בלבד. לדוגמה, השאילתה הבאה מציגה את השדה "filter" של שאילתה שמסוננת לפי zone, על סמך הערך של משתנה שמכיל ערך בלבד:

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
          resource.type=\"gce_instance\"
          resource.labels.\"zone\"=monitoring.regex.full_match(${my_value_only_variable})"

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

תחביר	הערך שנבחר	ביטוי סינון שנפתר
`${my_label_based_variable}`	`12345`	`resource.instance_id == "12345"` משתנה הדוגמה מבוסס על תווית המשאב `instance_id`.
`${my_label_based_variable}`	`*`	הושמט
`${my_label_based_variable.value}`	`12345`	לא נתמך
`${my_label_based_variable.value}`	`*`	לא נתמך
`${my_value_based_variable}`	`12345`	`"12345"`
`${my_value_based_variable}`	`*`	`".*"`

שינוי של מסנן או משתנה מוצמדים

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

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

כדי לשנות את ההגדרה של מסנן מוצמד או של משתנה:

במסוף Google Cloud , עוברים לדף Dashboards:
מעבר אל מרכזי בקרה

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

מחיקת מסנן או משתנה מוצמדים

כדי למחוק מסנן מוצמד או משתנה:

במסוף Google Cloud , עוברים לדף Dashboards:
מעבר אל מרכזי בקרה

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

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

מידע על מסננים מוצמדים

מידע על משתנים

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

יצירה של מסנן והצמדה שלו

יצירת משתנה

הוספת ווידג'ט לניהול הערך של משתנה

הגדרת החשיפה של ווידג'ט

מגבלות

עדכון השאילתה של ווידג'ט

יצירה של מסננים ומשתנים

המסוף

API

תחביר כללי לביטול ההפניה למשתנה

ווידג'טים של חלונית היומנים

המסוף

API

תרשימים עם שאילתות PromQL

המסוף

API

תרשימים עם שאילתות SQL

המסוף

API

תרשימים עם שאילתות סינון של Monitoring

המסוף

API

שינוי של מסנן או משתנה מוצמדים

מחיקת מסנן או משתנה מוצמדים

המאמרים הבאים

יצירה וניהול של משתנים ומסננים מוצמדים