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

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

מהו הכלי Trace?

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

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

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

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

   Edge

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

   1. נכנסים לחשבון בכתובת apigee.com/edge.
   2. בסרגל הניווט הימני, בוחרים באפשרות פיתוח > שרתי proxy של API.

   ‫Classic Edge (ענן פרטי)

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

   1. מתחברים אל http://ms-ip:9000, כאשר ms-ip היא כתובת ה-IP או שם ה-DNS של צומת שרת הניהול.
   2. בסרגל הניווט העליון, בוחרים באפשרות APIs > API Proxies.
2. בוחרים שרת proxy ל-API בדף API Proxies (שרתי proxy ל-API).
3. חשוב לוודא שממשק ה-API שרוצים לעקוב אחריו נפרס.
4. לוחצים על Trace כדי לעבור לתצוגת הכלי Trace.
5. בתפריט הנפתח Deployment to Trace (פריסה למעקב) בוחרים את סביבת הפריסה ואת הגרסה של ה-proxy שרוצים לעקוב אחריהם.
6. לוחצים על התחלת סשן מעקב. כשהסשן של המעקב פעיל, שרת ה-proxy של ה-API מתעד פרטים של כל שלב בצינור העיבוד. בזמן שהסשן של מעקב אחר נתונים פועל, הודעות ונתונים הקשריים נאספים מהתנועה בזמן אמת.
   

   

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

איך קוראים את נתוני ה-trace

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

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

זוהי מפה לדוגמה של כלי המעקב עם פלחי העיבוד העיקריים של ה-proxy שמתויגים:

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

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

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

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

	אפליקציית הלקוח ששולחת בקשה ל-ProxyEndpoint של ה-API proxy.
	העיגולים מסמנים נקודות קצה מעברות בתהליך של ה-proxy. הם נמצאים שם כשמתקבלת בקשה מהלקוח, כשהבקשה מגיעה ליעד, כשהתשובה חוזרת מהיעד וכשהתשובה חוזרת ללקוח.
	העמודות הגבוהות מציינות את ההתחלה של פלח זרימה בזרימת ה-API proxy. פילוחים של זרימת הנתונים: בקשה ל-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. הסמלים האלה מאפשרים לראות איפה המדיניות מופעלת בסדר הנכון, ואם ההפעלה מצליחה או לא. אפשר ללחוץ על סמל מדיניות כדי לראות את תוצאות ההפעלה שלה ואם הן צפויות או לא. לדוגמה, אפשר לראות אם ההודעה עברה טרנספורמציה כמו שצריך או אם היא נשמרת במטמון. הסימון של מדיניות שמוטמעת בצורה תקינה הוא ברור: סימני וי. במקרה של שגיאה, מוצג סימן קריאה אדום על הסמל. טיפ: כדאי לשים לב לתיאור הכלים או לציר הזמן כדי לראות אם מדיניות מסוימת פועלת יותר זמן מהצפוי.
	מופיע כשיעד ה-Backend הוא אפליקציית Node.js. מידע נוסף זמין במאמר סקירה כללית של Node.js ב-Apigee Edge.
	יעד הקצה העורפי שאליו מתבצעת קריאה על ידי שרת ה-proxy ל-API.
	ציר הזמן מציין כמה זמן (באלפיות השנייה) לקח לעיבוד להסתיים. השוואה בין פלחים של זמן שחלף עוזרת לכם לבודד את המדיניות שלוקח לה הכי הרבה זמן לפעול, וגורמת להאטה בקריאות ה-API.
	האות אפסילון (Epsilon) מציינת טווח זמן קצר יותר מאלפית השנייה.
	מושבת. מופיע בסמל של מדיניות כשהמדיניות מושבתת. אפשר להשבית מדיניות באמצעות ה-API הציבורי. מידע נוסף מופיע במאמר בנושא הפניית הגדרות של שרת proxy ל-API.
	שגיאה. מופיע בסמל של מדיניות כשהתנאי של השלב במדיניות מחזיר ערך false (ראו משתני זרימה ותנאים), או בסמל של מדיניות RaiseFault בכל פעם שמדיניות RaiseFault מופעלת.
	דילוג. מופיע בסמל מדיניות כשהמדיניות לא הופעלה כי התנאי של השלב הוגדר כ-false. מידע נוסף זמין במאמר משתני תהליך ותנאים.

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

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

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

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

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

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

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

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

1. אם סשן המעקב פועל, לוחצים על Stop Trace Session (עצירת סשן המעקב) כדי לעצור אותו.
2. לוחצים על מסננים בפינה הימנית העליונה של הכלי 'מעקב' כדי להרחיב את השדה 'מסננים'.
   
   
   
3. בשדה 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 כדי לזהות את צוואר הבקבוק. ב-Trace מוצג הזמן, באלפיות השנייה, שנדרש להשלמת כל שלב עיבוד. אם אתם מגלים ששלב מסוים נמשך יותר מדי זמן, אתם יכולים לבצע פעולת תיקון.
• בפרטי השלב אפשר לבדוק את הכותרות שנשלחות אל ה-backend, לראות את המשתנים שמוגדרים על ידי כללי המדיניות וכו'.
• אימות נתיב הבסיס מאפשר לוודא שהמדיניות מעבירה את ההודעה לשרת הנכון.

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

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

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

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

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

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

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

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

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

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

שימוש בתכונה Trace בתמיכה של Apigee

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

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

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