שימוש בכלי המעקב

אתם קוראים את מסמכי התיעוד של Apigee Edge.
למעבר אל מסמכי התיעוד של Apigee X
info

מהו הכלי Trace?

הכלי Trace משמש לפתרון בעיות ולמעקב אחרי שרתי proxy ל-API שפועלים ב-Apigee Edge. בעזרת Trace אפשר לבדוק את הפרטים של כל שלב בתהליך של proxy ל-API.

בסרטון הזה מוצג הכלי Trace.

איך משתמשים ב-Trace

קל להשתמש ב-Trace. מתחילים סשן מעקב, שולחים קריאה ל-API לפלטפורמת Edge וקוראים את התוצאות.

  1. נכנסים לדף proxies ל-API, כמו שמתואר בהמשך.

    Edge

    כדי לגשת לדף שרתי ה-proxy ל-API באמצעות ממשק המשתמש של Edge:

    1. נכנסים ל-apigee.com/edge.
    2. בסרגל הניווט הימני, לוחצים על Develop > proxies ל-API.

    ממשק משתמש חדש של Edge (ענן פרטי)

    כדי לגשת לדף שרתי ה-proxy ל-API באמצעות ממשק המשתמש החדש של Edge:

    1. נכנסים לממשק המשתמש של New Edge בכתובת http://host:3001/edge, כאשר host היא כתובת ה-IP או שם ה-DNS של המארח שמפעיל את ממשק המשתמש של New Edge.
    2. בסרגל הניווט הימני, לוחצים על Develop > proxies ל-API.
  2. בוחרים proxy ל-API בדף API Proxies.
  3. מוודאים שה-API שרוצים לעקוב אחריו פרוס.
  4. לוחצים על Trace כדי לעבור לתצוגה של הכלי Trace.
  5. בתפריט הנפתח Deployment to Trace, בוחרים את סביבת הפריסה ואת גרסת ה-proxy שרוצים לעקוב אחריהן.
  6. לוחצים על Start Trace Session. כשהסשן של Trace פעיל, ה-proxy ל-API מתעד את הפרטים של כל שלב בצינור עיבוד הנתונים. בזמן שהסשן של Trace פועל, הודעות ונתונים לפי הקשר נלכדים מהתנועה בזמן אמת.

  7. אם אין תנועה בזמן אמת שעוברת דרך שרת ה-proxy, פשוט שולחים בקשה ל-API. אתם יכולים להשתמש בכל כלי שתרצו כדי לשלוח את הבקשה, כמו curl,‏ Postman או כל כלי מוכר אחר. אפשר גם לשלוח את הבקשה ישירות מהכלי Trace. פשוט מזינים את כתובת ה-URL ולוחצים על שליחה. הערה: אפשר לשלוח רק בקשת GET מהכלי Trace, ולא בקשת POST.

    הערה: סשן אחד של Trace יכול לתמוך ב-10 טרנזקציות של בקשות/תגובות לכל מעבד בקשות דרך ה-proxy ל-API שנבחר. ב-Edge cloud, עם 2 מעבדי בקשות שמטפלים בתנועה, יש תמיכה ב-20 טרנזקציות של בקשות/תגובות. סשן מעקב נפסק באופן אוטומטי אחרי 10 דקות אם לא מפסיקים אותו ידנית.
  8. אחרי שמתעדים מספר מספיק של בקשות, לוחצים על Stop Trace Session.
  9. רשימה של עסקאות הבקשה/התגובה שנתפסו מוצגת בתפריט הימני. כדי לראות תוצאות מפורטות, לוחצים על אחת מהעסקאות.

איך קוראים מעקב

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

  • במפת העסקאות יש סמלים שמסמנים כל שלב חשוב שמתרחש במהלך עסקה של proxy ל-API, כולל הפעלת מדיניות, שלבים מותנים ומעברים. מעבירים את העכבר מעל סמל כלשהו כדי לראות מידע מסכם. השלבים של תהליך הבקשה מופיעים בחלק העליון של מפת העסקאות, והשלבים של תהליך התגובה מופיעים בחלק התחתון.
  • בקטע phase details בכלי מופיע מידע על העיבוד הפנימי של שרת ה-proxy, כולל משתנים שהוגדרו או נקראו, כותרות של בקשות ותגובות ועוד. לוחצים על סמל כלשהו כדי לראות את פרטי השלב.

