תוויות מעקב

הכלי Trace מספק מנגנון להוספת נתונים משמעותיים לטווחים. אם אתם משתמשים ב-Cloud Trace API V1, אתם יכולים להוסיף תוויות, שהן צמדי מפתח/ערך, באמצעות השדה labels באובייקט TraceSpan של Cloud Trace API. אם אתם משתמשים ב-Cloud Trace API V2, אתם יכולים להוסיף מידע באמצעות אובייקט Attributes.

כשבוחרים טווח, התוויות של הטווח הזה מוצגות בכרטיסייה Attributes. לדוגמה, צילום המסך הבא ממחיש את הכרטיסייה הזו:

דוגמה לטבלת המאפיינים של Cloud Trace.

מידע על גישה לנתונים האלה זמין במאמר בנושא איתור של עקבות וניתוח שלהם.

השדה labels הוא מיפוי של צמדי מפתח/ערך. המפתחות והערכים מאוחסנים כמחרוזות. הגבלות על אורך מחרוזת מפורטות במאמר בנושא הפניית API ל-labels.

אפשר להוסיף עד 32 תוויות לכל טווח.

מפתחות מוגדרים מראש

תוויות קנוניות

בטבלה הבאה מפורטות המפתחות המוגדרים מראש שנתמכים, כולל תיאור, ובמקרים מסוימים, כולל דוגמה:

מפתח התוויתתיאור
דוגמה
/agent מזהה סוכן המעקב.
"node@google-cloud/trace-agent v3.0.0"
/component מזהה הרכיב.
"grpc"
/error/message הודעת שגיאה.
"Rendezvous of RPC that terminated with:
status = StatusCode.UNAVAILABLE details = OS Error."
/error/name השם המוצג של השגיאה.
/http/client_city העיר של הלקוח.
"NYC"
/http/client_country המדינה של הלקוח.
"US"
/http/client_protocol מזהה פרוטוקול HTTP.
"1.0"
/http/client_region האזור של הלקוח.
"us-east4"
/http/host הערך של כותרת המארח.
"default.example.com"
/http/method† מוגדר ל-method של בקשת ה-HTTP.
אל תכללו את המפתח הזה בבקשות שאינן בקשות HTTP.
"GET"
/http/path† נתיב כתובת ה-URL של הבקשה.
"/cart/checkout"
/http/redirected_url כתובת ה-URL לפני ההפניה האוטומטית.
במקרה הזה, משתמשים בתווית HTTL URL כדי לאחסן את כתובת ה-URL הסופית.
/http/request/size מספר הבייטים בבקשה.
/http/response/size מספר הבייטים בתשובה.
/http/route† המסלול התואם.
"/cart/checkout/:item_id"
/http/status_code† קוד סטטוס של תגובת HTTP.
"200"
/http/url כתובת ה-URL המלאה של בקשת HTTP.
"http://example.com"
/http/user_agent מידע על סוכן המשתמש של HTTP שממנו נשלחה הבקשה.
"python-requests/2.19.1"
/stacktrace דוח קריסות בפורמט JSON. מעקבי ערימה לא נכללים באינדקס לחיפוש.
התווית הזו מוצגת בטבלה Call Stack.
התווית /stacktrace משמשת רק ב-V1 API.
ב-V2 API, השדה span מכיל את השדה stackTrace. 
    "stackTrace": {
      "stackFrames": {
        "frame": [
          {
            "functionName": {
              "value": "serverMethodTrace [as func]"
            },
            "fileName": {
              "value":
              "/usr/src/app/node_modules/@google-cloud/trace-agent/build/src/plugins/plugin-grpc.js"
            },
            "lineNumber": "249",
            "columnNumber": "28"
          },
          {
            "functionName": {
              "value": "anonymous function"
            },
            "fileName": {
              "value": "/usr/src/app/node_modules/grpc/src/server.js"
            },
            "lineNumber": "592",
            "columnNumber": "13"
          }
        ]
      }
    },

†התווית הזו והערך שלה מוצגים בטבלת פרטים שכלולה בתצוגה פרטי מעקב.

