תוויות מעקב

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

מידע על תוויות ומאפיינים

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

כשבוחרים יחידה לוגית למעקב בדף Trace Explorer, התוויות של היחידה הלוגית למעקב הזו מוצגות בכרטיסייה Attributes, כמו בצילום המסך הבא:

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

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

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

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

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

מפתח התוויתתיאור
דוגמה
/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 לפני ההפניה האוטומטית.
במקרה כזה, משתמשים בתווית של כתובת ה-URL של HTTP כדי לאחסן את כתובת ה-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.
ב-API בגרסה 2, השדה 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"
          }
        ]
      }
    },

†התווית הזו והערך שלה מוצגים בטבלת Details שכלולה בתצוגה Trace details.

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

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

השם המוצג בטבלה GKE Container
מפתח התווית		 תיאור
מזהה פרויקט
g.co/r/k8s_container/project_id		 הפרויקט Google Cloud שמארח את אשכול GKE. לוחצים על שם הפרויקט כדי לעבור למרכז הבקרה של 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.

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

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

שימוש ב-OpenTelemetry

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