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

É possível 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 a qualquer fornecedor, incluindo 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 ao fornecedor, consulte Instrumentação e observabilidade.

Como instrumentar aplicativos

Para instrumentar seus aplicativos e coletar dados de trace, faça uma das seguintes ações:

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 nem especificar o ID do projeto Google Cloud no aplicativo quando ele está em execução no Google Cloud. Para algumas linguagens, você precisa especificar o ID do projeto 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 federação de identidade da carga de trabalho para o GKE, será necessário configurar o aplicativo para usar a federação de identidade da carga de trabalho para o GKE.

Se você estiver executando fora de Google Cloud, precisará fornecer credenciais de autenticação ao aplicativo. Você também precisa especificar o ID do projetoGoogle 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 cada intervalo, não é possível, em geral, forçar que uma solicitação seja rastreada de ponta a ponta, porque cada componente em uma solicitação de ponta a ponta toma sua própria decisão de amostragem. No entanto, é possível influenciar a decisão adicionando ao cabeçalho do rastreamento uma flag sampled, com essa flag definida como true. Essa configuração é uma dica para componentes filhos para amostrar a 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 o OpenTelemetry para instrumentação, é possível usar o ParentBased sampler para garantir que a flag de amostragem pai seja respeitada.

Os serviçosGoogle Cloud que registram informações de rastreamento no Cloud Trace normalmente aceitam a flag de amostragem pai como uma dica. No entanto, a maioria deles também limita a taxa de amostragem. Cada Google Cloud service determina se ele oferece suporte ao rastreamento, como a flag de amostragem pai é utilizada e o limite de taxa na amostragem.

Como correlacionar dados de métricas e de rastreamento

É possível correlacionar dados de métricas com valor de distribuição com rastros anexando exemplos aos pontos de dados de métricas. Se você concluir as etapas de configuração necessárias, o OpenTelemetry, que é a biblioteca de instrumentação recomendada, vai adicionar esses exemplares automaticamente. Para mais informações, consulte Relacionar 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 sua organização podem ter desativado a API. Para informações sobre solução de problemas, consulte Desenvolver aplicativos em um ambiente Google Cloud restrito.

    Enable the Cloud Trace API.

    Enable the API

  2. Configure sua plataforma.

    Você pode usar o Cloud Trace no Google Cloud e em outras plataformas.

    • Google Cloud: quando o 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, verifique se o escopo de acesso da API Cloud Trace está ativado na Google Cloud plataforma.

      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 como definir a 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 em execução fora do Google Cloud, forneça as 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.

      AsGoogle Cloud bibliotecas de cliente 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 o sistema operacional. Confira 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 para o caminho da sua conta de serviço:

          export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key
          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.