Instrumentar para o Cloud Trace

É possível instrumentar seus aplicativos para que o Cloud Trace capture dados de rastreamento distribuídos, examine a latência de solicitações individuais e mostre a latência agregada em todos os seus serviços no console do Trace.

Este documento apresenta uma visão geral das abordagens de instrumentação e das opções de configuração. Para instruções detalhadas sobre linguagens de programação específicas, consulte as páginas de configuração de cada linguagem.

Quando instrumentar 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étrica e trace e podem enviá-los a qualquer fornecedor, incluindo o Google Cloud. Para seus aplicativos de agentes, alguns frameworks podem coletar seus comandos e respostas ou transmitir contexto que permite o rastreamento de algumas chamadas remotas de servidores MCP do Google Cloud.

Para instrumentar seu aplicativo, recomendamos o uso de um framework de instrumentação de código aberto e neutro em relação a fornecedores, como o OpenTelemetry, em vez de APIs ou bibliotecas de cliente específicas de fornecedores e produtos. Para mais informações sobre esses frameworks, consulte Observabilidade para desenvolvedores de aplicativos e Escolher uma abordagem de instrumentação.

Como instrumentar aplicativos

Há várias abordagens que podem ser usadas para instrumentar o aplicativo:

Amostras de instrumentação

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

Criar períodos personalizados

Embora o OpenTelemetry e as bibliotecas de cliente permitam criar períodos personalizados, talvez não seja necessário criá-los manualmente, porque essas bibliotecas criam automaticamente períodos nos limites de RPC.

Também é possível adicionar informações relevantes ao aplicativo adicionando anotações e tags personalizadas aos períodos atuais ou criar novos períodos filhos com as próprias anotações e tags para rastrear o comportamento do aplicativo com mais granularidade.

As bibliotecas geralmente mantêm um contexto de trace global que contém informações sobre o período atual, incluindo o ID de trace e o status de amostragem. Os aplicativos podem acessar o período atual pelo contexto de traces global. Como o contexto é global, verifique se os aplicativos com várias linhas de execução propagam o contexto entre as linhas de execução para manter dados de trace precisos.

Forçar amostragem de trace

Não é possível forçar a amostragem de períodos porque cada componente no caminho da solicitação toma uma decisão de amostragem independente. No entanto, é possível influenciar os componentes downstream definindo a flag sampled no cabeçalho do trace 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 trace, consulte Protocolos para propagação de contexto.

  • Seus aplicativos: você configura como a lógica de instrumentação respeita a flag sampled. Por exemplo, ao usar o OpenTelemetry, é possível usar o amostrador ParentBased para garantir que a flag de amostragem do pai seja respeitada.

  • Serviços doGoogle Cloud : cada serviço determina o próprio suporte de rastreamento. Em geral, os serviços aceitam a flag de amostragem pai como uma dica ao aplicar os próprios limites de taxa de amostragem.

Correlacionar métricas e traces com exemplares

É possível correlacionar dados de métricas com traces usando exemplos. Um exemplar é uma solicitação de amostra representativa ou um período associado a uma medição de métrica. Por exemplo, um exemplar pode conter um link para um trace, o que permite correlacionar os dados de métricas e de trace. Para um exemplo baseado no OpenTelemetry, consulte Correlacionar métricas e traces usando exemplos.

Talvez você veja exemplares gerados pelo sistema em gráficos de painel que mostram resultados de consultas SQL para dados de trace. Esses exemplares vinculam resultados de consulta específicos diretamente aos traces. Para mais informações, consulte Gerar e exibir exemplares de trace.

Configurar o projeto e a plataforma

Nesta seção, descrevemos as APIs e os papéis do Identity and Access Management (IAM) necessários e explicamos como configurar as credenciais de autenticação para sua plataforma.

Ativar APIs

Por padrão,os projetos do Google Cloud têm a API Cloud Trace e Telemetry ativadas, e você não precisa fazer nada. No entanto, as restrições de segurança definidas pela sua organização podem ter desativado uma ou as duas APIs. Para informações sobre solução de problemas, consulte Desenvolver aplicativos em um ambiente restrito de Google Cloud .

Ative as APIs Telemetry e Cloud Trace, se ainda não estiverem ativadas.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar as APIs

Conceder papéis do IAM

Os papéis do IAM necessários dependem de você estar visualizando dados de trace no console do Google Cloud ou gravando dados de trace no projeto:

  • Para receber as permissões necessárias para visualizar dados de trace usando o console do Google Cloud , peça ao administrador para conceder a você o papel do IAM de Usuário do Cloud Trace (roles/cloudtrace.user) no seu projeto.

  • Para receber as permissões necessárias para gravar dados de trace usando a API Cloud Trace, peça ao administrador para conceder a você o papel do IAM de Agente do Cloud Trace (roles/cloudtrace.agent) no projeto.

  • Para receber as permissões necessárias para gravar dados de trace usando a API Telemetry, peça ao administrador para conceder a você o papel do IAM de Gravador de telemetria do Cloud (roles/telemetry.writer) no projeto.

Autenticar

Nesta seção, descrevemos como autenticar quando os aplicativos são executados no Google Cloud e em outros lugares.

Executar em Google Cloud

Quando o aplicativo é executado no Google Cloud, geralmente não é necessário fornecer credenciais de autenticação. No entanto, algumas bibliotecas de cliente de linguagem exigem o ID do projeto, mesmo quando hospedadas no Google Cloud.

Verifique se a plataforma Google Cloud tem o escopo de acesso da API Cloud Trace ativado. Para as configurações a seguir, as configurações padrão de escopo de acesso 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 sinalização --scopes:

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

Execute localmente e em outro lugar

Se o aplicativo for executado fora do Google Cloud, será necessário fornecer credenciais de autenticação à 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. É possível fornecer essas credenciais de uma das três maneiras:

  • Executar gcloud auth application-default login

  • Coloque o arquivo de chave da conta de serviço em um caminho padrão para seu sistema operacional. Veja 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