Instrumentar para o Cloud Trace

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

Neste documento, apresentamos 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

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 traces e podem enviar esses dados a qualquer fornecedor, incluindo o Google Cloud. Para seus aplicativos generativos, 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 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 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 você pode usar para instrumentar seu aplicativo:

Amostras de instrumentação

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

Criar intervalos personalizados

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

Você também pode adicionar informações relevantes ao seu aplicativo adicionando anotações e tags personalizadas aos intervalos atuais ou criar novos intervalos filhos com anotações e tags próprias para rastrear o comportamento do aplicativo com granularidade mais refinada.

Normalmente, as bibliotecas mantêm um contexto de traces 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 intervalo atual pelo contexto de rastreamento global. Como o contexto é global, verifique se os aplicativos multithread propagaram o contexto entre as linhas de execução para manter dados de rastreamento precisos.

Forçar a amostragem de trace

Não é possível forçar a amostragem de intervalos 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 de rastreamento como true. Essa configuração é uma dica para que os componentes filhos façam amostragem da 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 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 principal como uma dica ao aplicar os próprios limites de taxa de amostragem.

Correlacionar métricas e traces com exemplos

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

É possível que você veja exemplares gerados pelo sistema em gráficos do 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 exemplares de rastreamento.

Configurar o projeto e a plataforma

Esta seção descreve as APIs e os papéis do Identity and Access Management (IAM) necessários e explica 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 a API Telemetry ativadas, e não é necessário 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 restrito de Google Cloud .

Ative as APIs Telemetry e Cloud Trace, se alguma delas ainda não estiver ativada.

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 receber 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 rastreamento no console do Google Cloud ou gravando dados de rastreamento no seu projeto:

  • Para receber as permissões necessárias para visualizar dados de rastreamento usando o console do Google Cloud , peça ao administrador para conceder a você o papel 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 Agente do Cloud Trace (roles/cloudtrace.agent) do IAM no 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ê o papel do IAM de Gravador de telemetria do Cloud (roles/telemetry.writer) no seu projeto.

Autenticar

Esta seção descreve como fazer a autenticação quando os aplicativos são executados no Google Cloud e em outros lugares.

Executar em Google Cloud

Quando seu 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 hospedado em 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ê usa 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

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 mais informações sobre papéis, consulte Controlar o acesso com o IAM.

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