トレースラベル

トレースには、スパンに意味のあるデータを追加するためのメカニズムがあります。 Cloud Trace API V1 を使用している場合は、Cloud Trace API の TraceSpan オブジェクトの labels フィールドを使用して、Key-Value ペアのラベルを追加できます。Cloud Trace API V2 を使用している場合は、Attributes オブジェクトを使用して情報を追加できます。

スパンを調べる際に、そのスパンのラベルが [属性] タブに表示されます。たとえば、次のスクリーンショットは、このタブを示しています。

Cloud Trace 属性テーブルの例。

この情報にアクセスする方法については、トレースを検索して調査するをご覧ください。

labels フィールドは、Key-Value ペアのマップです。キーと値は文字列として保存されます。文字列の長さの制限については、labels の API リファレンスをご覧ください。

スパンあたりのラベル数の上限は 32 です。

事前定義されたキー

正規ラベル

次のテーブルに、サポートされている事前定義済みのキーとその説明が示されています。次の内容が含まれていることもあります。

ラベルキー説明
例
/agent Trace エージェントの識別子。
"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† HTTP リクエスト メソッドに設定します。
HTTP 以外のリクエストにはこのキーを含めないでください。
"GET"
/http/path† Request-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 完全な HTTP リクエスト URL。.
"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 プロジェクト。プロジェクト名をクリックして、コンソールの GKE ダッシュボードに移動します。 Google Cloud
ロケーション
g.co/r/k8s_container/location		 GKE クラスタの物理的な場所。
クラスタ名
g.co/r/k8s_container/cluster_name 		GKE クラスタを識別します。[クラスタ] 構成ページに移動するには、この値をクリックします。
名前空間
g.co/r/k8s_container/namespace 		名前空間を識別します。GKE ワークロード ページに移動するには、この値をクリックします。
Pod 名
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 コレクタまたは OpenCensus などのライブラリを使用する場合、トレーススパンにラベルが追加されることがあります。

OpenTelemetry を使用する

OpenTelemetry ライブラリを使用している場合は、スパンの作成時に OpenTelemetry セマンティック規則を必ず使用してください。