Etiquetas de rastreio

O rastreio oferece um mecanismo para adicionar dados significativos aos seus intervalos. Se estiver a usar a API Cloud Trace V1, pode adicionar etiquetas, que são pares de chaves-valores, usando o campo labels no objeto API Cloud Trace TraceSpan. Se estiver a usar a API Cloud Trace V2, pode adicionar informações com um objeto Attributes.

Quando explora um intervalo, as etiquetas desse intervalo são apresentadas no separador Atributos. Por exemplo, a seguinte captura de ecrã ilustra este separador:

Exemplo da tabela de atributos do Cloud Trace.

Para obter informações sobre como aceder a estas informações, consulte o artigo Encontre e explore rastreios.

O campo labels é um mapa de pares de chave-valor. As chaves e os valores são armazenados como strings. Para restrições de comprimento de strings, consulte a referência da API para labels.

Existe um limite de 32 etiquetas por intervalo.

Chaves predefinidas

Etiquetas canónicas

A tabela seguinte apresenta as chaves predefinidas suportadas, inclui uma descrição e, em alguns casos, inclui um exemplo:

Chave da etiquetaDescrição
Exemplo
/agent Identificador do agente de rastreio.
"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 a apresentar 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 anfitrião.
"default.example.com"
/http/method† Definido para o método de pedido HTTP.
Não inclua esta chave para pedidos não HTTP.
"GET"
/http/path† Caminho do URL do pedido.
"/cart/checkout"
/http/redirected_url O URL antes do redirecionamento.
Neste caso, use a etiqueta do URL HTTL para armazenar o URL final.
/http/request/size Número de bytes no pedido.
/http/response/size Número de bytes na resposta.
/http/route† O trajeto correspondente.
"/cart/checkout/:item_id"
/http/status_code† Código de estado da resposta HTTP.
"200"
/http/url URL do pedido HTTP completo.
"http://example.com"
/http/user_agent Informações sobre o agente do utilizador HTTP que originou o pedido.
"python-requests/2.19.1"
/stacktrace Rastreio da pilha formatado em JSON. Os rastreios de pilha não são indexados para a pesquisa.
Esta etiqueta é apresentada na tabela Call Stack.
A etiqueta /stacktrace só é usada pela API V1.
Para a API V2, o span contém 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"
          }
        ]
      }
    },

†Esta etiqueta e o respetivo valor são apresentados na tabela Detalhes incluída na vista Detalhes do rastreio.

Etiquetas canónicas para o GKE

A tabela seguinte apresenta todas as etiquetas canónicas para um contentor do GKE:

Nome a apresentar na tabela GKE Container
Chave de etiqueta		 Descrição
ID do projeto
g.co/r/k8s_container/project_id		 O Google Cloud projeto que aloja o cluster do GKE. Clique no nome do projeto para aceder ao painel de controlo do GKE na Google Cloud consola.
Localização
g.co/r/k8s_container/location		 A localização física do cluster do GKE.
Nome do cluster
g.co/r/k8s_container/cluster_name 		Identifica o cluster do GKE. Para aceder à página de configuração de clusters, clique neste valor.
Espaço de nomes
g.co/r/k8s_container/namespace 		Identifica o espaço de nomes. Para aceder à página Cargas de trabalho do GKE, clique neste valor.
Nome do agrupamento
g.co/r/k8s_container/pod_name 		Identifica o pod do GKE. Para aceder ao painel de controlo Detalhes dos pods, clique neste valor.
Nome do contentor
g.co/r/k8s_container/container_name 		Identifica o contentor do GKE. Para aceder à página de detalhes do contentor, clique neste valor.

Exemplo

Segue-se uma representação JSON parcial de um objeto Trace que inclui várias etiquetas:

{
  "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 rastreio anterior foi feito a partir de um sistema que usa um coletor Zipkin. Neste caso, as etiquetas com chaves zipkin.io foram adicionadas por esse coletor.

Prefixo g.co

Em alguns casos, as etiquetas apresentadas contêm o prefixo g.co. O prefixo g.co indica que esta etiqueta foi gerada por um serviço Google. Se estiver a executar o seu serviço no App Engine ou noutra infraestrutura, pode ver etiquetas como as seguintes: Google Cloud

Chave da etiqueta Valor da etiqueta de exemplo
g.co/agent opentelemetry-js 1.18.1; google-cloud-trace-exporter 2.1.0
g.co/r/generic_node/location global

Etiquetas personalizadas

Pode criar etiquetas personalizadas. Se criar uma etiqueta personalizada, recomendamos que use 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 criar muitas etiquetas personalizadas, isso pode ter um impacto no desempenho devido ao aumento da cardinalidade das etiquetas.

Conforme ilustrado na secção Exemplo, se usar um coletor Zipkin ou uma biblioteca, como o OpenTelemetry, pode adicionar etiquetas aos intervalos de rastreio.

Usar o OpenTelemetry

Se estiver a usar bibliotecas do OpenTelemetry, certifique-se de que usa as convenções semânticas do OpenTelemetry ao criar intervalos.