トレースラベル

トレースには、スパンに意味のあるデータのアノテーションを付けるメカニズムがあります。Cloud Trace API V1 を使用している場合は、Cloud Trace API TraceSpan オブジェクトの labels フィールドを使用してこれらのアノテーションを作成します。Cloud Trace API V2 を使用している場合は、属性でアノテーションを付けることができます。アノテーション オプションの詳細については、スパンにアノテーションを付けるをご覧ください。

ほとんどのラベルは、Trace のウォーターフォール ビューが表示されているときに、ラベルのテーブルに表示されます。

ラベルとスタック トレースが表示されたトレースリストのページ。

ラベルが表示される場所は他にもあります。

  • [詳細] ペインには、最も一般的な HTTP ラベルが一覧表示されます。
  • [トレース呼び出し] テーブルには、stacktrace ラベルの内容が一覧表示されます。このテーブルは、スパンにスタック トレースが含まれている場合にのみ表示されます。
  • GKE コンテナ テーブルには、GKE コンテナの正規ラベルが表示されます。テーブル内の各行は、特定のラベルに対するものであり、値はリソースに関する情報をより詳しく表示するために使用できるリンクです。

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": {
      "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 コンテナのすべての正規ラベルを一覧表示したものです。

ラベル
Project ID GKE クラスタをホストする Google Cloud プロジェクト。プロジェクト名をクリックし、Google Cloud Console の GKE ダッシュボードに移動します。
Cluster Name GKE クラスタを識別します。この値をクリックして、[クラスタ構成] ページに移動します。
Namespace 名前空間を識別します。この値をクリックして、GKE の [ワークロード] ページに移動します。
Pod Name GKE Pod を識別します。この値をクリックして、Pod の詳細ダッシュボードに移動します。
Container Name GKE コンテナを識別します。この値をクリックして、コンテナの [詳細] ページに移動します。

以下は、複数のラベルを含む Trace オブジェクトの JSON 表現の一部です。

{
  "projectId": "a-sample-project",
  "traceId": "00000000000000004db6dd68e7d37f57",
  "spans": [
    {
      "spanId": "12913864118554233534",
      "kind": "RPC_SERVER",
      "name": "http://xx.xxx.xxx.xxx/",
      "startTime": "2019-04-02T19:37:34.149058Z",
      "endTime": "2019-04-02T19:37:34.151136Z",
      "parentSpanId": "5599906629317525335",
      "labels": {
        "/component": "default",
        "/http/host": "xx.xxx.xxx.xxx",
        "/http/status_code": "200",
        "/http/url": "http://xx.xxx.xxx.xxx/",
        "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

Trace のウォーターフォール ビューに表示されるラベルには、g.co 接頭辞が含まれている場合があります。g.co 接頭辞は、このラベルが Google サービスによって生成されたことを示します。App Engine またはその他の Google Cloud インフラストラクチャでサービスを実行している場合は、次のようなラベルが表示されることがあります。

ラベルキー ラベルの値の例
g.co/agent opencensus-go[0.15.0]
g.co/gce/instanceid 12345678900000000

カスタムラベル

カスタムラベルを作成できます。カスタムラベルを作成する場合は、次の形式を使用することをおすすめします。

  • 良く知られたプロダクトのエージェントの場合は /category/product/key。例: /db/mongodb/read_size
  • ドメイン固有のキーの場合は short_host/path/key。例: g.co/agent

何百、何千ものカスタムラベルを作成すると、ラベルのカーディナリティが増加するため、パフォーマンスに影響をおよぼす可能性があります。

のセクションで説明したように、Zipkin コレクタまたは OpenCensus などのライブラリを使用する場合、トレーススパンにラベルが追加されることがあります。

OpenCensus の使用

OpenCensus ライブラリを使用している場合は、OpenCensus の属性名を使用する必要があります。OpenCensus の属性名と Cloud Trace の事前定義されたラベル名が相互掲載されたテーブルを見つけるには、属性をご覧ください。