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 ao 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é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 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 inglês). 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étricas. 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.

Investigação

Os exemplos usam o OpenTelemetry Collector como um arquivo secundário para receber e enriquecer a telemetria do aplicativo, que é enviada ao seu Google Cloud projeto usando um Google Cloud exportador. O exportador converte a telemetria em um formato compatível com a API Cloud Trace, a API Cloud Monitoring ou a API Cloud Logging. Em seguida, eles enviam os dados transformados ao seu Google Cloud projeto emitindo um comando de API.

Os exemplos mostram como fazer o seguinte:

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

   Se você analisar os exemplos, vai notar que 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, o que resulta na carga útil do registro formatada como um objeto JSON. Para esses registros, é possível criar consultas que pesquisam caminhos JSON específicos e indexar campos específicos na carga útil do 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 coletor do OpenTelemetry. Esse coletor especifica receptores, exportadores, processadores e pipelines.

     O serviço telemetry define pipelines para dados de trace, métricas e registros. Cada entrada de pipeline especifica um receptor, um processador e um exportador. O mesmo receptor, otlp, é usado para métricas e traces.

     A seção exporters descreve como os dados coletados são exportados para um Google Cloud projeto. Para dados de registro e métricas, Google Cloud os exportadores são usados. Esses exportadores convertem a telemetria em um formato compatível com a API correspondente e enviam os dados transformados ao seu Google Cloud projeto emitindo um comando de API. Em contraste, os dados de trace são enviados ao seu projeto usando a API Telemetry, que oferece suporte ao OTLP.

   • docker-compose.creds.yaml: esse arquivo monta opcionalmente um Google Cloud arquivo de credenciais no otelcol contêiner. Esse arquivo é necessário quando um exemplo é executado 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 registro, métricas e traces, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

  • Gravador de registros (roles/logging.logWriter)
  • Gravador de métricas do Monitoring (roles/monitoring.metricWriter)
  • Gravador de traces de telemetria do Cloud (roles/telemetry.tracesWriter)

  Se você executar os exemplos no Cloud Shell, em Google Cloud recursos, ou em um ambiente de desenvolvimento local, as permissões anteriores serão suficientes para gravar dados de registro, métricas e traces. Para aplicativos de produção, uma conta de serviço normalmente fornece as credenciais necessárias.

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

  • Visualizador de registros (roles/logging.viewer)
  • Leitor do monitoramento (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 personalizados papéis ou outros predefinidos papéis.

APIs necessárias

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

Papéis necessários para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM 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.