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

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

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

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

באמצעות מזהים משותפים כאלה, Cloud 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, שמגדיר את ההקשר לשימוש בפורמט traceparent של W3C. לדוגמה, אפשר לעיין בדוגמה של מכשור Go.

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

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