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 instrumentar seu aplicativo

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 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 informações sobre como instrumentar seus aplicativos usando estruturas de instrumentação neutras em relação a fornecedores, consulte Instrumentação e observabilidade.

Como instrumentar aplicativos

Para instrumentar seus aplicativos e coletar dados de rastreamento, faça uma destas 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

Em geral, 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 do Google Cloud , mesmo que esteja em execução no Google Cloud. Além disso, se você usar o modo Autopilot no 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 do 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 amostragem de todos os intervalos, 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 sua própria decisão de amostragem. No entanto, é possível influenciar a decisão adicionando ao cabeçalho de rastreamento uma flag sampled, com essa flag definida 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.

Para componentes downstream cujo código é de sua propriedade, determine se a lógica de instrumentação respeita a flag sampled. Por exemplo, ao usar o OpenTelemetry para instrumentação, é possível usar o amostrador ParentBased para garantir que a flag de amostragem principal seja respeitada.

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

Como correlacionar dados de métricas e traces

É possível correlacionar dados de métricas com valores de distribuição e rastreamentos anexando exemplares 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 automaticamente esses exemplares. Para mais informações, consulte Correlacionar métricas e traces usando exemplos.

Configurar seu projeto e 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 restrito de Google Cloud .

    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 seu 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 sua plataforma Google Cloud .

      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

    • Execução local e em outros lugares: se o aplicativo estiver sendo executado fora doGoogle Cloud, forneça 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 doGoogle Cloud usam o Application Default Credentials (ADC) para encontrar as credenciais do aplicativo. Você pode 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. 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

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.