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

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

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

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

   1. נכנסים לממשק המשתמש החדש של Edge בכתובת http://host:3001/edge, כאשר host היא כתובת ה-IP או שם ה-DNS של המארח שבו פועל ממשק המשתמש החדש של Edge.
   2. בסרגל הניווט הימני, בוחרים באפשרות פיתוח > שרתי proxy של API.
2. בוחרים שרת proxy ל-API בדף API Proxies.
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 המסומנים:

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

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

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

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

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

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

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

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

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