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

במסמך הזה מתואר בקצרה הקשר, שמתייחס למצב, והעברת הקשר, שמתייחסת להעברת מידע על המצב לפעולות צאצא. לצורך מעקב מבוזר, צריך להעביר את מזהה המעקב ואת המזהה של יחידה לוגית למעקב שעובר עיבוד לפעולות צאצא.

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

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

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

ההקשר עשוי לכלול מידע אחר על המצב, ששימושי למעקב מבוזר. לדוגמה, התקן של World Wide Web Consortium ‏ (W3C) כולל מידע על כך שיחידה לוגית למעקב האב נדגמה.

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

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

בקשות HTTP

בבקשות HTTP, העברת ההקשר מתבצעת בדרך כלל באמצעות כותרות HTTP כמו הכותרות traceparent ו-tracestate, שתוקננו על ידי W3C. שירותיGoogle Cloud שתומכים בהעברת הקשר של מעקב בדרך כלל תומכים גם בכותרת traceparent וגם בכותרת X-Cloud-Trace-Context מדור קודם.

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

אם יש לכם אפליקציה שתומכת רק בכותרת 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) ו-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 שתומכות במעקב זמינה במאמר Language APIs & SDKs.

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

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

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