הנה מפה לדוגמה של כלי המעקב, עם תוויות על מקטעי העיבוד העיקריים של שרת ה-proxy:

מפת העסקאות של כלי המעקב

מקרא של מפת העסקאות

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

סמלים במפת העסקאות

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

העמודות הגבוהות מציינות את ההתחלה של מקטע בתהליך של ה-proxy ל-API. הקטעים של התהליך הם: בקשת ProxyEndpoint, בקשת TargetEndpoint, תגובת TargetEndpoint ותגובת ProxyEndpoint. קטע כולל את PreFlow,‏ Conditional Flows ו-PostFlow.

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

מציין שפעולות של Analytics התרחשו ברקע.

תהליך מותנה שהערך שלו הוא True. במאמר הגדרת תהליכים מוסבר על תהליכים מותנים.

שימו לב שחלק מהתנאים נוצרים על ידי Edge. לדוגמה, הביטוי הבא משמש את Edge כדי לבדוק אם אירעה שגיאה ב-ProxyEndpoint:

((error.state equals PROXY_REQ_FLOW) or (error.state equals PROXY_RESP_FLOW))

תהליך מותנה שהערך שלו הוא False. למבוא על תהליכים מותנים, קראו את המאמר הגדרת תהליכים.

שימו לב שחלק מהתנאים נוצרים על ידי Edge. לדוגמה, הביטוי הבא משמש את Edge כדי לבדוק אם אירעה שגיאה ב-TargetEndpoint:

(((error.state equals TARGET_REQ_FLOW) or (error.state equals TARGET_RESP_FLOW)) or ((error.state equals REQ_SENT) or (error.state equals RESP_START)))

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

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

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

מופיע כשיעד הקצה העורפי הוא אפליקציית Node.js. מידע נוסף זמין במאמר סקירה כללית של Node.js ב-Apigee Edge.
יעד הקצה העורפי שאליו מתבצעת הקריאה על ידי ה-proxy ל-API.
ציר הזמן מציין כמה זמן (באלפיות השנייה) נמשך העיבוד. השוואה בין פלחי הזמן שחלף עוזרת לבודד את כללי המדיניות שהביצוע שלהם נמשך הכי הרבה זמן, וכך מאטים את הקריאות ל-API.
האפסילון מציין פרק זמן קצר יותר מאלפית השנייה.

מושבת. מופיע בסמל של מדיניות כשהמדיניות מושבתת. אפשר להשבית מדיניות באמצעות ה-API הציבורי. הפניה להגדרת proxy ל-API

שגיאה. מופיע בסמל של מדיניות כשתנאי לביצוע השלב של המדיניות מקבל את הערך False (ראו משתני זרימה ותנאים), או בסמל של המדיניות RaiseFault בכל פעם שהמדיניות RaiseFault מופעלת.
דילגת על השאלה. מופיע בסמל של מדיניות כשהמדיניות לא בוצעה כי התנאי לביצוע השלב הוערך כ-false. מידע נוסף זמין במאמר משתני זרימה ותנאים.

הסבר על פרטי השלב

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

פרטי השלב תיאור
נקודת קצה (endpoint) של שרת proxy מציין איזה תהליך ProxyEndpoint נבחר להרצה. ל-proxy ל-API יכולות להיות כמה נקודות קצה (endpoint) עם שמות.
משתנים

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

הערה:

  • סימן שוויון (=) מציין את הערך שהוקצה למשתנה.
  • סימן שווה עם קו חוצה (≠) מציין שלא ניתן היה להקצות ערך למשתנה כי הוא לקריאה בלבד או שהייתה שגיאה בביצוע המדיניות.
  • שדה ריק מציין שערך המשתנה נקרא.