תוויות קנוניות ל-GKE

בטבלה הבאה מפורטות כל התוויות הקנוניות של קונטיינר GKE:

שם התצוגה בטבלה GKE Container
מפתח התווית		 תיאור
מזהה פרויקט
g.co/r/k8s_container/project_id		 הפרויקט שמארח את אשכול GKE. Google Cloud לוחצים על שם הפרויקט כדי לעבור אל מרכז הבקרה של GKE במסוף Google Cloud .
מיקום
g.co/r/k8s_container/location		 המיקום הפיזי של אשכול GKE.
שם האשכול
g.co/r/k8s_container/cluster_name 		מזהה את אשכול GKE. כדי לעבור לדף ההגדרות של Clusters, לוחצים על הערך הזה.
Namespace
g.co/r/k8s_container/namespace 		מזהה את מרחב השמות. כדי לעבור לדף Workloads ב-GKE, לוחצים על הערך הזה.
שם ה-Pod
g.co/r/k8s_container/pod_name 		מזהה את ה-Pod של GKE. כדי לעבור ללוח הבקרה פרטי הפודים, לוחצים על הערך הזה.
שם הקונטיינר
g.co/r/k8s_container/container_name 		מזהה את קונטיינר GKE. כדי לעבור לדף הפרטים של מאגר התגים, לוחצים על הערך הזה.

דוגמה

הדוגמה הבאה היא ייצוג חלקי של אובייקט Trace בפורמט JSON שכולל כמה תוויות:

{
  "projectId": "a-sample-project",
  "traceId": "00000000000000004db6dd68e7d37f57",
  "spans": [
    {
      "spanId": "12913864118554233534",
      "kind": "RPC_SERVER",
      "name": "http://192.0.2.0/",
      "startTime": "2024-04-02T19:37:34.149058Z",
      "endTime": "2025-04-02T19:37:34.151136Z",
      "parentSpanId": "5599906629317525335",
      "labels": {
        "/component": "default",
        "/http/host": "192.0.2.0",
        "/http/status_code": "200",
        "/http/url": "http://192.0.2.0/",
        "zipkin.io/http.route": "/**",
        "/http/method": "GET",
        "zipkin.io/endpoint.ipv4": "10.16.1.6",
        "zipkin.io/http.path": "/",
        "zipkin.io/mvc.controller.class": "ResourceHttpRequestHandler"
      }
    }
  ]
}

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

קידומת g.co

במקרים מסוימים, התוויות שמוצגות כוללות את הקידומת g.co. הקידומת g.co מציינת שהתווית הזו נוצרה על ידי שירות של Google. אם אתם מפעילים את השירות ב-App Engine או בתשתית אחרת Google Cloud , יכול להיות שתראו תוויות כמו אלה:

מפתח התווית ערך לדוגמה של תווית
g.co/agent opentelemetry-js 1.18.1; google-cloud-trace-exporter 2.1.0
g.co/r/generic_node/location global

תוויות מותאמות אישית

אתם יכולים ליצור תוויות בהתאמה אישית. אם אתם יוצרים תווית בהתאמה אישית, מומלץ להשתמש בפורמטים הבאים:

  • /category/product/key לסוכנים של מוצרים מוכרים. לדוגמה, /db/mongodb/read_size.
  • short_host/path/key למקשים שספציפיים לדומיין. לדוגמה, g.co/agent.

אם יוצרים הרבה תוויות מותאמות אישית, יכול להיות שתהיה לכך השפעה על הביצועים בגלל העוצמה הגבוהה של התוויות.

כפי שמודגם בקטע דוגמה, אם אתם משתמשים ב-Zipkin collector או בספרייה כמו OpenTelemetry, יכול להיות שיתווספו תוויות לטווחים שלכם.

שימוש ב-OpenTelemetry

אם אתם משתמשים בספריות OpenTelemetry, הקפידו להשתמש במוסכמות הסמנטיות של OpenTelemetry כשאתם יוצרים טווחים.