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

Para manter o código do aplicativo independente de fornecedores ao coletar e enviar telemetria para Google Cloud, use as amostras de instrumentação baseadas em coletores do OpenTelemetry para Go, Java, Node.js e Python.

Esses exemplos mostram como configurar um SDK do OpenTelemetry no processo para exportar métricas, registros e rastreamentos para um coletor local do OpenTelemetry que roteia sua telemetria para Google Cloud. Os exemplos enviam dados de métricas e rastreamento no formato do protocolo OpenTelemetry (OTLP) para seu projeto Google Cloud usando a API Telemetry e enviam dados de registro usando um exportador Google Cloud .

Como as amostras funcionam

As amostras para Go, Java, Node.js e Python usam o protocolo OpenTelemetry para coletar dados de rastreamento e métricas. Os exemplos configuram um framework de geração de registros para gravar registros estruturados e o coletor do OpenTelemetry para ler do 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 as amostras no Cloud Shell, em recursos do Google Cloud ou em um ambiente de desenvolvimento local.

Modo detalhado

Os exemplos usam o OpenTelemetry Collector como um sidecar para receber e enriquecer a telemetria do aplicativo, que um exportador envia para seu projeto Google Cloud . Os aplicativos de exemplo enviam dados de métricas e traces para seu projeto usando a API Telemetry, que é compatível com o formato OTLP.

Os exemplos mostram como fazer o seguinte:

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

   A complexidade dessa etapa depende do idioma. Por exemplo, em Go, você atualiza a função main para inicializar a coleta de telemetria e configurar o servidor e o cliente HTTP.

2. Configure uma estrutura 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 do registro.

   Alguns serviços, como o Google Kubernetes Engine, têm agentes integrados que extraem registros estruturados e os enviam para seu projeto Google Cloud . 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 que você instala, consulte Visão geral do Agente de operações.

   Não é necessário instalar nenhum agente para usar essas amostras.

3. Configure os arquivos do Docker. Todas as amostras 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, especificada no serviço app.

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

     • As amostras usam o receptor otlp para dados de métricas e rastreamento e o receptor filelog para dados de registros.

     • Os exemplos usam o exportador otlphttp para dados de métricas e rastreamento e o exportador Google Cloud para dados de registros.

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

   • docker-compose.creds.yaml: esse arquivo monta opcionalmente um arquivo de credenciais Google Cloudno contêiner otelcol. Você precisa desse arquivo quando executa uma amostra em uma máquina local em que as Application Default Credentials (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 registros, métricas e rastreamentos, 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 do Service Usage (roles/serviceusage.serviceUsageConsumer) no projeto de cota

  Essas permissões são suficientes se você executar a amostra no Cloud Shell, em recursos do Google Cloud 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 geralmente dependem de uma conta de serviço para fornecer as credenciais necessárias para gravar dados de registro, métricas e rastreamento. Nesses cenários, conceda os papéis anteriores à conta de serviço.

• Para ter as permissões necessárias para visualizar seus dados de registros, métricas e rastreamentos, 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 usando papéis personalizados ou outros papéis predefinidos.

APIs necessárias

Ative as APIs Cloud Logging, Cloud Monitoring, Cloud Trace e Telemetry, se alguma delas ainda não estiver ativada:

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão pelo papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

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

Abordagens alternativas de instrumentação

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

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

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

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

• 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 rastreamentos de um aplicativo.

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 em Go
• Exemplo em Java
• Exemplo de Node.js
• Exemplo em Python