Rótulos de trace

Com os rótulos e atributos do Cloud Trace, é possível anexar metadados de chave-valor, como códigos de status HTTP, nomes de regiões ou propriedades personalizadas de aplicativos, aos intervalos para filtrar, agrupar e resolver problemas de solicitações. Se você usa a API Cloud Trace v1, adicione pares de chave-valor usando o campo labels no objeto TraceSpan. Se você usar a API Trace v2, adicione metadados usando um objeto Attributes.

Sobre rótulos e atributos

O campo labels é um mapa de pares de chave-valor armazenados como strings, com um limite de 1.024 rótulos por período. Para restrições de comprimento de string, consulte a referência da API para labels.

Ao analisar um período na página Explorador de traces, os rótulos desse período são mostrados na guia Atributos, conforme mostrado na captura de tela a seguir:

Exemplo da tabela de atributos do Cloud Trace.

Para informações sobre como acessar esses dados, consulte Encontrar e explorar traces.

Chaves predefinidas

Rótulos canônicos

A tabela a seguir lista as chaves predefinidas compatíveis, inclui uma descrição e, em alguns casos, inclui um exemplo:

Chave do rótuloDescrição
Exemplo
/agent Identificador do agente de rastreamento.
"node@google-cloud/trace-agent v3.0.0"
/component Identificador do componente.
"grpc"
/error/message Uma mensagem de erro.
"Rendezvous of RPC that terminated with:
status = StatusCode.UNAVAILABLE details = OS Error."
/error/name Nome de exibição do erro.
/http/client_city A cidade do cliente.
"NYC"
/http/client_country O país do cliente.
"US"
/http/client_protocol Identificador do protocolo HTTP.
"1.0"
/http/client_region A região do cliente.
"us-east4"
/http/host O valor do Cabeçalho do host.
"default.example.com"
/http/method† Defina como o método de solicitação HTTP.
Não inclua essa chave em solicitações não HTTP.
"GET"
/http/path† Caminho do URL de solicitação.
"/cart/checkout"
/http/redirected_url O URL antes do redirecionamento.
Nesse caso, use o rótulo "URL HTTP da chave" para armazenar o URL final.
/http/request/size Número de bytes na solicitação.
/http/response/size Número de bytes na resposta.
/http/route† A rota correspondente.
"/cart/checkout/:item_id"
/http/status_code† Código de status de resposta HTTP.
"200"
/http/url URL de solicitação HTTP completo.
"http://example.com"
/http/user_agent Informações sobre o user agent HTTP que originou a solicitação.
"python-requests/2.19.1"
/stacktrace Stack trace formatado em JSON. Os traces de pilha não são indexados para pesquisa.
Esse rótulo é exibido na tabela Pilha de chamadas.
O rótulo /stacktrace é usado apenas pela API V1.
Para a API V2, o span tem um campo 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"
          }
        ]
      }
    },

†Esse rótulo e seu valor são exibidos na tabela Detalhes que está incluída na visualização Detalhes do trace.

Rótulos canônicos para o GKE

A tabela a seguir lista todos os rótulos canônicos de um contêiner do GKE:

Nome de exibição na tabela Contêiner do GKE
Chave do rótulo		 Descrição
ID do projeto
g.co/r/k8s_container/project_id		 O projeto Google Cloud que hospeda o cluster do GKE. Clique no nome do projeto para acessar o painel do GKE no console do Google Cloud .
Local
g.co/r/k8s_container/location		 O local físico do cluster do GKE.
Nome do cluster
g.co/r/k8s_container/cluster_name 		Identifica o cluster do GKE. Para acessar a página de configuração Clusters, clique nesse valor.
Namespace
g.co/r/k8s_container/namespace 		Identifica o namespace. Para acessar a página Cargas de trabalho do GKE, clique nesse valor.
Nome do pod
g.co/r/k8s_container/pod_name 		Identifica o pod do GKE. Clique no valor para acessar o painel Detalhes do pod.
Nome do contêiner
g.co/r/k8s_container/container_name 		Identifica o contêiner do GKE. Para acessar a página de detalhes do contêiner, clique nesse valor.

Exemplo

Veja a seguir uma representação JSON parcial de um objeto Trace que inclui vários rótulos:

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

O rastreamento anterior foi feito em um sistema que usa um coletor do Zipkin. Nesse caso, os rótulos com chaves zipkin.io foram adicionados por esse coletor.

Prefixo g.co

Em alguns casos, os rótulos exibidos contêm um prefixo g.co. O prefixo g.co indica que esse rótulo foi gerado por um serviço do Google. Se você estiver executando seu serviço no App Engine ou em outra infraestrutura Google Cloud , poderá encontrar rótulos como estes:

Chave do rótulo Exemplo de valor do rótulo
g.co/agent opentelemetry-js 1.18.1; google-cloud-trace-exporter 2.1.0
g.co/r/generic_node/location global

Rótulos personalizados

Você pode criar rótulos personalizados. Se você criar um rótulo personalizado, recomendamos usar os seguintes formatos:

  • /category/product/key para agentes de produtos conhecidos. Por exemplo, /db/mongodb/read_size;
  • short_host/path/key para chaves específicas do domínio. Por exemplo, g.co/agent.

Se você criar vários rótulos personalizados, isso poderá gerar impacto no desempenho devido ao aumento da cardinalidade do rótulo.

Como ilustrado na seção Exemplo, se você usar um coletor do Zipkin ou uma biblioteca como o OpenTelemetry, ela poderá adicionar rótulos aos intervalos de rastreamento.

Como usar o OpenTelemetry

Se você estiver usando bibliotecas do OpenTelemetry, use as Convenções semânticas do OpenTelemetry ao criar períodos.