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

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

‫Telemetry API משתמש ב-OpenTelemetry Line 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 חובה. שם הפעולה שבוצעה. השם יכול להיות שם של שיטה או שם אחר של אתר לכל שיחה. אם משתמשים באותו שם לאותו קובץ הפעלה ולאותה נקודת קצה, קל יותר לקשר בין טווחי זמן שונים בנתוני המעקב. שיטות מומלצות מפורטות במאמר איך לתת שמות לטווחים. שם הטווח עובר ניקוי ומוצג במסוף Google Cloud .
kind	integer מציין את המיקום במערכת שבו התרחשה הפעולה. הערך תואם לספירה OpenTelemetry: Span Kind: ערך ספירה של OpenTelemetry 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 בלי שדות חוזרים תוויות ספציפיות לאפליקציה זמינות כשמרווחי זמן של מעקב נוצרים על ידי אפליקציות של מרכז האפליקציות, כשהאפליקציות האלה פועלות בתשתית נתמכת או כשבוצע אינסטרומנטציה. מידע נוסף על Application Monitoring ועל המועד שבו התוויות האלה זמינות מופיע במאמר סקירה כללית על Application Monitoring. השדה הזה מכיל את שדות המשנה application,‏ service ו-workload. שדה משנה של אפליקציה תיאור container string location string id string שדה משנה של שירות/עומס עבודה תיאור id string environment_type string criticality_type string