O Trace fornece um mecanismo para você adicionar dados significativos aos seus períodos. Se você estiver usando a API Cloud Trace V1,
é possível adicionar rótulos, que são pares de chave-valor, usando o campo
labels
no
objeto TraceSpan
da API Cloud Trace.
Se você estiver usando a API Cloud Trace V2, poderá adicionar informações
com um objeto Attributes
.
Para mais informações, consulte
Adicionar anotações de evento a intervalos de rastreamento.
Quando você analisa um período, os rótulos dele aparecem na guia Atributos. Por exemplo, a captura de tela a seguir ilustra essa guia:
Para saber como acessar essas informações, consulte Encontrar e explorar traces.
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
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 de rótulo | Descriçã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:
|
/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. 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 de rótulo |
Descrição |
---|---|
ID do projetog.co/r/k8s_container/project_id |
O projeto do Google Cloud que hospeda o cluster do GKE. Clique no nome do projeto para acessar Painel do GKE no console do Google Cloud. |
Localg.co/r/k8s_container/location |
O local físico do cluster do GKE. |
Nome do clusterg.co/r/k8s_container/cluster_name
|
Identifica o cluster do GKE. Para acessar a página de configuração Clusters, clique nesse valor. |
Namespaceg.co/r/k8s_container/namespace
|
Identifica o namespace. Para acessar a página Cargas de trabalho do GKE, clique nesse valor. |
Nome do podg.co/r/k8s_container/pod_name
|
Identifica o pod do GKE. Clique no valor para acessar o painel Detalhes do pod. |
Nome do contêinerg.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://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 rastro anterior 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
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 |
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.
Conforme ilustrado na seção Exemplo, se você usar um coletor Zipkin ou uma biblioteca como o OpenTelemetry, isso poderá adicionar rótulos aos períodos de trace.
Como usar o OpenTelemetry
Se você estiver usando bibliotecas do OpenTelemetry, use o Convenções semânticas do OpenTelemetry ao criar períodos.