הקשר של נתוני המעקב

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

איך מתבצעת העברת הקשר

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

  • ‫Span ID: מזהה ייחודי של פעולת הצאצא. אם מבצעים פעולה כמה פעמים, כל הפעלה יוצרת יחידה לוגית למעקב עם מזהה יחידה לוגית למעקב נפרד.
  • ‫Trace ID: המזהה הייחודי של הבקשה הכוללת מקצה לקצה, שסופק על ידי ההורה.
  • ‫Parent span ID: המזהה הייחודי של ה-span הראשי שמופעל. השדה הזה null מיועד ל-root span.

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

פרוטוקולים להעברת הקשר

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

בקשות HTTP

בבקשות HTTP, העברת ההקשר מתבצעת בדרך כלל באמצעות כותרות HTTP כמו הכותרות traceparent ו-tracestate, שתוקננו על ידי W3C. הכותרת traceparent מכילה את המזהים שמזהים באופן ייחודי את הבקשה. לעומת זאת, הכותרת tracestate היא אופציונלית והיא מכילה מטא-נתונים ספציפיים לספק.

הכותרת traceparent היא בפורמט הבא:

traceparent: VERSION-TRACE_ID-PARENT_SPAN_ID-TRACE_FLAGS

השדות של הכותרת של traceparent מוגדרים כך:

  • ‫VERSION היא גרסת הכותרת. חייב להיות 00.
  • ‫TRACE_ID הוא ערך הקסדצימלי באורך 32 תווים שמייצג מספר בן 128 ביט.
  • ‫PARENT_SPAN_ID הוא ערך הקסדצימלי באורך 16 תווים שמזהה את הטווח ברמת ההורה.
  • ‫TRACE_FLAGS הוא ערך הקסדצימלי בן 2 תווים שמזהה את החלטת הדגימה של ההורה. אם טווח הזמן נדגם על ידי רכיב אב, הערך הוא 01.

Google Cloud שירותים שתומכים בהעברת הקשר של מעקב בדרך כלל תומכים גם ב-traceparent וגם בכותרת X-Cloud-Trace-Context מדור קודם.

כשאפשר, כדאי להשתמש בכותרת traceparent באפליקציות. אם אפליקציה תומכת רק בכותרת X-Cloud-Trace-Context, מומלץ לעדכן את האפליקציה כך שתתמוך בכותרת traceparent ותיתן לה עדיפות. האפליקציה יכולה להמשיך להשתמש בכותרת X-Cloud-Trace-Context כפתרון חלופי.

בטבלה הבאה מפורטים כמה מההבדלים המשמעותיים בין שני הכותרים:

מאפיין כותרת traceparent
 X-Cloud-Trace-Context
כותרת
מפרידים מקפים (-) קו נטוי (/) ונקודה-פסיק (;)
ייצוג של Span ID
 הקסדצימלי עשרוני

כותרת מדור קודם X-Cloud-Trace-Context

הכותרת X-Cloud-Trace-Context שבה נעשה שימוש ב- Google Cloud קודמת למפרט של W3C. לצורך תאימות לאחור, חלק משירותי Google Cloud ממשיכים לקבל, ליצור ולהפיץ את הכותרת X-Cloud-Trace-Context. עם זאת, סביר להניח שהמערכות האלה תומכות גם בכותרת traceparent.

הכותרת X-Cloud-Trace-Context היא בפורמט הבא:

X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=OPTIONS

השדות בכותרת מוגדרים כך:

  • ‫TRACE_ID הוא ערך הקסדצימלי באורך 32 תווים שמייצג מספר בן 128 ביט.
  • ‫SPAN_ID הוא ייצוג עשרוני של מזהה היחידה הלוגית למעקב הלא חתום, בגודל 64 ביט.
  • ‫OPTIONS supports 0 (parent not sampled) and 1 (parent was sampled).

בקשות gRPC

בבקשות gRPC, העברת ההקשר מתבצעת באמצעות מטא-נתונים של gRPC, שמוטמעים על גבי כותרות HTTP. אפליקציות gRPC עשויות להשתמש בכותרת traceparent או במפתח הקשר של המטא-נתונים שנקרא grpc-trace-bin.

לרכיבים שבבעלותכם, מומלץ להשתמש בכותרת traceparent.

העברת הקשר לשירותים של Google Cloud

שירותיGoogle Cloud עשויים לפעול כיוזמים או כמתווכים בעיבוד בקשות. לדוגמה, השירותים הבאים ידועים כמשתתפים בעיבוד בקשות:

התמיכה בהפעלת הקשר של מעקב ובשמירה שלו תלויה בשירותGoogle Cloud הספציפי. כדי לבקש ששירות Google Cloud מסוים יתמוך בהעברת הקשר, צריך להשתמש בIssue Tracker של Google.

העברת הקשר באפליקציות

ספריות מסוימות של מכשירי מדידה, כמו OpenTelemetry, יכולות להפיץ אובייקט context שמכיל את הנתונים שדרושים למעקב. רשימה של ספריות OpenTelemetry שתומכות במעקב זמינה במאמר ממשקי API וערכות SDK לשפות.

אם אתם מסתמכים על ספרייה בקוד פתוח, צריך לבדוק אם יש אפשרות להעברת הקשר ואם נדרש לבצע הגדרה. לדוגמה, אם אתם משתמשים ב-OpenTelemetry כדי להוסיף לאפליקציית Go כלי מדידה, האפליקציה צריכה לקרוא ל-SetTextMapPropagator, שמגדיר את ההקשר לשימוש בפורמט W3C traceparent. דוגמה מופיעה במאמר Go instrumentation sample.

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

המאמרים הבאים