מעקב אחר ה-API

‫OpenAPI   |  gRPC

אחרי שפורסים את Extensible Service Proxy (ESP) או את Extensible Service Proxy V2 (ESPv2) ואת קוד הבק-אנד של ה-API, ה-proxy מיירט את כל הבקשות ומבצע את כל הבדיקות הנדרשות לפני שהוא מעביר את הבקשה לבק-אנד של ה-API. כששרת הקצה העורפי מגיב, ה-proxy אוסף ומדווח על טלמטריה. אחד מנתוני הטלמטריה שה-proxy מתעד הוא מעקב, באמצעות Cloud Trace.

בדף הזה נסביר איך:

• צפייה בנתוני מעקב במסוף Google Cloud .
• אומדן העלות של Trace.
• מגדירים את ה-proxy כך שישבית את דגימת העקבות.

צפייה במעקבים

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

כדי לראות את נתוני המעקב של הפרויקט, עוברים לדף Cloud Trace ב- Google Cloud console:

מעבר אל Trace

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

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

מידע נוסף על הדף Trace explorer זמין במאמר חיפוש של עקבות ובדיקה שלהם.

טווחים שנוצרו על ידי ESPv2

‫ESPv2 יוצר עקבות בפורמט הבא:

לפחות, ESPv2 יוצר 2 טווחי זמן לכל מעקב:

• ingress OPERATION_NAME טווח לכל הבקשה והתשובה.
• טווח router BACKEND egress של הזמן שבו ESPv2 ממתין לעיבוד הבקשה על ידי ה-backend ולשליחת תגובה. זה כולל את הניתוב ברשת בין ESPv2 לבין ה-backend.

בהתאם להגדרת ה-API, ‏ ESPv2 עשוי ליצור עוד טווחים:

• אם ה-API שלכם דורש אימות, ESPv2 שומר במטמון את המפתח הציבורי שנדרש לאימות למשך 5 דקות. אם המפתח הציבורי לא נמצא במטמון, ESPv2 מאחזר אותו, מכניס אותו למטמון ויוצר טווח JWT Remote PubKey Fetch.
• אם ה-API שלכם דורש מפתח API, ‏ ESPv2 שומר במטמון את המידע שנדרש לאימות מפתח ה-API. אם המידע לא נמצא במטמון, ESPv2 קורא ל-Service Control API ויוצר יחידה לוגית למעקב Service Control remote call: Check.

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

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

טווחים שנוצרו על ידי ESP

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

‫ESP יוצר עקבות בפורמט הבא:

לפחות 4 טווחי זמן נוצרים לכל מעקב:

• טווח לכל הבקשה והתשובה.
• ‫CheckServiceControl span לקריאה ל-method‏ services.check של Service Control כדי לקבל את ההגדרה של ה-API.
• QuotaControl טווח לבדיקה אם הוגדרה מכסת שימוש ב-API.
• יחידה לוגית למעקב Backend שמתעדת את הזמן שחלף בקוד העורפי של ה-API.

בהתאם להגדרה של ה-API, ‏ ESP יוצר עוד טווחים:

• אם ה-API שלכם דורש אימות, ESP יוצר CheckAuthיחידה לוגית למעקב בכל יומן מעקב. כדי לאמת בקשה, ESP שומר במטמון את המפתח הציבורי שנדרש לאימות למשך 5 דקות. אם המפתח הציבורי לא נמצא במטמון, ESP מאחזר אותו, מכניס אותו למטמון ויוצר טווח HttpFetch.
• אם ה-API שלכם דורש מפתח API, ‏ ESP יוצר טווח CheckServiceControlCache בכל מעקב. ה-ESP שומר במטמון את המידע שנדרש כדי לאמת את מפתח ה-API. אם המידע לא נמצא במטמון, ESP קורא ל-Service Control API ויוצר Call ServiceControl server span.
• אם הגדרתם מכסת שימוש ל-API, ‏ ESP יוצר יחידה לוגית למעקב QuotaServiceControlCache בכל יומן מעקב. ספקי ESP שומרים במטמון את המידע שנדרש לבדיקת המכסה. אם המידע לא נמצא במטמון, ספק ה-ESP קורא ל-Service Control API ויוצר יחידה לוגית למעקב Call ServiceControl server.

