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

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

Esses exemplos demonstram como configurar um SDK do OpenTelemetry em processo para exportar métricas, registros e traces para um coletor local do OpenTelemetry que encaminha sua telemetria para o Google Cloud. As amostras enviam dados de registro, métrica e trace no formato do protocolo OpenTelemetry (OTLP) para o projeto do Google Cloud usando a API Telemetry.

Como as amostras funcionam

As amostras para Go, Java, Node.js e Python usam o protocolo OpenTelemetry para coletar dados de trace e métrica. As amostras configuram um framework de geração de registros para gravar registros estruturados e configuram o coletor do OpenTelemetry para ler o stream 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 coletor do OpenTelemetry como um arquivo secundário para receber e enriquecer a telemetria do aplicativo, que um exportador envia para o projeto do Google Cloud . As amostras enviam dados de registro, métrica e trace para seu projeto usando a API Telemetry, que é compatível com o formato OTLP.

Os exemplos mostram como:

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 um framework de geração de registros para gravar registros estruturados.

   Recomendamos que seus aplicativos gravem registros estruturados, que formatam o payload do 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 coletam registros estruturados e os enviam para o projeto do Google Cloud . Outros serviços, como o Compute Engine, exigem que você instale um agente, que coleta e envia os 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. Configurar 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 para o 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 coletor do OpenTelemetry:

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

     • As amostras usam o exportador otlphttp para dados de registro, métrica e trace.

       O exportador otlphttp envia dados para seu projeto usando a API Telemetry, que é compatível com OTLP.

   • docker-compose.creds.yaml: esse arquivo monta opcionalmente um arquivo de credenciais do Google Cloudno contêiner otelcol. Você precisa desse arquivo ao executar uma amostra em uma máquina local em que o Application Default Credentials (ADC) está disponível apenas como um arquivo.

Permissões necessárias

• Para receber as permissões necessárias para que os aplicativos de amostra 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 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 de 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 ter as permissões necessárias para visualizar os 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 usando papéis personalizados ou outros papéis predefinidos.

APIs necessárias

Ative as APIs Cloud Logging, Cloud Monitoring, Cloud Trace e Telemetry, se ainda não estiverem ativadas:

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 conseguir 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 configurações diferentes:

• Migrar do exportador do Trace para o endpoint do OTLP descreve como usar a instrumentação em processo para enviar dados de trace diretamente para seu projeto do 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 em processo que envie dados diretamente para o projeto do Google Cloud .

• Correlacionar métricas e traces usando exemplos descreve como configurar um aplicativo Go para gerar exemplos. Um exemplar é um ponto de dados de exemplo anexado a um ponto de dados de métrica. É possível usar exemplares para correlacionar os 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.

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