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, é preciso instrumentar seu aplicativo para coletar esses dados.
Você pode 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 traces do aplicativo e enviar esses dados a 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 mais informações sobre como instrumentar seus aplicativos usando estruturas de instrumentação neutras de fornecedores, consulte Instrumentação e observabilidade (em inglês).
Como instrumentar aplicativos
Para instrumentar seus aplicativos e coletar dados de trace, você pode fazer 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 Go SDK Exemplo de rastreamento e métricas para Go SDK do Java Exemplo de rastreamento e métricas para Java SDK do Node.js Exemplo de traces e métricas para Node.js SDK do Python Exemplo de traces e métricas para Python SDK C++ Exemplo de trace para C++ SDK do Ruby Consulte a documentação do OpenTelemetry. Se você estiver escrevendo aplicativos 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 aplicativo. O Agente de operações também pode coletar mas não pelo 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 geração de trace ao Cloud Trace. No entanto, recomendamos que você use o OpenTelemetry quando sua linguagem for compatível com essa biblioteca.
É possível configurar um servidor Zipkin para receber traces dos clientes Zipkin e depois encaminhar esses rastros para o Cloud Trace para análise. Para saber mais sobre essa abordagem, consulte Como usar o Cloud Trace com o Zipkin.
Você pode configurar aplicativos Spring Boot para encaminhar os dados de trace coletados para o Cloud Trace. Para saber mais sobre esse 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 no aplicativo quando você está 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 o Google Kubernetes Engine ou ativar a federação de identidade da carga de trabalho para o GKE, será necessário configurar o aplicativo para usar a federação de identidade da carga de trabalho para o GKE.
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
A menos que seu aplicativo sempre faça amostras de todos os períodos,
não é possível, em geral, forçar o rastreamento de uma solicitação de ponta a ponta
porque cada componente em uma solicitação de ponta a ponta faz seu próprio
decisão de amostragem. No entanto, é possível influenciar
decisão adicionando ao cabeçalho do trace uma sinalização sampled
,
com essa flag definida como true
. Esta configuração é uma dica para componentes filhos
para criar uma amostra da solicitação.
Para mais informações sobre cabeçalhos de trace, consulte
Protocolos para propagação de contexto.
Para componentes downstream cujo código você possui, é preciso determinar se
sua lógica de instrumentação respeita a flag sampled
.
Por exemplo, ao usar o OpenTelemetry
Para instrumentação, você pode usar o ParentBased
sampler
para garantir que a sinalização de amostra pai seja respeitada.
Os serviços do Google Cloud que registram informações de rastreamento no Cloud Trace normalmente aceitam a flag de amostragem pai como uma dica. No entanto, a maioria dos serviços também limita a amostragem. Cada serviço do Google Cloud determina se ele oferece suporte ao rastreamento, como a flag de amostragem pai é utilizada e o limite de taxa na amostragem.
Como correlacionar dados de métricas e traces
É possível correlacionar dados de métricas com valor de distribuição com rastros anexando exemplos aos pontos de dados de métricas. Se você concluir as etapas de configuração necessárias, o OpenTelemetry, que é a biblioteca de instrumentação recomendada, vai adicionar esses exemplares automaticamente. Para mais informações, consulte Correlacione métricas e traces usando exemplos.
Configurar o projeto e a plataforma
Verifique se a API Cloud Trace está ativada.
Por padrão, os projetos do Google Cloud têm a API Cloud Trace ativada, e você não precisa fazer nada. No entanto, as restrições de segurança definidas pela sua organização pode ter desativado a API. Para informações sobre solução de problemas, consulte Desenvolver aplicativos em um ambiente restrito do Google Cloud.
Enable the Cloud Trace API.
Configure sua plataforma.
Você pode usar o Cloud Trace no Google Cloud e em outras plataformas.
Google Cloud: quando o aplicativo está em execução no Google Cloud, não é necessário fornecer credenciais de autenticação na forma de uma conta de serviço para a biblioteca de cliente. No entanto, verifique se o escopo de acesso da API Cloud Trace está ativado no Google Cloud Platform.
Para as seguintes configurações, as definições de escopo de acesso padrão incluem o escopo de acesso da API Cloud Trace:
Se você usa escopos de acesso personalizados, O escopo de acesso da API Cloud Trace está ativado. Por exemplo, se você usa a Google Cloud CLI para criar um cluster do GKE e, se você especificar a sinalização
--scopes
, verifique se o escopo incluitrace.append
. O comando a seguir ilustra como definir a flag--scopes
:gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append
Como executar localmente e em outro lugar: se seu aplicativo estiver sendo executado fora do Google Cloud, será necessário fornecer credenciais de autenticação no a forma de uma conta de serviço para a biblioteca de cliente. A conta de serviço precisa receber o agente do Cloud Trace (
roles/cloudtrace.agent
). Para informações sobre papéis, consulte Controlar o acesso com o IAM.As bibliotecas de cliente do Google Cloud usam o Application Default Credentials (ADC) para encontrar as credenciais do aplicativo. É possível fornecer essas credenciais três maneiras:
Executar
gcloud auth application-default login
Coloque a conta de serviço em um caminho padrão para seu sistema operacional. Confira a seguir os caminhos padrão para Windows e Linux:
Windows:
%APPDATA%/gcloud/application_default_credentials.json
Linux:
$HOME/.config/gcloud/application_default_credentials.json
Defina a variável de ambiente
GOOGLE_APPLICATION_CREDENTIALS
como o caminho para sua conta de serviço:Linux/macOS
export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key
Windows
set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key
PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"
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: