Instrumentar 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 trace para validar o desempenho ou solucionar problemas não são capturados automaticamente, instrumente seu aplicativo.

Instrumente seu aplicativo para coletar informações específicas que ajudem você a entender o desempenho dele e solucionar falhas. Vários frameworks de instrumentação de código aberto coletam dados de registro, métricas e trace dados e podem enviar esses dados a qualquer fornecedor, incluindo Google Cloud. Para seus aplicativos de agente, alguns frameworks podem coletar seus comandos e respostas ou transmitir o contexto que permite o rastreamento de algumas chamadas de servidores MCP remotos do 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 esses frameworks, consulte Instrumentação e observabilidade e Escolher uma abordagem de instrumentação.

Como instrumentar aplicativos

Há várias abordagens que você pode usar para instrumentar seu aplicativo:

  • Recomendado: use o OpenTelemetry, configure seu aplicativo com um exportador OTLP que envia dados de trace para um coletor e configure o coletor para enviar dados de trace para seu Google Cloud projeto usando a API Telemetry (OTLP). Para saber mais sobre nossas recomendações, consulte Escolher uma abordagem de instrumentação.

  • Use OpenTelemetry e configure seu aplicativo com um exportador OTLP que envia os dados de trace para seu Google Cloud projeto usando a API Telemetry.

  • Se você estiver escrevendo aplicativos que são executados no Compute Engine, poderá usar o Agente de operações e o receptor OpenTelemetry Protocol (OTLP) para coletar traces e métricas do 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.

  • Invoque diretamente a API Telemetry ou a API Cloud Trace.

  • Use as bibliotecas de cliente do Cloud Trace ou o exportador do Cloud Trace para OpenTelemetry.

  • Para aplicativos Spring Boot, configure-os para encaminhar os dados de trace coletados para o Cloud Trace. Para informações sobre esse procedimento, consulte Spring Cloud para Google Cloud: Cloud Trace.

Os exemplos de instrumentação que fornecemos usam OpenTelemetry:

  • Para saber quais servidores MCP remotos do Google Cloud oferecem suporte à geração de trace e como saber como configurar seu aplicativo para instruir esses servidores a criar períodos, consulte Investigar chamadas de MCP usando o 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

Em geral, não é necessário fornecer credenciais de autenticação ao aplicativo ou especificar o ID do seu Google Cloud projeto no seu aplicativo quando estiver em execução no Google Cloud. Para algumas linguagens, você precisa especificar o ID do seu Google Cloud projeto, mesmo que esteja em execução no Google Cloud. Além disso, se você usar o Autopilot para o Google Kubernetes Engine ou ativar a Federação de Identidade da Carga de Trabalho para GKE, será necessário configurar o aplicativo para usar a Federação de Identidade da Carga de Trabalho para GKE.

Se você estiver executando fora do Google Cloud, precisará fornecer credenciais de autenticação ao aplicativo. Você também precisa especificar o Google Cloud ID do projeto 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 a amostragem de cada período, 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 toma a própria decisão de amostragem. No entanto, é possível influenciar a decisão adicionando uma sampled flag ao cabeçalho de trace, com essa flag definida como true. Essa configuração é uma dica para os componentes filhos fazerem a amostragem 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, é necessário determinar se a lógica de instrumentação respeita a flag sampled. Por exemplo, ao usar OpenTelemetry para instrumentação, é possível usar o ParentBased sampler para garantir que a flag de amostragem pai seja respeitada.

Google Cloud serviços 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 taxa de amostragem. Cada Google Cloud serviço determina se oferece suporte ao rastreamento, como a flag de amostragem pai é usada 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 traces anexando exemplos aos pontos de dados de métricas. Desde que você conclua as etapas de configuração necessárias, o OpenTelemetry, que é a biblioteca de instrumentação recomendada, adiciona esses exemplos automaticamente. Para mais informações, consulte Correlacionar métricas e traces usando exemplos.

Configurar seu projeto e plataforma

  1. Verifique se a API Cloud Trace está ativada.

    Por padrão, Google Cloud os projetos 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 podem ter desativado a API. Para informações sobre solução de problemas, consulte Desenvolver aplicativos em um ambiente restrito Google Cloud .

    Ative a API Cloud Trace.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter a permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pela função Proprietário (roles/owner). Caso contrário, você pode receber essa permissão pela função Administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder funções.

    Ativar a API

  2. Configure sua plataforma.

    Você pode usar o Cloud Trace no Google Cloud e em outras plataformas.

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.