תדירות הדגימה של המעקב

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

אם מספר הבקשות בשנייה הוא:

• אם הערך קטן מ-999 או שווה לו, ספק ה-ESP שולח נתון מעקב אחד.
• בין 1000 ל-1999, ספק ה-ESP שולח 2 עקבות.
• בין 2000 ל-2999, ספק ה-ESP שולח 3 עקבות.
• וכן הלאה.

לסיכום, אפשר להעריך את קצב הדגימה באמצעות הפונקציה ceiling: ceiling(requests per second/1000)

הערכת העלות של Trace

כדי לאמוד את העלות של Trace, צריך לאמוד את מספר הטווחים ש-ESP שולח ל-Trace בחודש.

כדי להעריך את מספר התקופות בחודש:

1. הערכה של מספר הבקשות לשנייה ל-API. כדי לקבל את האומדן הזה, אפשר להשתמש בתרשים בקשות בדף נקודות קצה > שירותים או ב-Cloud Logging. מידע נוסף זמין במאמר בנושא ניטור ה-API.
2. חישוב מספר העקבות ש-ESP שולח ל-Trace בכל שנייה: ceiling(requests per second/1000)
3. הערכת מספר הטווחים ב-Trace. כדי לקבל את האומדן הזה, אפשר להשתמש במידע שבקטע טווחים שנוצרו על ידי ESP או לעיין בדף Trace List כדי לראות את ה-traces של ה-API.
4. אומדים את מספר השניות בחודש שבהן ה-API מקבל תנועת גולשים. לדוגמה, יש ממשקי API שמקבלים בקשות רק בשעות מסוימות ביום, ויש ממשקי API שמקבלים בקשות באופן לא סדיר.
5. מכפילים את מספר השניות בחודש במספר טווחי הזמן.

לדוגמה:

1. נניח שהמספר המקסימלי של בקשות לשנייה עבור API הוא 5.
2. תדירות הדגימה של העקבות היא ceiling (5/1000) = 1
3. לא מוגדרת מכסה ל-API, לא נדרש מפתח API ולא נדרש אימות. לכן, מספר הטווחים ש-ESP יוצר לכל מעקב הוא 4.
4. ה-API הזה מקבל בקשות רק במהלך שעות הפעילות, בימים שני עד שישי. מספר השניות בחודש שבהן ה-API מקבל תנועה הוא בערך: ‎3,600 X 8 X 20 = 576,000
5. מספר הטווחים בחודש הוא בערך 576,000 x 4 = 2,304,000

אחרי שתדעו את המספר המשוער של טווחי הזמן בחודש, תוכלו לעיין בדף תמחור של Trace כדי לקבל מידע מפורט על התמחור.

השבתת דגימת נתונים של מעקב

אם רוצים להפסיק את הדגימה של בקשות ושליחת עקבות על ידי ESP, אפשר להגדיר אפשרות הפעלה של ESP ולהפעיל מחדש את ESP. הנתונים של העקבות ששירות ה-ESP שולח ל-Cloud Trace לא קשורים לתרשימים שמוצגים בדף Endpoints > Services. הגרפים ימשיכו להיות זמינים אם תשביתו את הדגימה של המעקב.

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

Compute Engine

כדי להשבית את הדגימה של מעקב ESP ב-Compute Engine באמצעות Docker:

1. מתחברים למופע של מכונת ה-VM:

   gcloud compute ssh [INSTANCE_NAME]

2. בפקודה docker run, מוסיפים את האפשרות --disable_cloud_trace_auto_sampling לדגלים של ESP:

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=[SERVICE_NAME] \
       --rollout_strategy=managed \
       --backend=[YOUR_API_CONTAINER_NAME]:8080 \
       --disable_cloud_trace_auto_sampling

3. מריצים את הפקודה docker run כדי להפעיל מחדש את ה-ESP.

כדי להפעיל מחדש את דגימת העקבות:

1. מסירים את --disable_cloud_trace_auto_sampling.
2. מריצים את הפקודה docker run כדי להפעיל מחדש את ה-ESP.

GKE

