Instrumentar para o Cloud Trace

É possível instrumentar seus aplicativos para o Cloud Trace a fim de capturar dados de rastreamento distribuído, examinar a latência de solicitações individuais e visualizar a latência agregada em todos os serviços no console do Trace.

Este documento oferece 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 específicas da linguagem.

Quando instrumentar seu aplicativo

Quando os dados de rastreamento 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étricas e rastreamento e podem enviar esses dados a qualquer fornecedor, incluindo Google Cloud. Para seus aplicativos de agente, alguns frameworks podem coletar 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 de código aberto, como o OpenTelemetry, em vez de APIs ou bibliotecas de cliente específicas do fornecedor e do produto. 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 podem ser usadas para instrumentar seu aplicativo:

  • Recomendado: use o OpenTelemetry, configure seu aplicativo com um exportador OTLP que envia dados de rastreamento para um coletor e configure o coletor para enviar dados de rastreamento 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 o OpenTelemetry e configure seu aplicativo com um exportador OTLP que envia os dados de rastreamento para seu Google Cloud projeto usando a API Telemetry.

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

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

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

Exemplos de instrumentação

Os exemplos de instrumentação que fornecemos usam 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 períodos automaticamente nos limites de RPC.

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

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

Forçar a amostragem de rastreamento

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 sampled flag no cabeçalho de rastreamento como true. Essa configuração é uma dica para os componentes filhos para amostrar a solicitação. Para mais informações sobre cabeçalhos de rastreamento, 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 OpenTelemetry, é possível usar o sampler ParentBased para garantir que a flag de amostragem do pai seja respeitada.

  • Google Cloud serviços: 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 rastreamentos com exemplos

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

Você pode encontrar exemplos gerados pelo sistema em gráficos de painel que mostram resultados de consultas SQL para dados de rastreamento. Esses exemplos vinculam resultados de consultas específicas diretamente a rastreamentos. Para mais informações, consulte Gerar e mostrar exemplos de rastreamento.

Configurar seu projeto e plataforma

Esta seção descreve as APIs e os papéis do Identity and Access Management (IAM, na sigla em inglês) necessários e explica como configurar as credenciais de autenticação para sua plataforma.

Ativar APIs

Por padrão, Google Cloud os projetos têm a API Cloud Trace e a API 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 ambas as APIs. Para informações sobre solução de problemas, consulte Desenvolver aplicativos em um ambiente Google Cloud restrito.

Ative as APIs Telemetry e Cloud Trace.

Funções necessárias para ativar APIs

Para ativar as 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 receber essa permissão pelo papel de administrador de uso do serviço (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 rastreamento no Google Cloud console ou gravando dados de rastreamento no seu projeto:

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

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

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

Autenticar

Esta seção descreve como autenticar quando seus aplicativos são executados em Google Cloud e quando são executados em outro lugar.

Executar em Google Cloud

Quando seu aplicativo é executado em 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 hospedado em Google Cloud.

Verifique se sua Google Cloud plataforma tem 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 definição da flag --scopes:

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

Executar localmente e em outro lugar

Se o aplicativo for executado fora Google Cloud, forneça credenciais de autenticaçã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 uma destas três maneiras:

  • Execute gcloud auth application-default login

  • Coloque o arquivo de chave da 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 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