מסננים של Cloud Trace

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

הדף לא רלוונטי לדף 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] אומר ששם ה-root span חייב להתחיל ב-[NAME_PREFIX].

בהמשך הדף מופיע תיאור של מסננים לשימוש ב-Cloud 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]

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

span:/modules.
+span:[NAME]

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

span:/modules.GetNumInstances
latency:[DURATION]

השהייה הכוללת של ה-trace צריכה להיות גדולה מ-[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].

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

כדי להגביל את מונח החיפוש רק ליחידה הלוגית למעקב הבסיסית, מוסיפים (^) לפני מונח החיפוש ואחרי האופציונלי (+). בשדה מסנן בדף יומן מעקב 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]
הפונקציה הזו שוות ערך לפונקציה 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.