跟踪记录标签

Trace 提供了一种机制，可让您向 span 添加有意义的数据。如果您使用的是 Cloud Trace API V1，则可以使用 Cloud Trace API TraceSpan 对象中的 labels 字段添加标签（即键值对）。如果您使用的是 Cloud Trace API V2，则可以使用 Attributes 对象添加信息。

探索某个 span 时，该 span 的标签会显示在属性标签页中。例如，以下屏幕截图展示了此标签页：

Cloud Trace 属性表示例。

如需了解如何访问此类信息，请参阅查找和探索跟踪记录。

labels 字段是键值对的映射。其中的键和值以字符串形式存储。如需了解字符串长度限制，请参阅 labels 的 API 参考。

每个 span 最多只能有 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† 请求网址路径。
"/cart/checkout"
/http/redirected_url 重定向前的网址。
在本例中，请使用键 HTTL 网址标签存储最终到达网址。
/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"
          }
        ]
      }
    },

†此标签及其值显示在 Trace 详情视图中包含的详情表中。

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 集群。要转到集群配置页面，请点击此值。
命名空间
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 收集器或 OpenTelemetry 等库，则可能会向 Trace span 添加标签。

使用 OpenTelemetry

如果您使用的是 OpenTelemetry 库，请确保在创建 span 时使用 OpenTelemetry 语义惯例。