Esta página foi traduzida pela API Cloud Translation.

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

Este documento descreve a estrutura das amostras de instrumentação fornecidas para as linguagens Go, Java, Node.js e Python. Esses exemplos fornecem 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 projeto do Google Cloud . O coletor contém a vinculação a Google Cloud. Essas amostras usam exportadores Google Cloud para enviar dados de registro e métricas ao seu projeto. No entanto, eles enviam dados de rastreamento para seu projeto usando a API Telemetry.

Talvez você se interesse por outras amostras 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 usar 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 exemplos 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 traces de um aplicativo.

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 é configurado 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.

Intenso

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

Os exemplos mostram como fazer o seguinte:

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

Se você analisar as amostras, vai perceber que a complexidade dessa etapa depende do idioma. Por exemplo, para Go, esta etapa configura a função main para chamar uma função que configura a coleta de métricas e rastreamentos. Para Go, o servidor e o cliente HTTP também são atualizados.
Configure uma estrutura de geração de registros para gravar registros estruturados.

Recomendamos que seus aplicativos gravem registros estruturados, o que faz com que o payload do registro seja formatado 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 agentes para usar essas amostras.
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, 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 rastreamento, 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 projeto do Google Cloud . Para dados de registros e métricas, são usados exportadoresGoogle Cloud . Esses exportadores convertem a telemetria em um formato compatível com a API correspondente e enviam os dados transformados para seu projetoGoogle Cloud emitindo um comando de API. Em contraste, os dados de rastreamento são enviados ao seu projeto usando a API Telemetry, que é compatível com OTLP.
- docker-compose.creds.yaml: esse arquivo monta opcionalmente um arquivo de credenciaisGoogle Cloud no contêiner otelcol. Esse arquivo é necessário quando uma amostra é executada 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 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 as amostras no Cloud Shell, em recursos Google Cloud ou em um ambiente de desenvolvimento local, as permissões anteriores serão suficientes para gravar dados de registros, métricas e rastreamentos. Para aplicativos de produção, uma conta de serviço geralmente fornece as credenciais necessárias.

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 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 papéis personalizados ou outros papéis predefinidos.

APIs necessárias

Enable the Cloud Logging, Cloud Monitoring, Cloud Trace, and Telemetry APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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.