כדי להשבית את דגימת העקבות של ESP ב-GKE:

1. פותחים את קובץ המניפסט של הפריסה, שנקרא deployment.yaml, ומוסיפים את השורות הבאות לקטע containers:

   containers:
   - name: esp
     image: gcr.io/endpoints-release/endpoints-runtime:1
     args: [
       "--http_port=8081",
       "--backend=127.0.0.1:8080",
       "--service=[SERVICE_NAME]",
       "--rollout_strategy=managed",
       "--disable_cloud_trace_auto_sampling"
     ]

2. מפעילים את שירות Kubernetes באמצעות הפקודה kubectl create:

   kubectl create -f deployment.yaml

כדי להפעיל מחדש את דגימת העקבות:

1. מסירים את האפשרות --disable_cloud_trace_auto_sampling.
2. מפעילים את שירות Kubernetes:

   kubectl create -f deployment.yaml

אם אתם מריצים ESP במכונה וירטואלית ב-Compute Engine בלי קונטיינר Docker, אין זוג מקש/ערך של מטא נתונים של מכונה וירטואלית ששווה לאפשרות --disable_cloud_trace_auto_sampling. אם רוצים להשבית את הדגימה של נתוני המעקב, צריך להפעיל את ESP בקונטיינר.

לקוח יכול לכפות מעקב על בקשה על ידי הוספת הכותרת X-Cloud-Trace-Context לבקשה, כפי שמתואר במאמר כפיית מעקב על בקשה. אם בקשה מכילה את הכותרת X-Cloud-Trace-Context, ‏ ESP שולח את נתוני המעקב אל Trace גם אם השבתתם את הדגימה של המעקב.

העברת הקשר של מעקב

במעקב מבוזר, כותרת בקשה יכולה להכיל הקשר מעקב שמציין מזהה מעקב. מזהה העקבות משמש כש-ESPv2 יוצרת טווחי עקבות חדשים ושולחת אותם אל Cloud Trace. מזהה העקבות משמש לחיפוש בכל העקבות ולצירוף של טווחי זמן לבקשה אחת. אם לא צוין הקשר של המעקב בבקשה, והמעקב מופעל, נוצר מזהה מעקב אקראי לכל טווחי המעקב.

בדוגמה הבאה, Cloud Trace מבצע קורלציה בין טווחים שנוצרו על ידי ESPv2‏ (1) לבין טווחים שנוצרו על ידי הקצה העורפי (2) עבור בקשה יחידה. הפעולה הזו עוזרת לנפות באגים בבעיות של זמן אחזור בכל המערכת:

פרטים נוספים זמינים במאמר מושגי ליבה של OpenTelemetry: העברת הקשר

הערה: כדי להשתמש באפשרות 'מעקב מבוזר', הלקוחות או השרתים העורפיים צריכים לתמוך במעקב. הנושא הזה לא נכלל במסמכי התיעוד האלה. מומלץ להשתמש ב-OpenTelemetry.

כותרות נתמכות

‫ESPv2 תומך בכותרות הבאות של העברת הקשר של מעקב:

• ‫traceparent: כותרת ההפצה של הקשר למעקב בתקן W3C. נתמך על ידי רוב מסגרות המעקב המודרניות.
• ‫x-cloud-trace-context: כותרת להעברת הקשר של מעקב ב-GCP. נתמך על ידי frameworks ישנים יותר למעקב וספריות של Google, אבל ספציפי לספק.
• ‫grpc-trace-bin: כותרת להעברת הקשר של מעקב, שמשמשת קצה עורפי של gRPC עם ספריית המעקב OpenCensus.

אם אתם מפתחים אפליקציה חדשה, מומלץ להשתמש בהפצת הקשר של traceparent trace. ‫ESPv2 יחלץ ויפיץ את הכותרת הזו כברירת מחדל. פרטים על שינוי התנהגות ברירת המחדל מופיעים במאמר בנושא אפשרויות הפעלה של מעקב ESPv2.

הערה: בניגוד ל-ESPv2, ב-ESP צריך להפעיל ידנית את העברת ההקשר של המעקב באמצעות אפשרויות ההפעלה. פרוטוקול ESP לא תומך בכותרת traceparent.