追蹤記錄標籤

追蹤記錄提供機制，可讓您在跨度中新增有意義的資料。如果您使用 Cloud Trace API V1，可以透過 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 「Host Header」的值。
"default.example.com"
/http/method† 設為 HTTP 要求方法。
請勿為非 HTTP 要求加入這個金鑰。
"GET"
/http/path† 要求網址路徑。
"/cart/checkout"
/http/redirected_url 重新導向前網址。
在本例中，請使用金鑰 HTTP 網址標籤儲存最終到達網址。
/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 格式的堆疊追蹤。 系統不會為堆疊追蹤建立索引，因此無法搜尋。
這個標籤會顯示在「呼叫堆疊」表格中。
/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 容器」表格中的顯示名稱
標籤鍵		 說明
專案 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。如要前往「Pod 詳細資料」資訊主頁，請按一下這個值。
容器名稱
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 程式庫，請務必在建立 span 時使用 OpenTelemetry 語意慣例。