כותרות של בקשות רשימה של כותרות בקשת HTTP.
בקשת תוכן מציג את גוף בקשת ה-HTTP.
מאפיינים המאפיינים מייצגים את המצב הפנימי של ה-proxy ל-API. הן לא מוצגות כברירת מחדל.
נקודת הקצה של היעד מציין איזה TargetEndpoint נבחר להרצה.
כותרות תגובה רשימה של כותרות תגובת HTTP.
תוכן התשובה הצגת גוף תגובת ה-HTTP.
PostClientFlow מציג מידע על PostClientFlow, שמופעל אחרי שהבקשה מוחזרת לאפליקציית הלקוח ששלחה את הבקשה. אפשר לצרף ל-PostClientFlow רק כללי מדיניות של MessageLogging. ה-PostClientFlow משמש כרגע בעיקר למדידת מרווח הזמן בין חותמות הזמן של ההתחלה והסיום של הודעת התגובה.

שיפור תיעוד ההודעות באמצעות מסננים

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

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

מה חשוב לדעת על תכונת הסינון

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

איך יוצרים מסנן מעקב

  1. אם סשן המעקב פועל, לוחצים על Stop Trace Session כדי לעצור אותו.
  2. לוחצים על Filters בפינה השמאלית העליונה של הכלי Trace כדי להרחיב את השדה Filters.

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

    בכלי Trace, בקטע Filters, בקטע פרמטרים של שאילתה, מוגדרים שני שמות וערכים לדוגמה.
  4. מתחילים את סשן המעקב.
  5. שולחים קריאות ל-API. רק בקשות שכוללות את כל הכותרות ו/או הפרמטרים של השאילתות שצוינו יפיקו התאמה מוצלחת.

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

בדוגמה שלמעלה, הקריאה הזו ל-API תופיע ב-Trace:

http://docs-test.apigee.net/cats?name=Penny&breed=Calico

אבל לא:

http://docs-test.apigee.net/cats?name=Penny

ניפוי באגים באמצעות Trace

הכלי Trace מאפשר לראות הרבה פרטים פנימיים על שרת proxy ל-API. לדוגמה:

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

בחירת אפשרויות תצוגה

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

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

הורדת תוצאות המעקב

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

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

הצגת בקשות כ-curl

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

  • יכול להיות שה-proxy ל-API ישנה את הבקשה, ולכן כדאי לראות במה הבקשה מה-proxy לשרת היעד שונה מהבקשה המקורית. הפקודה curl מייצגת את הבקשה ששונתה.
  • אם המטען הייעודי של ההודעה גדול יותר, הפקודה curl מאפשרת לראות את כותרות ה-HTTP ואת תוכן ההודעה במקום אחד. (בשלב הזה, המגבלה היא בערך 1,000 תווים. כדי לקבל טיפ איך לעקוף את המגבלה הזו, אפשר לעיין בפוסט הזה בקהילה.)

מטעמי אבטחה, התכונה curl מסתירה את כותרת ההרשאה של HTTP.

כדי לראות בקשות כ-curl אחרי שקריאה ל-API מגיעה ב-Trace, בוחרים את השלב "Request sent to target server" בתרשים Transaction Map, ואז לוחצים על הכפתור Show curl בעמודה "Request sent to target server" בחלונית Phase Details.

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

שימוש ב-Trace על ידי צוות התמיכה של Apigee

כברירת מחדל, Apigee Edge מאפשר לתמיכה של Apigee להשתמש בכלי Trace עבור שרתי proxy של ה-API כדי לספק תמיכה. אפשר להשבית את האפשרות הזו בכל שלב. עם זאת, השבתת האפשרות הזו עלולה להגביל את היכולת של התמיכה ב-Apigee לספק לך תמיכה.

כדי להשבית את התמיכה של Apigee בכלי Trace:

  1. נכנסים אל https://apigee.com/edge.
  2. בוחרים באפשרות ניהול > פרטיות ואבטחה בסרגל הניווט הימני.
  3. לוחצים על המתג הפעלת תמיכה ב-Apigee כדי לעקוב כדי להשבית את השימוש בכלי Trace על ידי תמיכת Apigee.