Instrumente o Cloud Trace

Este documento oferece uma breve vista geral sobre como instrumentar a sua aplicação para o Cloud Trace. Para ver instruções detalhadas sobre como configurar o Cloud Trace, consulte as páginas de configuração específicas do idioma.

O Cloud Trace fornece dados de rastreio distribuídos para as suas aplicações. Depois de instrumentar a sua aplicação, pode inspecionar os dados de latência de um único pedido e ver a latência agregada de uma aplicação inteira na consola do Cloud Trace.

Quando instrumentar a sua aplicação

Quando os dados de rastreio não são capturados automaticamente, tem de instrumentar a sua aplicação para recolher estes dados.

Pode instrumentar a sua aplicação para que recolha informações específicas da aplicação. Vários frameworks de instrumentação de código aberto permitem-lhe recolher métricas, registos e rastreios da sua aplicação e enviar esses dados para qualquer fornecedor, incluindo Google Cloud. Para instrumentar a sua aplicação, recomendamos que use uma estrutura de instrumentação neutra em relação ao fornecedor e de código aberto, como o OpenTelemetry, em vez de APIs ou bibliotecas de cliente específicas do fornecedor e do produto.

Para obter informações sobre a instrumentação das suas aplicações através de frameworks de instrumentação independentes do fornecedor, consulte o artigo Instrumentação e observabilidade.

Como instrumentar aplicações

Para instrumentar as suas aplicações de modo a recolher dados de rastreio, pode fazer qualquer uma das seguintes ações:

Quando deve criar intervalos

Normalmente, as bibliotecas de cliente do Cloud Trace mantêm um contexto de rastreio global que contém informações sobre o intervalo atual, incluindo o respetivo ID de rastreio e se o rastreio é amostrado. Normalmente, estas bibliotecas criam intervalos nos limites de RPC. No entanto, pode ter de criar intervalos se o algoritmo de criação predefinido não for suficiente para as suas necessidades.

O intervalo ativo atual pode ser acedido pelo contexto de rastreio global, que, por vezes, está envolvido num objeto Tracer. Pode adicionar informações relevantes para a sua aplicação através de anotações e etiquetas personalizadas a intervalos existentes ou pode criar novos intervalos subordinados com as suas próprias anotações e etiquetas para monitorizar o comportamento da aplicação com maior detalhe. Uma vez que o contexto é global, as aplicações com vários threads que atualizam o contexto têm de usar o isolamento adequado.

Quando fornecer credenciais de autenticação

Geralmente, não precisa de fornecer credenciais de autenticação à sua aplicação nem especificar o ID do projeto na sua aplicação quando está a ser executada no Google Cloud. Google Cloud Para alguns idiomas, tem de especificar o ID do projeto, mesmo que esteja a usar o Google Cloud. Google Cloud Além disso, se usar o modo Autopilot para o Google Kubernetes Engine ou se ativar a Workload Identity Federation para o GKE, tem de configurar a sua aplicação para usar a Workload Identity Federation para o GKE.

Se estiver a executar fora do Google Cloud, tem de fornecer credenciais de autenticação à sua aplicação. Também tem de especificar o Google Cloud ID do projeto na sua aplicação.

Para ver detalhes, aceda às páginas de configuração específicas do idioma.

Como forçar o rastreio de um pedido

A menos que a sua aplicação faça sempre a amostragem de cada intervalo, não é possível, em geral, forçar o rastreio integral de um pedido, porque cada componente num pedido integral toma a sua própria decisão de amostragem. No entanto, pode influenciar a decisão adicionando ao cabeçalho de rastreio uma flag sampled, com esta flag definida como true. Esta definição é uma sugestão para os componentes secundários para amostrar o pedido. Para mais informações sobre os cabeçalhos de rastreio, consulte o artigo Protocolos para propagação de contexto.

Para os componentes a jusante cujo código é seu, tem de determinar se a lógica de instrumentação respeita a flag sampled. Por exemplo, quando usar o OpenTelemetry para instrumentação, pode usar o ParentBased amostragem para garantir que o indicador de amostragem principal é respeitado.

Google Cloud Os serviços que registam informações de rastreio no Cloud Trace aceitam normalmente o indicador de amostragem principal como uma sugestão. No entanto, a maioria dos serviços também limita a taxa de amostragem. Cada Google Cloud serviço determina se suporta o rastreio, como é usado o indicador de amostragem principal e o limite de taxa na amostragem.

Como correlacionar dados de métricas e rastreios

Pode correlacionar dados de métricas com valores de distribuição com rastreios anexando exemplos aos pontos de dados das métricas. Desde que conclua os passos de configuração necessários, a OpenTelemetry, que é a biblioteca de instrumentação recomendada, adiciona automaticamente estes exemplos. Para mais informações, consulte o artigo Correlacione métricas e rastreios através de exemplos.

Configure o seu projeto e plataforma

  1. Certifique-se de que a API Cloud Trace está ativada.

    Por predefinição, Google Cloud os projetos têm a API Cloud Trace ativada e não tem de fazer nada. No entanto, as restrições de segurança definidas pela sua organização podem ter desativado a API. Para obter informações de resolução de problemas, consulte o artigo Desenvolva aplicações num ambiente Google Cloud restrito.

    Enable the Cloud Trace API.

    Enable the API

  2. Configure a sua plataforma.

    Pode usar o Cloud Trace no Google Cloud e noutras plataformas.

    • Google Cloud: quando a sua aplicação é executada no Google Cloud, não precisa de fornecer credenciais de autenticação sob a forma de uma conta de serviço à biblioteca cliente. No entanto, tem de garantir que a sua plataforma tem o âmbito de acesso da API Cloud Trace ativado. Google Cloud

      Para as seguintes configurações, as definições de âmbito de acesso predefinidas incluem o âmbito de acesso da Cloud Trace API:

      Se usar âmbitos de acesso personalizados, tem de garantir que o âmbito de acesso da API Cloud Trace está ativado. Por exemplo, se usar a Google Cloud CLI para criar um cluster do GKE e especificar a flag --scopes, certifique-se de que o âmbito inclui trace.append. O seguinte comando ilustra a definição do sinalizador --scopes:

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

    • Execução local e noutro local: se a sua aplicação estiver a ser executada fora do Google Cloud, tem de fornecer credenciais de autenticação sob a forma de uma conta de serviço à biblioteca de cliente. Tem de conceder à conta de serviço a função Agente do Cloud Trace (roles/cloudtrace.agent). Para informações sobre funções, consulte o artigo Controle o acesso com a IAM.

      Google Cloud As bibliotecas cliente usam Credenciais padrão da aplicação (ADC) para encontrar as credenciais da sua aplicação. Pode fornecer estas credenciais de uma das três formas:

      • Execução gcloud auth application-default login

      • Coloque a conta de serviço num caminho predefinido para o seu sistema operativo. A lista seguinte apresenta os caminhos predefinidos para o Windows e o 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"

O que se segue?

Para obter informações de configuração detalhadas, exemplos e links para o GitHub e outros repositórios de código aberto, aceda à página de configuração do seu idioma.