追蹤記錄標籤

您可以在 Cloud Trace 中使用標籤和屬性，將鍵/值中繼資料 (例如 HTTP 狀態碼、區域名稱或自訂應用程式屬性) 附加至 span，以便篩選、分組及排解要求問題。如果您使用 Cloud Trace API 第 1 版，請在 TraceSpan 物件中使用 labels 欄位新增鍵/值組合。如果您使用 Trace API v2，請使用 Attributes 物件新增中繼資料。

關於標籤和屬性

labels 欄位是儲存為字串的鍵/值組合對應，每個範圍最多可有 1024 個標籤。如需字串長度限制，請參閱 labels 的 API 參考資料。

在「Trace Explorer」頁面探索範圍時，該範圍的標籤會顯示在「Attributes」分頁中，如下列螢幕截圖所示：

Cloud Trace 屬性表範例。

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

預先定義的鍵

標準標籤

下表列出支援的預先定義鍵，包括說明，以及部分情況下的範例：

標籤鍵說明
範例
/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 重新導向前網址。
在這種情況下，請使用金鑰 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 User-Agent 相關資訊。
"python-requests/2.19.1"
/stacktrace JSON 格式的堆疊追蹤。 系統不會為堆疊追蹤建立索引，因此無法搜尋。
這個標籤會顯示在「呼叫堆疊」表格中。
/stacktrace 標籤僅供第 1 版 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		 Google Cloud 代管 GKE 叢集的專案。按一下專案名稱，前往 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」(工作負載) 頁面，請點選這個值。
Pod 名稱
g.co/r/k8s_container/pod_name 		識別 GKE Pod。如要前往「Pod details」(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 程式庫，請務必在建立範圍時使用 OpenTelemetry 語意慣例。