סכימת אחסון לנתוני מעקב

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

‫Telemetry API משתמש ב-OpenTelemetry OTLP Protocol. הפרוטוקול הזה מסתמך על הקבצים trace_service.proto ו-trace.proto. מידע על מגבלות השדות זמין במאמר מגבלות של Telemetry API.

‫Cloud Trace API לא משתמש בפרוטוקול OpenTelemetry OTLP, ומגדיר פורמט נתונים קנייני. נתונים שמועברים אל Google Cloud הפרויקט שלכם דרך ה-API הזה מומרים לפורמט שמתואר במסמך הזה. עם זאת, חלות המגבלות של Cloud Trace API.

פורמט אחסון של טווח

שדה	תיאור
trace_id	string מזהה ייחודי גלובלי של המעקב. המזהה הזה הוא ערך מספרי של 128 ביט בפורמט של מחרוזת הקסדצימלית בגודל 16 בייט. לדוגמה: 382d4f4c6b7bb2f4a972559d9085001d. מידע נוסף על המזהה הזה זמין ב-W3C trace-id. ערך מספרי של אפס לא תקין. ה-trace_id משמש כלי ויזואליזציה וניתוח כדי לזהות את טווחי הזמן שמשויכים למעקב. לכן, לכל פעולה מקצה לקצה צריך להיות מזהה ייחודי. לא כדאי לעשות שימוש חוזר במזהה מעקב.
span_id	string חובה. מזהה של התג span. המזהה חייב להיות ייחודי בתוך עקבה. המזהה הזה הוא ערך מספרי בן 64 ביט בפורמט של מחרוזת הקסדצימלית באורך 8 בתים. לדוגמה, 9046a5b9f7c12500. ערך מספרי של אפס לא תקין.
trace_state	string השדה הזה תואם לכותרת tracestate, כפי שמוגדר בהקשר של מעקב W3C. הכותרת הזו מכילה פרטי הגדרה שנכללים בבקשות כשמגדירים באפליקציות איסוף של נתוני מעקב. לדוגמה, אפליקציה יכולה לציין את ההגדרות של דגימה הסתברותית או לכלול תוכן ספציפי לספק. ספריות OpenTelemetry מתעדות באופן אוטומטי את הערך של הכותרת tracestate כשהן יוצרות טווחים.
parent_span_id	string זה שינוי אופציונלי. מזהה את הפעולה שהפעילה את הטווח הזה. בטווח 'root' מזהה טווח האב מוגדר כ-null. הקשר בין טווחי זמן הורה-צאצא משמש כלי ויזואליזציה לבניית מבנה העץ.
name	string חובה. שם הפעולה שבוצעה. השם יכול להיות שם של method או שם אחר של אתר לכל קריאה. אם משתמשים באותו שם לאותו קובץ הפעלה ולאותה נקודת קצה, קל יותר לקשר בין טווחי זמן שונים במעקב. שיטות מומלצות מפורטות במאמר איך לתת שמות לטווחים. שם הטווח עובר ניקוי ומוצג במסוף Google Cloud .
kind	integer מציין איפה במערכת התרחשה הפעולה. הערך תואם לספירה OpenTelemetry: Span Kind: ערך OpenTelemetry enumeration 0 SPAN_KIND_UNSPECIFIED 1 SPAN_KIND_INTERNAL 2 SPAN_KIND_SERVER 3 SPAN_KIND_CLIENT 4 SPAN_KIND_PRODUCER 5 SPAN_KIND_CONSUMER
start_time	Timestamp חובה. שעת ההתחלה של יחידה לוגית למעקב, מעוגלת לננו-שנייה הקרובה ביותר.
start_time_unix_nano	integer זמן ההתחלה בננו-שניות, לפי ראשית זמן יוניקס (Unix epoch).
end_time	Timestamp חובה. שעת הסיום של יחידה לוגית למעקב, מעוגלת לננו-שנייה הקרובה ביותר.
end_time_unix_nano	integer זמן הסיום בננו-שניות, לפי ראשית זמן יוניקס (Unix epoch).
receive_time	Timestamp חובה. השעה שבה התקבל הטווח, מעוגלת לננו-שנייה הקרובה ביותר.
receive_time_unix_nano	integer זמן הסיום בננו-שניות, לפי ראשית זמן יוניקס (Unix epoch).
duration_unix_nano	integer משך הזמן בננו-שניות.
attributes	JSON type כל מאפיין הוא צמד מפתח/ערך. התכונות שזמינות לכם תלויות בנתוני העקבות. מבנה המאפיינים תואם לתקן OpenTelemetry. מידע נוסף זמין במאמר OpenTelemetry: Attributes. ב-OpenTelemetry מוגדרות מוסכמות סמנטיות למאפיינים. מידע נוסף על המוסכמות האלה זמין במאמר בנושא מוסכמות סמנטיות של מעקב. דוגמאות למאפיינים: "yourcompany.your.own.key": "your own value" "network.protocol.name": "http" "network.protocol.version": "1.1" "http.response.status_code": "200" "network.peer.address": "REDACTED"
dropped_attributes_count	integer מספר המאפיינים שהמערכת פסלה. יכול להיות שמאפיינים ייפסלו כי המפתחות שלהם ארוכים מדי או כי יש יותר מדי מאפיינים. אם הערך הוא אפס, לא נמחקו מאפיינים. יכול להיות שהערך הזה מוגדר על ידי מכשור בצד הלקוח או על ידי אפליקציה. השרת יכול להגדיל את הערך.
events	‫record עם שדות חוזרים אירוע שמתרחש בנקודת זמן מסוימת. כל אירוע מכיל את השדות הבאים. שדה תיאור time Timestamp time_unix_nano integer name string חובה. שם האירוע. attributes JSON type כל מאפיין הוא צמד מפתח/ערך. התכונות שזמינות לכם תלויות בנתוני העקבות. מבנה המאפיינים תואם לתקן OpenTelemetry. מידע נוסף זמין במאמר OpenTelemetry: Attributes. dropped_attributes_count integer מספר המאפיינים שהמערכת פסלה. יכול להיות שמאפיינים ייפסלו כי המפתחות שלהם ארוכים מדי או כי יש יותר מדי מאפיינים. אם הערך הוא אפס, לא נמחקו מאפיינים. יכול להיות שהערך הזה מוגדר על ידי מכשור בצד הלקוח או על ידי אפליקציה. השרת יכול להגדיל את הערך.
dropped_events_count	integer מספר האירועים שהושלכו. יכול להיות שהאירועים יימחקו כי יש יותר מדי אירועים. אם הערך הוא אפס, לא נמחקו אירועים.
links	‫record עם שדות חוזרים קישורים שמשויכים לטווח. קישורים הם הפניות מיחידה לוגית למעקב זו ליחידה לוגית למעקב אחרת באותו מעקב או במעקב אחר. קישורים מספקים מנגנון לקורלציה בין טווחי זמן ממעקב אחד לבין טווחי זמן במעקב אחר. לדוגמה, נניח שפעולה אחת גורמת להתרחשות של פעולה אסינכרונית. בתרחיש הזה יש שני עקבות, אחד לפעולה המקורית ואחד לפעולה האסינכרונית. אפשר להשתמש בקישורים כדי ליצור קורלציה בין הטווחים בעקבות האלה. כל קישור מכיל את השדות הבאים. שדה תיאור trace_id string חובה. span_id string חובה. trace_state string attributes JSON type כל מאפיין הוא צמד מפתח/ערך. התכונות שזמינות לכם תלויות בנתוני העקבות. מבנה המאפיינים תואם לתקן OpenTelemetry. מידע נוסף זמין במאמר OpenTelemetry: Attributes. dropped_attributes_count integer מספר המאפיינים שהמערכת פסלה. יכול להיות שמאפיינים ייפסלו כי המפתחות שלהם ארוכים מדי או כי יש יותר מדי מאפיינים. אם הערך הוא אפס, לא נמחקו מאפיינים. יכול להיות שהערך הזה מוגדר על ידי מכשור בצד הלקוח או על ידי אפליקציה. השרת יכול להגדיל את הערך.
dropped_links_count	integer מספר הקישורים שהושלכו. יכול להיות שקישורים יימחקו כי יש יותר מדי קישורים. אם הערך הוא אפס, לא נמחקו קישורים.
status	‫record בלי שדות חוזרים בשדה הזה מתועד סטטוס ההשלמה של טווח. הערך של שדה המשנה code תואם לספירה OpenTelemetry: Span Status: ערך OpenTelemetry enumeration תיאור 0 UNSET הפעולה הושלמה בהצלחה. 1 OK הפעולה סומנה על ידי אדם כפעולה ללא שגיאות. 2 ERROR הפעולה הושלמה עם שגיאה. לדוגמה, אם הסטטוס הוא 400 (בקשה שגויה) ביחידה לוגית למעקב של לקוח, השדה הזה מוגדר ל-ERROR. שדה המשנה message, שהוא מחרוזת בפורמט מסוים, מכיל מידע על שגיאות.
resource	‫record בלי שדות חוזרים בשדה הזה מצוינת התשתית או מערכת האירוח שממנה נאספה הטלמטריה או שהטלמטריה מתייחסת אליה. לדוגמה, נניח שיש אפליקציה שפועלת ב-Google Kubernetes Engine. המאפיינים של המשאב הזה יכולים לכלול את שם התהליך ואת מרחב השמות. השדה הזה מכיל את שדות המשנה הבאים: שדה תיאור attributes JSON type כל מאפיין הוא צמד מפתח/ערך. התכונות שזמינות לכם תלויות בנתוני העקבות. מבנה המאפיינים תואם לתקן OpenTelemetry. מידע נוסף זמין במאמר OpenTelemetry: Attributes. דוגמאות למאפייני משאבים: cloud.account.id: "my-project" cloud.platform: "gcp_kubernetes_engine" cloud.provider: "gcp" cloud.region: "us-central1" gcp.project_id: "my-project" host.id: "REDACTED" host.name: "gke-otel-demo" k8s.cluster.name: "otel-demo" k8s.deployment.name: "otel-demo-frontendproxy" dropped_attributes_count integer מספר המאפיינים שהמערכת פסלה. יכול להיות שמאפיינים ייפסלו כי המפתחות שלהם ארוכים מדי או כי יש יותר מדי מאפיינים. אם הערך הוא אפס, לא נמחקו מאפיינים. יכול להיות שהערך הזה מוגדר על ידי מכשור בצד הלקוח או על ידי אפליקציה. השרת יכול להגדיל את הערך. מידע נוסף זמין במאמר OpenTelemetry: Resources.
instrumentation_scope	‫record בלי שדות חוזרים בשדה הזה מצוין הרכיב של הספרייה או רכיב באפליקציה עבור resource שמוגדר לאיסוף טלמטריה. התג span מייצג פעולה ספציפית שעוברת דרך ההיקף הזה, כלומר דרך הספרייה או הרכיב, בתוך המשאב. לדוגמה, נניח שהאפליקציה checkout-service נפרסה ב-Cloud Run, כלומר resource היא מופע ספציפי של Cloud Run. בנוסף, נניח שלמשאב יש כמה היקפי אינסטרומנטציה, כמו request-authorization-library ו-payment-processor-library. יחידה לוגית למעקב של לקוח, כמו WritePaymentInfoToStripe, יכולה להיות יחידה לוגית למעקב שמדווחת על ידי payment-processor-library, שנמצא בתוך שירות Cloud Run שנקרא checkout-service. השדה הזה מכיל את שדות המשנה הבאים: שדה תיאור name string version string attributes JSON type כל מאפיין הוא צמד מפתח/ערך. התכונות שזמינות לכם תלויות בנתוני העקבות. מבנה המאפיינים תואם לתקן OpenTelemetry. מידע נוסף זמין במאמר OpenTelemetry: Attributes. dropped_attributes_count integer מספר המאפיינים שהמערכת פסלה. יכול להיות שמאפיינים ייפסלו כי המפתחות שלהם ארוכים מדי או כי יש יותר מדי מאפיינים. אם הערך הוא אפס, לא נמחקו מאפיינים. יכול להיות שהערך הזה מוגדר על ידי מכשור בצד הלקוח או על ידי אפליקציה. השרת יכול להגדיל את הערך. מידע נוסף זמין במאמר בנושא OpenTelemetry: Instrumentation scope.
resource_schema_link	string השדות האלה חייבים להיות כתובת URL בפורמט של מחרוזת. השדות האלה מכילים כתובת URL שמחזירה קובץ סכימה של משאב. הפורמט של קובץ הסכימה והנתונים מוגדר על ידי OpenTelemetry. מידע נוסף זמין במאמר בנושא OpenTelemetry: Schemas. אפשר להגדיר את השדות האלה רק כשמשתמשים ב-Telemetry API. ממשק ה-API הזה לא מאמת שהנתונים תואמים לסכימה שהוגדרה.
scope_schema_link	string השדות האלה חייבים להיות כתובת URL בפורמט של מחרוזת. השדות האלה מכילים כתובת URL שמחזירה קובץ סכימה להיקף. הפורמט של קובץ הסכימה והנתונים מוגדר על ידי OpenTelemetry. מידע נוסף זמין במאמר בנושא OpenTelemetry: Schemas. אפשר להגדיר את השדות האלה רק כשמשתמשים ב-Telemetry API. ממשק ה-API הזה לא מאמת שהנתונים תואמים לסכימה שהוגדרה.
apphub	‫record בלי שדות חוזרים תוויות ספציפיות לאפליקציה זמינות כשמרווחי זמן של מעקב נוצרים על ידי אפליקציות של App Hub, כשהאפליקציות האלה פועלות בתשתית נתמכת או כשהן מוגדרות למעקב. מידע נוסף על מעקב אחר אפליקציות ומתי התוויות האלה זמינות אפשר למצוא במאמר סקירה כללית על מעקב אחר אפליקציות. השדה הזה מכיל את שדות המשנה application,‏ service ו-workload. שדה משנה של אפליקציה תיאור container string location string id string שדה משנה של שירות או עומס עבודה תיאור id string environment_type string criticality_type string