Visão geral das amostras de instrumentação baseadas em coletores

Este documento descreve a estrutura dos exemplos de instrumentação fornecidos para as linguagens Go, Java, Node.js e Python. Esses exemplos oferecem orientações sobre como instrumentar um aplicativo para usar o SDK do OpenTelemetry e um coletor do OpenTelemetry.

A instrumentação nesses exemplos, que inclui o uso do SDK do OpenTelemetry e do exportador OTLP no processo do SDK, é neutra em relação ao fornecedor. O exportador no processo envia telemetria para o coletor do OpenTelemetry, que recebe esses dados e os envia para seu Google Cloud projeto. O coletor contém a vinculação a Google Cloud. Esses exemplos usam Google Cloud exportadores para enviar dados de registro e métricas ao seu projeto. No entanto, eles enviam dados de trace ao seu projeto usando a API Telemetry.

Talvez você se interesse por outros exemplos que ilustram configurações diferentes:

• Migrar do exportador de trace para o endpoint OTLP descreve como usar a instrumentação no processo para enviar dados de trace diretamente para seu Google Cloud projeto.

  Recomendamos que você use um coletor do OpenTelemetry para exportar seus dados de telemetria quando o ambiente oferecer suporte ao uso de um coletor. Se não for possível usar um coletor, use um exportador no processo que envie dados diretamente para seu Google Cloud projeto.

• Relacionar métricas e traces usando exemplos descreve como configurar um aplicativo Go para gerar exemplos. Um exemplo é um ponto de dados de exemplo anexado a um ponto de dados de métrica. É possível usar exemplos para correlacionar seus dados de trace e métrica.

• Usar o Agente de operações e o protocolo OpenTelemetry (OTLP) descreve como configurar o Agente de operações e um receptor OTLP para coletar métricas e traces de um aplicativo.

Observação: os exemplos mostram apenas partes selecionadas de um aplicativo em funcionamento. Por exemplo, os exemplos não mostram a lista de pacotes importados. No entanto, os aplicativos completos estão disponíveis no GitHub. Em um code snippet, é possível abrir o GitHub usando as opções Mais.

Como os exemplos funcionam

Os exemplos para Go, Java, Node.js e Python usam o protocolo OpenTelemetry para coletar dados de trace e métrica. Os exemplos configuram um framework de geração de registros para gravar registros estruturados e o coletor do OpenTelemetry é configurado para ler o fluxo stdout do aplicativo. Para recomendações de framework, consulte Escolher uma abordagem de instrumentação.

Os aplicativos são criados e implantados usando o Docker. Não é necessário usar o Docker ao instrumentar um aplicativo com o OpenTelemetry.

É possível executar os exemplos no Cloud Shell, em Google Cloud recursos ou em um ambiente de desenvolvimento local.

Modo detalhado

Os exemplos usam o OpenTelemetry Collector como um arquivo secundário para receber e enriquecer a telemetria do aplicativo, que um exportador envia para seu Google Cloud projeto. Os aplicativos de exemplo enviam dados de métrica e trace ao seu projeto usando a API Telemetry, que oferece suporte ao formato OTLP.

Os exemplos mostram como fazer o seguinte:

1. Configure o OpenTelemetry para coletar métricas e traces usando o OpenTelemetry collector.

   A complexidade dessa etapa depende da linguagem. Por exemplo, para Go, essa etapa configura a função main para chamar uma função que configura a coleta de métricas e traces. Para Go, o servidor e o cliente HTTP também são atualizados.

2. Configure um framework de geração de registros para gravar registros estruturados.

   Recomendamos que seus aplicativos gravem registros estruturados, que formatam o payload de registro como um objeto JSON. Para esses registros, é possível criar consultas que pesquisam caminhos JSON específicos e indexar campos específicos no payload de registro.

   Alguns serviços, como o Google Kubernetes Engine, têm agentes integrados que extraem registros estruturados e os enviam para seu Google Cloud projeto. Outros serviços, como o Compute Engine, exigem a instalação de um agente, que extrai e envia seus registros. Para saber mais sobre os agentes instalados, consulte Visão geral do Agente de operações.

   Não é necessário instalar nenhum agente para usar esses exemplos.

3. Configure arquivos do Docker. Todos os exemplos contêm os seguintes arquivos YAML:

   • docker-compose.yaml: configura os serviços para o aplicativo, o coletor do OpenTelemetry e um gerador de carga. Por exemplo, o serviço do coletor do OpenTelemetry, otelcol, especifica uma imagem, um volume e variáveis de ambiente. O endpoint do coletor do OpenTelemetry é definido pela variável de ambiente OTEL_EXPORTER_OTLP_ENDPOINT, que é especificada no serviço app.

   • otel-collector-config.yaml: configura o OpenTelemetry:

     • Os exemplos usam o receptor otlp para dados de métrica e trace e o receptor filelog para dados de registro.

     • Os exemplos usam o otlphttp exportador para dados de métrica e trace, e o Google Cloud exportador para dados de registro.

       O exportador otlphttp envia dados ao seu projeto usando a API Telemetry, que oferece suporte ao OTLP. O Google Cloud exportador converte os dados de registro em um formato compatível com a API Cloud Logging e envia os dados transformados ao seu Google Cloud projeto emitindo um comando de API.

   • docker-compose.creds.yaml: esse arquivo monta opcionalmente um Google Cloud arquivo de credenciais no contêiner otelcol. Você precisa desse arquivo ao executar um exemplo em uma máquina local em que as credenciais padrão do aplicativo (ADC) estão disponíveis apenas como um arquivo.

Permissões necessárias

• Para receber as permissões necessárias para que os aplicativos de exemplo gravem dados de registro, métrica e trace, peça ao administrador para conceder a você os seguintes papéis do IAM:

  • Gravador de registros (roles/logging.logWriter) no seu projeto
  • Gravador de métricas do Monitoring (roles/monitoring.metricWriter) no seu projeto
  • Gravador de traces de telemetria do Cloud (roles/telemetry.tracesWriter) no seu projeto
  • Consumidor de uso do serviço (roles/serviceusage.serviceUsageConsumer) no seu projeto de cota

  Essas permissões são suficientes se você executar o exemplo no Cloud Shell, em Google Cloud recursos ou em um ambiente de desenvolvimento local. Para saber como configurar um projeto de cota, consulte Definir o projeto de cota.

  Observação: os aplicativos Production normalmente dependem de uma conta de serviço para fornecer as credenciais necessárias para gravar dados de registro, métrica e trace. Nesses cenários, conceda os papéis anteriores à conta de serviço.

• Para receber as permissões necessárias para visualizar seus dados de registro, métrica e trace, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

  • Visualizador de registros (roles/logging.viewer)
  • Leitor do Monitoring (roles/monitoring.viewer)
  • Usuário do Cloud Trace (roles/cloudtrace.user)

  Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

  Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

APIs necessárias

Ative as APIs Cloud Logging, Cloud Monitoring, Cloud Trace e Telemetry:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço role (roles/serviceusage.serviceUsageAdmin), que contém a serviceusage.services.enable permissão. Saiba como conceder papéis.

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

A seguir

Para saber mais sobre coletores, consulte Coletor do OpenTelemetry criado pelo Google.

Confira os exemplos que usam exportações baseadas em coletores.

• Exemplo de Go.
• Exemplo de Java.
• Exemplo de Node.js.
• Exemplo de Python.