Rótulos de trace

O Trace fornece um mecanismo para você anotar seus períodos com dados significativos. Se você estiver usando a API Cloud Trace V1, crie essas anotações usando o campo labels no objeto TraceSpan da API Cloud Trace. Se você estiver usando a API Cloud Trace V2, poderá fazer anotações com atributos. Para mais informações sobre as opções de anotação, consulte Como anotar períodos.

A maioria dos rótulos é exibida na tabela Rótulos quando a Visualização da hierarquia Trace é exibida:

Página de lista de traces com rótulos e um trace de pilha exibidos.

Há dois outros locais onde os rótulos são exibidos. O painel Detalhes lista os rótulos HTTP mais comuns, enquanto a tabela Rastreamento de chamadas lista o conteúdo do rótulo stacktrace.

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

Há um limite de 32 rótulos por período.

Chaves predefinidas

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

Chave de 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.
Neste caso, use o rótulo de URL HTTL 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 Trace de pilha formatado em JSON. Os traces de pilha não são indexados para pesquisa.
Esse rótulo é exibido na tabela Pilha de chamadas.

    "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.

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://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"
      }
    }
  ]
}

O trace acima foi retirado de um sistema usando um coletor 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 na Visualização da hierarquia Trace 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 do Google Cloud, poderá ver rótulos como os seguintes:

Chave de rótulo Exemplo de valor do rótulo
g.co/agent opencensus-go[0.15.0]
g.co/gce/instanceid 12345678900000000

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 centenas ou milhares de rótulos personalizados, isso poderá gerar impacto no desempenho devido ao aumento da cardinalidade do rótulo.

Conforme ilustrado na seção Exemplo, se você usar um coletor Zipkin ou uma biblioteca como OpenCensus, isso poderá adicionar rótulos aos períodos de trace.

Como usar o OpenCensus

Se você estiver usando bibliotecas do OpenCensus, será necessário usar o nome do atributo do OpenCensus. Para encontrar uma tabela que cruze o nome do atributo do OpenCensus com o nome do rótulo predefinido do Cloud Trace, consulte Atributos.