Instrumento 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 não são capturados automaticamente, é necessário instrumentar seu aplicativo para coletar esses dados.

Você pode instrumentar seu aplicativo para que ele colete informações específicas do aplicativo. Vários frameworks de instrumentação de código aberto permitem coletar métricas, registros e traces do aplicativo e enviar esses dados para qualquer fornecedor, incluindo o 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 mais informações sobre como instrumentar seus aplicativos usando frameworks de instrumentação neutros em relação a fornecedores, consulte Instrumentação e observabilidade.

Como instrumentar aplicativos

Para instrumentar seus aplicativos para coletar dados de traces, é possível fazer o seguinte:

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

Geralmente, não é necessário fornecer credenciais de autenticação ao aplicativo ou especificar o ID do projeto do Google Cloud nele quando estiver executando 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 para o Google Kubernetes Engine ou ativar a Identidade da carga de trabalho, será necessário configurar seu aplicativo para usar a Identidade da carga de trabalho.

Se você estiver executando fora do Google Cloud, precisará fornecer credenciais de autenticação ao aplicativo. Você também precisa especificar o ID do projeto do Google 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 a amostragem de todos os períodos, 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 ao cabeçalho do trace uma sinalização sampled, com essa sinalização definida como true. Essa configuração é uma dica para que os componentes filhos tenham uma amostra da solicitação. Para mais informações sobre cabeçalhos de rastreamento, consulte Protocolos para propagação de contexto.

Para componentes downstream que têm o código próprio, é necessário determinar se a lógica de instrumentação respeita a sinalização sampled. Por exemplo, ao usar o OpenTelemetry para instrumentação, use o sampler ParentBased para garantir que a flag mãe seja respeitada.

Os serviços do Google Cloud que registram informações de rastreamento no Cloud Trace geralmente aceitam a sinalização de amostragem pai como uma dica. No entanto, a maioria dos serviços também aceita amostragem de limitação de taxa. Cada serviço do Google Cloud determina se oferece suporte ao rastreamento, como a sinalização de amostragem pai é utilizada e a limitação de taxa na amostragem.

Como correlacionar dados de métricas e traces

É possível correlacionar dados de métricas com valor de distribuição a rastreamentos 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, 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 organização podem ter desativado a API. Para informações sobre solução de problemas, consulte Desenvolver aplicativos em um ambiente restrito do Google Cloud.

    Ative a API Cloud Trace.

    Ative 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á sendo executado 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, você precisa verificar se o Google Cloud Platform tem o escopo de acesso da API Cloud Trace ativado.

      Para as configurações a seguir, as configuraçõ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 sinalização --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

    • Execução local e em outro lugar: se o aplicativo estiver sendo executado fora do Google Cloud, será necessário fornecer 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 do Google Cloud usam o Application Default Credentials (ADC) para encontrar as credenciais do aplicativo. É possível 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. Esta é a lista dos 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.