Instrumento para o Cloud Trace

Neste documento, você encontra uma visão geral sobre como instrumentar seu aplicativo para o Cloud Trace. Para instruções detalhadas sobre como configurar o Cloud Trace, consulte as páginas de configuração específicas da linguagem.

O Cloud Trace fornece dados de geração de trace distribuídos para seus aplicativos. Depois de instrumentar seu aplicativo, você pode inspecionar os dados de latência de uma única solicitação e ver a latência agregada de um aplicativo inteiro no console do Cloud Trace.

Quando instrumentar seu aplicativo

Quando os dados de rastreamento não são capturados automaticamente, você precisa instrumentar seu app para coletar esses dados.

É possível instrumentar seu aplicativo para que ele colete informações específicas do aplicativo. Vários frameworks de instrumentação de código aberto permitem coletar métricas, registros e rastreamentos do seu aplicativo e enviar esses dados para qualquer fornecedor, incluindo o Google Cloud. Para instrumentar seu aplicativo, recomendamos que você use uma estrutura de instrumentação neutra de fornecedores e que seja de código aberto, como o OpenTelemetry, em vez de APIs específicas do fornecedor e do produto. ou bibliotecas de cliente.

Para informações sobre como instrumentar seus aplicativos usando estruturas de instrumentação neutras de fornecedores, consulte Instrumentação e observabilidade.

Como instrumentar aplicativos

Para conferir recomendações sobre como instrumentar seus aplicativos para coletar registros, métricas e traces, consulte Escolher uma abordagem de instrumentação.

Para instrumentar seus aplicativos para coletar dados de rastreamento, é possível realizar uma das seguintes ações:

Quando criar períodos

As bibliotecas de cliente do Cloud Trace normalmente mantêm um contexto de trace global que contém informações sobre o período atual, incluindo o ID do trace e se o trace é amostrado. Essas bibliotecas geralmente criam períodos nos limites da RPC. No entanto, talvez seja necessário criar períodos se o algoritmo de criação padrão não for suficiente para suas necessidades.

O período ativo atual pode ser acessado pelo contexto de trace global, que às vezes é agrupado em um objeto Trace. É possível adicionar informações relevantes ao aplicativo usando anotações e tags personalizadas em períodos existentes ou criar novos intervalos filhos com as próprias anotações e tags para rastrear o comportamento do aplicativo com granularidade mais precisa. Como o contexto é global, os aplicativos com várias linhas de execução que atualizam o contexto precisam usar o isolamento adequado.

Quando fornecer credenciais de autenticação

Geralmente, não é necessário fornecer credenciais de autenticação ao aplicativo nem especificar o ID do projeto do Google Cloud nele quando você estiver executando no Google Cloud. Para algumas linguagens, você precisa especificar o ID do projeto do Google Cloud, mesmo que esteja em execução no Google Cloud. Além disso, se você usar o modo Autopilot para Google Kubernetes Engine ou ativar a Identidade da carga de trabalho, será necessário configurar seu aplicativo para usá-la.

Se você estiver executando fora do Google Cloud, precisará fornecer credenciais de autenticação ao aplicativo. Você também precisa especificar o ID do projeto do Google Cloud no aplicativo.

Para mais detalhes, acesse as páginas de configuração de linguagens específicas.

Como forçar o rastreamento de uma solicitação

O Cloud Trace não cria amostras de todas as solicitações. Alguns pacotes, como o OpenTelemetry, oferecem suporte à configuração da taxa de amostragem. Por padrão, o OpenTelemetry faz a amostragem de todos os traces.

Se você configurar um microsserviço com uma taxa de amostragem, a taxa será aplicada somente às solicitações iniciadas a ele. Se você não configurar uma taxa de amostragem para um microsserviço, a taxa de amostragem do contexto principal determinará a do microsserviço.

Para forçar a geração de trace de uma solicitação específica, adicione um cabeçalho X-Cloud-Trace-Context à solicitação. A especificação do cabeçalho é:

"X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=TRACE_TRUE"

Em que:

  • TRACE_ID é um valor hexadecimal de 32 caracteres que representa um número de 128 bits. Ele precisa ser exclusivo entre as solicitações, a menos que você queira agrupar intencionalmente as solicitações.

  • SPAN_ID é a representação decimal do ID de período (não assinado). Ele precisa ser gerado aleatoriamente e exclusivamente no seu trace. Para solicitações subsequentes, defina SPAN_ID como o ID do período da solicitação pai. Consulte a descrição de TraceSpan (REST, RPC) para mais informações sobre traces aninhados.

  • TRACE_TRUE precisa ser 1 para rastrear essa solicitação. Especifique 0 para não rastrear a solicitação.

Por exemplo, para forçar um trace com cURL:

curl "http://www.example.com" --header "X-Cloud-Trace-Context:
  105445aa7843bc8bf206b12000100000/1;o=1"

Ative a API Cloud Trace

Para usar o Cloud Trace, seu projeto do Google Cloud precisa ter a API Cloud Trace ativada. Essa configuração permite que seu projeto do Google Cloud receba dados de trace de fontes autenticadas. Por padrão, os projetos do Google Cloud têm a API Cloud Trace ativada, e você não precisa fazer nada. No entanto, talvez seja necessário ativar a API Cloud Trace se você tiver modificado os escopos de acesso do projeto do Google Cloud.

Para ativar a API Cloud Trace, faça o seguinte:

  1. No painel de navegação do console do Google Cloud, selecione APIs e serviços, clique em Ativar APIs e serviços e ative a API Cloud Trace:

    Acessar as configurações da API Cloud Trace

  2. Se a mensagem API ativada for exibida, quer dizer que a API já está ativada. Caso contrário, clique no botão Ativar.

A seguir

Para informações detalhadas de configuração, amostras e links para o GitHub e outros repositórios de código aberto, acesse a página de configuração da sua linguagem: