Trace labels

Trace provides a mechanism for you to add meaningful data to your spans. If you are using the Cloud Trace API V1, you can add labels, which are key-value pairs, by using the labels field in the Cloud Trace API TraceSpan object. If you are using the Cloud Trace API V2, you can add information by with an Attributes object.

When you explore a span, labels for that span are displayed in the Attributestab. For example, the following screenshot illustrates this tab:

For information about how to access this information, see Find and explore traces .

The labels field is a map of key-value pairs. They keys and values are stored as strings. For string length restrictions, see the API reference for labels .

There is a limit of 32 labels per span.

Predefined keys

Canonical labels

The following table lists the supported predefined keys, includes a description, and in some cases, includes an example:

 "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"
          }
        ]
      }
    }, 

† This label and its value are displayed in the Detailstable that is included in the Trace detailsview.

Canonical labels for GKE

The following table lists all of the canonical labels for a GKE container:

Example

The following is a partial JSON representation of a Trace object that includes multiple labels:

{
  "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"
      }
    }
  ]
}

The previous trace was taken from a system using a Zipkin collector. In this case, the labels with zipkin.io keys were added by that collector.

Prefix g.co

In some cases, the displayed labels contain a g.co prefix. The g.co prefix indicates that this label was generated by a Google service. If you are running your service on App Engine or other Google Cloud infrastructure, you might see labels such as the following:

Custom labels

You can create custom labels. If you create a custom label, we recommend that you use the following formats:

• /category/product/key for agents of well-known products. For example, /db/mongodb/read_size .
• short_host/path/key for domain-specific keys. For example, g.co/agent .

If you create a lot of custom labels, then that might incur performance impacts due to the increased label cardinality.

As illustrated in the Example section, if you use a Zipkin collector or a library such as OpenTelemetry, it might add labels to your trace spans.

Using OpenTelemetry

If you are using OpenTelemetry libraries, then ensure you use the OpenTelemetry Semantic Conventions when creating spans.