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:
É possível usar o OpenTelemetry e o exportador do Cloud Trace associado para as seguintes linguagens de programação:
SDK do OpenTelemetry Exemplo SDK do C++ Exemplo de C++ Go SDK Exemplo em Go SDK do Java Exemplo em Java SDK do Node.js Exemplo de Node.js SDK do Python Exemplo em Python SDK do Ruby Consulte a documentação do OpenTelemetry. Se você estiver escrevendo aplicativos que são executados no Compute Engine, poderá usar o Agente de operações e o receptor do OpenTelemetry Protocol (OTLP) para coletar traces e métricas do seu aplicativo. O Agente de operações também pode coletar registros, mas não usando o OTLP. Para mais informações, consulte Usar o Agente de operações e o OTLP e Visão geral do Agente de operações.
É possível usar as bibliotecas de cliente ou chamar diretamente a API Cloud Trace para enviar dados de rastreamento ao Cloud Trace. No entanto, recomendamos usar o OpenTelemetry quando sua linguagem for compatível com essa biblioteca.
É possível configurar um servidor Zipkin para receber traces de clientes do Zipkin e, em seguida, encaminhá-los ao Cloud Trace para análise. Para informações sobre essa abordagem, consulte Como usar o Cloud Trace com Zipkin.
É possível configurar aplicativos Spring Boot para encaminhar os dados de trace coletados para o Cloud Trace. Para informações sobre este procedimento, consulte Spring Cloud para Google Cloud: Cloud Trace.
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
Em geral, a menos que seu aplicativo sempre faça amostras de todos os períodos, não é possível forçar o rastreamento de uma solicitação de ponta a ponta, porque cada componente em uma solicitação de ponta a ponta toma a própria decisão de amostragem. No entanto, é possível influenciar a
decisão adicionando ao cabeçalho do trace uma flag sampled,
com essa flag definida como true. Essa configuração é uma dica para os componentes filhos
fazerem uma amostra da solicitação.
Para mais informações sobre cabeçalhos de rastreamento, consulte
Protocolos para propagação de contexto.
Para componentes downstream que têm seu código, é necessário determinar se
a lógica de instrumentação respeita a sinalização sampled.
Por exemplo, ao usar o OpenTelemetry
para instrumentação, use o sampler ParentBased
para garantir que a flag mãe amostrada seja respeitada.
Os serviços do Google Cloud que registram informações de rastreamento no Cloud Trace geralmente aceitam a sinalização de amostragem pai como uma dica. No entanto, a maioria dos serviços também oferece amostragem de limite de taxa. Cada serviço do Google Cloud determina se oferece suporte a rastreamento, como a sinalização de amostragem pai é usada e o limite de taxa na amostragem.
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:
-
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:
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:
Exemplos do OpenTelemetry:
Exemplos de biblioteca de cliente: