追蹤記錄標籤

Trace 提供一種機制，可讓您在跨度中加入有意義的資料。如果您使用的是 Cloud Trace API 第 1 版，可以使用 Cloud Trace API TraceSpan 物件中的 labels 欄位新增標籤 (鍵/值組)。如果您使用的是 Cloud Trace API v2，可以使用 Attributes 物件新增資訊。

探索時距時，該時距的標籤會顯示在「Attributes」分頁中。例如，下圖顯示這個分頁：

Cloud Trace 屬性表格範例。

如要瞭解如何存取這項資訊，請參閱「尋找及探索追蹤記錄」。

labels 欄位是鍵/值組合的對應關係，這些鍵和值會以字串形式儲存。如需字串長度限制的相關資訊，請參閱 labels 的 API 參考資料。

每個區間的標籤上限為 32 個。

預先定義的鍵

標準標籤

下表列出支援的預先定義鍵，並附上說明，在某些情況下還會附上範例：

標籤鍵說明
範例
/agent 追蹤代理程式 ID。
"node@google-cloud/trace-agent v3.0.0"
/component 元件 ID。
"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 通訊協定 ID。
"1.0"
/http/client_region 用戶端的區域。
"us-east4"
/http/host 主機標頭的值。
"default.example.com"
/http/method† 設為 HTTP 要求方法。
請勿在非 HTTP 要求中加入這個索引鍵。
"GET"
/http/path† 要求網址路徑。
"/cart/checkout"
/http/redirected_url 重新導向前的網址。
在這種情況下，請使用主要 HTTL 網址標籤來儲存最終到達網址。
/http/request/size 要求中的位元組數。
/http/response/size 回應中的位元組數。
/http/route† 相符的路由。
"/cart/checkout/:item_id"
/http/status_code† HTTP 回應狀態碼。
"200"
/http/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"
          }
        ]
      }
    },

†這個標籤及其值會顯示在「Trace details」檢視畫面中的「Details」表格中。

GKE 的標準標籤

下表列出 GKE 容器的所有標準化標籤：

GKE Container 表格中的顯示名稱
標籤鍵		 說明
專案 ID
g.co/r/k8s_container/project_id		 託管 GKE 叢集的 Google Cloud 專案。按一下專案名稱，前往 Google Cloud 主控台的 GKE 資訊主頁。
位置
g.co/r/k8s_container/location		 GKE 叢集的實際位置。
叢集名稱
g.co/r/k8s_container/cluster_name 		用於識別 GKE 叢集。如要前往「Clusters」(叢集) 設定頁面，請點選這個值。
命名空間
g.co/r/k8s_container/namespace 		用於識別命名空間。如要前往 GKE「Workloads」(工作負載) 頁面，請按一下這個值。
廣告連播名稱
g.co/r/k8s_container/pod_name 		用於識別 GKE Pod。如要前往「Pods 詳細資料」資訊主頁，請按一下這個值。
容器名稱
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 收集器或 OpenTelemetry 等程式庫，可能會在追蹤區間中加入標籤。

使用 OpenTelemetry

如果您使用的是 OpenTelemetry 程式庫，請務必在建立跨度時使用 OpenTelemetry 語意慣例。