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

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X.
מידע

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

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

צפה בסרטון זה לקבלת מבוא לכלי המעקב.

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

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

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

    Edge

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

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

    Classic Edge (ענן פרטי)

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

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

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

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

איך לקרוא עקבות

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

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

הנה מפה לדוגמה של כלי מעקב, שמסומנים בתווית:

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

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

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

סמלים של מפת עסקאות

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

העמודות הגבוהות מציינות את תחילתו של מקטע הזרימה בזרימה של שרת ה-proxy של ה-API. מקטעי הזרימה: בקשת ProxyEndpoint, בקשת TargetEndpoint, תגובת TargetEndpoint ותגובה ProxyEndpoint. פלח כולל את השדות PreFlow, Conditionalflows ו-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.
היעד לקצה העורפי שנקרא על ידי שרת ה-API של שרת ה-proxy.
ציר הזמן מציין את משך הזמן (באלפיות שנייה) שנדרש להשלמת משך העיבוד. ההשוואה בין מקטעי הזמן שעברו עוזרת לבודד את כללי המדיניות שזמן הביצוע שלהם הוא הארוך ביותר, ומאטים את הקריאות ל-API.
אפסילון מציין טווח זמן הקטן מאלפיות שנייה.

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

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

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

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

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

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

הערה:

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

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

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

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

דברים שצריך לדעת על התכונה 'מסנן'

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

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

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

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

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

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

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

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

המערכת מורידה את התוצאות של המעקב

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

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

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

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

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

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

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

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

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

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

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

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