מסננים של Cloud Trace

מסנני Cloud Trace מאפשרים לשלוח שאילתה ל-method של Trace API‏ list כדי לאחזר רק עקבות שתואמים לקריטריונים ספציפיים, כמו שמות של span, חביון מינימלי, מאפייני HTTP או תוויות.

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

סקירה כללית של המסננים

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

+span:/modules.GetNumInstances latency:1s

כל ההשוואות של מחרוזות הן תלויות-רישיות.

מאפיינים בוליאניים

כדי לציין ערכים למאפיינים בוליאניים, משתמשים ב-false לערך false וב-true לערך true:

Client:true

תווים מיוחדים

אפשר לספק ערכים פשוטים, כלומר ערכים שתואמים לביטוי הרגולרי [a-zA-Z0-9./_][a-zA-Z0-9./_-]*, בלי מירכאות:

environment:production
path:/index.html
error_code:200

ערכים שכוללים תווים אחרים, כולל רווח לבן, צריכים להיות מוקפים במירכאות כפולות ("):

my-label:"Notice: This value contains spaces and a colon"

כדי לחפש את תו המירכאות הכפולות או את תו הלוכסן ההפוך (\) בתוך מחרוזת שמוקפת במירכאות, צריך להוסיף לוכסן הפוך לפני התו:

my-label:"Notice: This value contains spaces, a colon, a \"quote\", and a backslash (\\)"

תחביר של מסננים

בדף הזה, NAME מתייחס לשם של שדה, ו-VALUE מתייחס לערך של צמד מפתח/ערך. המחרוזות _PREFIX ו-_EXACT הן אינדיקציות חזותיות שמראות אם הבדיקה היא בדיקת קידומת או התאמה מדויקת. לדוגמה, root:[NAME_PREFIX] אומר ששם ה-span הבסיסי חייב להתחיל ב-[NAME_PREFIX].

בהמשך הדף מוסבר על תחביר המסננים של Trace API.

דוגמאות למסנני בקשות

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

root:[NAME_PREFIX]

השם של ה-root-span ב-trace חייב להתחיל ב-‎[NAME_PREFIX]‎. לדוגמה, המסנן הבא מתאים למעקב בשם "/_ah/background", אבל לא למעקב בשם "/_ahx/background":

root:/_ah/
+root:[NAME]

השם של ה-root-span ב-trace חייב להיות [NAME], בדיוק. לדוגמה:

+root:/_ah/background
[NAME_PREFIX]

התחביר הזה הוא קיצור דרך ל-root:[NAME_PREFIX].

+[NAME]

התחביר הזה הוא קיצור דרך ל-+root:[NAME].

span:[NAME_PREFIX]

המעקב צריך לכלול לפחות יחידה לוגית למעקב אחת שהשם שלה מתחיל ב-‎[NAME_PREFIX]‎. לדוגמה:

span:/modules.
+span:[NAME]

למעקב חייב להיות לפחות span אחד שהשם שלו הוא בדיוק [NAME]. לדוגמה:

+span:/modules.GetNumInstances
latency:[DURATION]

ההשהיה הכוללת של המעקב צריכה להיות גדולה מ-[DURATION] או שווה לה. המשך מוצג כמספר שלם ואחריו יחידת זמן: s לשניות, ms לאלפיות השנייה או ns לננו-שניות. אם לא מציינים יחידה, היחידות הן אלפיות השנייה. לדוגמה, ארבעת משכי הזמן הבאים זהים:

12s 12000ms 12000000ns 12000
label:[LABEL_KEY]

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

label:/http/url
[LABEL_KEY]:[VALUE_PREFIX]

המעקב חייב להכיל בדיוק את מפתח התווית שצוין, והערך של התווית חייב להתחיל ב-‎[VALUE_PREFIX]‎. לדוגמה, המונח הבא תואם למעקבים שגרסת App Engine שלהם מתחילה ב-"2017":

g.co/gae/app/module_version:2017
+[LABEL_KEY]:[VALUE_EXACT]

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

+g.co/gae/app/module_version:201750925t173233.387410594824284458
method:[VALUE_PREFIX]

התחביר הזה הוא קיצור דרך לבדיקת התווית /http/method:[VALUE_PREFIX].

+method:[VALUE_EXACT]

התחביר הזה הוא קיצור דרך לבדיקת התווית +/http/method:[VALUE_EXACT].

url:[VALUE_PREFIX]

התחביר הזה הוא קיצור דרך לבדיקת התווית /http/url:[VALUE_PREFIX].

+url:[VALUE_EXACT]

התחביר הזה הוא קיצור דרך לבדיקת התווית +/http/url:[VALUE_EXACT].

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

כדי להגביל את מונח החיפוש רק ליחידה הלוגית למעקב הבסיסית, מוסיפים סמן טקסט (^) לפני מונח החיפוש ואחרי סימן הפלוס האופציונלי (+). בשדה מסנן בדף Trace Explorer, אם מוסיפים את האנוטציה +^, היא מומרת ל-^+ כשלוחצים על Enter.

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

^label:[LABEL_KEY]
זהו חיפוש של טווח בסיסי עבור label:[LABEL_KEY].
^[LABEL_KEY]:[VALUE_PREFIX]
זהו חיפוש של טווח בסיסי עבור [LABEL_KEY]:[VALUE_PREFIX].
+^[LABEL_KEY]:[VALUE]
זהו חיפוש של טווח בסיסי עבור +[LABEL_KEY]:[VALUE].
^method:[VALUE_PREFIX]
זהו חיפוש של טווח בסיסי עבור method:[VALUE_PREFIX].
+^method:[VALUE]
זהו חיפוש של טווח בסיסי עבור +method:[VALUE].
^url:[VALUE_PREFIX]
זהו חיפוש של טווח בסיסי עבור url:[VALUE_PREFIX].
+^url:[VALUE]
זהו חיפוש של טווח בסיסי עבור +url:[VALUE].
^span:[NAME_PREFIX]
‫
This is equivalent to root:[NAME_PREFIX].
+^span:[NAME]
הביטוי הזה שווה ל-+root:[NAME].

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

+^url:/main /images method:200

מתאים למעקב אחרי פעולות כשהתווית של יחידה לוגית למעקב הבסיסית /http/url היא בדיוק ‎/main, השם של יחידה לוגית למעקב הבסיסית מתחיל ב-/images, ולכל יחידה לוגית למעקב יש את התווית /http/method עם ערך של 200.

פתרון בעיות

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

ביצועים איטיים

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

אין תוצאות

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

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

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

  • כדי לבדוק את מונחי הסינון אחד בכל פעם, עוברים אל שיטת ה-API‏ list ומשתמשים ב-APIs Explorer. אם אחד מהמונחים לא מחזיר תוצאות, יכול להיות שהמונח הזה הוא הסיבה לכך שלא מוחזרים נתונים.

    הכלי APIs Explorer פתוח כשהחלונית עם הכותרת Try this method מוצגת בדף. אם צריך, לוחצים על Try it (ניסיון), ואז נפתח הכלי APIs Explorer.