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

Instrumente seu aplicativo para coletar informações específicas que ajudam 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 rastreamento e podem enviar esses dados para qualquer fornecedor, incluindo o Google Cloud. Para seus aplicativos agênticos, alguns frameworks podem coletar seus comandos e respostas ou transmitir contexto que permite o rastreamento de algumas chamadas remotas dos servidores MCP do Google Cloud.

Para instrumentar seu aplicativo, recomendamos que você use uma estrutura de instrumentação de código aberto e neutra em relação a fornecedores, como OpenTelemetry, em vez de APIs ou bibliotecas de cliente específicas do fornecedor e do produto. Para mais 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:

As amostras de instrumentação que fornecemos usam o OpenTelemetry:

  • Para saber quais servidores MCP remotos do Google Cloud oferecem suporte à geração de trace, e 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 nem especificar o ID do projeto Google Cloud no aplicativo quando ele está em execução 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 no 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 ID do projetoGoogle 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 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 sua própria decisão de amostragem. No entanto, é possível influenciar a decisão adicionando ao cabeçalho de rastreamento uma flag sampled, com essa flag definida como true. Essa configuração é uma dica para que os componentes filhos façam uma amostragem da solicitação. Para mais informações sobre cabeçalhos de rastreamento, consulte Protocolos para propagação de contexto.

Para componentes downstream cujo código é de sua propriedade, determine se a lógica de instrumentação respeita a flag sampled. Por exemplo, ao usar o OpenTelemetry para instrumentação, use o amostrador ParentBased para garantir que a flag de amostragem principal seja respeitada.

Google Cloud Os serviços que registram informações de rastreamento no Cloud Trace normalmente aceitam a flag de amostragem principal como uma dica. No entanto, a maioria dos serviços também limita a taxa de amostragem. Cada Google Cloud serviço determina se ele oferece suporte ao rastreamento, como a flag de amostragem principal é usada e o limite de taxa na amostragem.

Como correlacionar dados de métricas e traces

É possível correlacionar dados de métricas com valores de distribuição e rastreamentos anexando exemplares 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 automaticamente esses exemplares. Para mais informações, consulte Correlacionar métricas e traces usando exemplos.

Configurar o projeto e a plataforma

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

    Ative a API Cloud Trace.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

    Ativar a API

  2. Configure sua plataforma.

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

    • Google Cloud: quando seu 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 na sua plataforma Google Cloud .

      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ê usar escopos de acesso personalizados, verifique se o escopo de acesso da API Cloud Trace está ativado. Por exemplo, se você usar a Google Cloud CLI para criar um cluster do GKE e especificar a flag --scopes, verifique se o escopo inclui trace.append. O comando a seguir ilustra a definição da flag --scopes:

      gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

    • Execução local e em outros lugares: se o aplicativo estiver sendo executado fora doGoogle Cloud, forneça credenciais de autenticação na forma de uma conta de serviço para a biblioteca de cliente. A conta de serviço precisa receber o papel de agente do Cloud Trace (roles/cloudtrace.agent). Para informações sobre papéis, consulte Controlar o acesso com o IAM.

      As bibliotecas de cliente doGoogle Cloud usam o Application Default Credentials (ADC) para encontrar as credenciais do aplicativo. Você pode fornecer essas credenciais de 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 abaixo 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 para o caminho da 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.