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

אתם צופים במסמכי התיעוד של 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 באמצעות ממשק המשתמש הקלאסי של Edge:

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

   

7. אם אין תנועה בזמן אמת שזורמת דרך השרת הפרוקסי, פשוט שולחים בקשה ל-API. אפשר להשתמש בכל כלי שרוצים כדי לשלוח את הבקשה, כמו curl,‏ Postman או כל כלי אחר שאתם מכירים. אפשר גם לשלוח את הבקשה ישירות מכלי המעקב. פשוט מזינים את כתובת ה-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 של ה-proxy ל-API.
	העיגולים מסמנים נקודות קצה מעבר בתהליך של ה-proxy. הם נמצאים שם כשמתקבלת בקשה מהלקוח, כשהבקשה מגיעה ליעד, כשהתשובה חוזרת מהיעד וכשהתשובה חוזרת ללקוח.
	העמודות הגבוהות מציינות את ההתחלה של מקטע זרימה בזרימת ה-proxy ל-API. פלחים של Flow: בקשת 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.
	האות אפסילון (ε) מציינת פרק זמן קצר יותר מאלפית השנייה.
	מושבת. מופיע בסמל של מדיניות כשהמדיניות מושבתת. אפשר להשבית מדיניות באמצעות ה-API הציבורי. מידע נוסף זמין במאמר בנושא הפניית הגדרות של שרת proxy ל-API.
	שגיאה. מופיע בסמל של מדיניות כשתנאי לביצוע השלב של המדיניות מחזיר ערך false (ראו משתני זרימה ותנאים), או בסמל של מדיניות RaiseFault בכל פעם שמדיניות RaiseFault מופעלת.
	דילוג. מופיע בסמל מדיניות כשהמדיניות לא בוצעה כי התנאי של השלב הוגדר כ-false. מידע נוסף זמין במאמר משתני תהליך ותנאים.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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