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 e solucionar falhas. Vários frameworks de instrumentação de código aberto coletam dados de registro, métrica e trace e podem enviar esses dados a qualquer fornecedor, incluindo Google Cloud. Para 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 gravando 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:

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 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 modo 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. Também é necessário 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 para fazer 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 principal seja respeitada.

Google Cloud 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 oferece suporte ao rastreamento, como a flag de amostragem principal é 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 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 o projeto e a 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 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, é necessário garantir que sua Google Cloud plataforma tenha o escopo de acesso da API Cloud Trace ativado.

      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 configuraçã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 do Google Cloud, forneça as credenciais de autenticação em 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.

      AsGoogle Cloud bibliotecas de cliente usam Application Default Credentials (ADC) para encontrar as credenciais do aplicativo. É possível fornecer essas credenciais de três maneiras:

      • Corrida gcloud auth application-default login

      • Coloque a conta de serviço em um caminho padrão para seu sistema operacional. A seguir, listamos 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.