トレースには、スパンに意味のあるデータを追加するためのメカニズムがあります。 Cloud Trace API V1 を使用している場合は、Cloud Trace API の TraceSpan オブジェクトの labels フィールドを使用して、Key-Value ペアのラベルを追加できます。Cloud Trace API V2 を使用している場合は、Attributes オブジェクトを使用して情報を追加できます。詳細については、トレーススパンへのイベント アノテーションの追加をご覧ください。
スパンを調べる際に、そのスパンのラベルが [属性] タブに表示されます。たとえば、次のスクリーンショットは、このタブを示しています。
この情報にアクセスする方法については、トレースを検索して調査するをご覧ください。
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:
|
/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 コンテナ テーブルの表示名 ラベルキー |
説明 |
|---|---|
プロジェクト IDg.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 クラスタを識別します。[クラスタ] 構成ページに移動するには、この値をクリックします。 |
名前空間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://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
表示されるラベルに 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 セマンティック規則を必ず使用してください。