Esta página foi traduzida pela API Cloud Translation.

Vista geral dos exemplos de instrumentação baseada em coletores

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

A instrumentação nestes exemplos, que inclui a utilização do SDK OpenTelemetry e do exportador OTLP no processo do SDK, é independente do fornecedor. O exportador no processo envia telemetria para o coletor do OpenTelemetry, que recebe esses dados e, em seguida, envia-os para o seu Google Cloud projeto. O coletor contém a associação a Google Cloud. Estes exemplos usam Google Cloud exportadores para enviar dados de registo e métricas para o seu projeto. No entanto, enviam dados de rastreio para o seu projeto através da API Telemetry.

Pode ter interesse noutros exemplos que ilustram diferentes configurações:

O artigo Migre do exportador de rastreio para o ponto final OTLP descreve como usar a instrumentação no processo para enviar dados de rastreio diretamente para o seu Google Cloud projeto.

Recomendamos que use um coletor do OpenTelemetry para exportar os dados de telemetria quando o seu ambiente suporta a utilização de um coletor. Se não puder usar um coletor, tem de usar um exportador no processo que envie diretamente dados para o seu Google Cloud projeto.
O artigo Correlacione métricas e rastreios através de exemplares descreve como configurar uma aplicação Go para gerar exemplares. Um exemplar é um ponto de dados de exemplo anexado a um ponto de dados de métrica. Pode usar exemplos para correlacionar os dados de rastreio e métricas.
Use o agente de operações e o protocolo OpenTelemetry (OTLP) descreve como pode configurar o agente de operações e um recetor OTLP para recolher métricas e rastreios de uma aplicação.

Como funcionam os exemplos

Os exemplos para Go, Java, Node.js e Python usam o protocolo OpenTelemetry para recolher dados de rastreio e métricas. Os exemplos configuram uma framework de registo para escrever registos estruturados e o coletor OpenTelemetry está configurado para ler a partir do fluxo stdout da aplicação. Para recomendações de estruturas, consulte o artigo Escolha uma abordagem de instrumentação.

As aplicações são criadas e implementadas através do Docker. Não tem de usar o Docker quando instrumenta uma aplicação com o OpenTelemetry.

Pode executar os exemplos no Cloud Shell, em Google Cloud recursos ou num ambiente de programação local.

Análise detalhada

Os exemplos usam o OpenTelemetry Collector como um sidecar para receber e enriquecer a telemetria da aplicação, que é depois enviada para o seu Google Cloud projeto através de um Google Cloud exportador. O exportador converte a telemetria num formato compatível com a Cloud Trace API, a Cloud Monitoring API ou a Cloud Logging API. Em seguida, enviam os dados transformados para o seu Google Cloud projeto através da emissão de um comando da API.

Os exemplos mostram como fazer o seguinte:

Configure o OpenTelemetry para recolher métricas e rastreios através do coletor OpenTelemetry.

Se rever os exemplos, vai reparar que a complexidade deste passo depende do idioma. Por exemplo, para o Go, este passo configura a função main para chamar uma função que configura a recolha de métricas e rastreios. Para o Go, o servidor e o cliente HTTP também são atualizados.
Configure uma framework de registo para escrever registos estruturados.

Recomendamos que as suas aplicações escrevam registos estruturados, o que faz com que a carga útil do registo seja formatada como um objeto JSON. Para estes registos, pode criar consultas que pesquisam caminhos JSON específicos e pode indexar campos específicos no payload do registo.

Alguns serviços, como o Google Kubernetes Engine, têm agentes incorporados que extraem registos estruturados e enviam esses registos para o seu projeto. Google Cloud Outros serviços, como o Compute Engine, exigem que instale um agente que extrai e envia os seus registos. Se quiser saber mais sobre os agentes que instala, consulte a vista geral do agente de operações.

Não precisa de instalar agentes para usar estes exemplos.
Configure ficheiros Docker. Todos os exemplos contêm os seguintes ficheiros YAML:
- docker-compose.yaml: configura os serviços para a aplicação, o coletor do OpenTelemetry e um gerador de carga. Por exemplo, o serviço para o coletor OpenTelemetry, otelcol, especifica uma imagem, um volume e variáveis de ambiente. O ponto final do coletor 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. Este coletor especifica recetores, exportadores, processadores e pipelines.
  
  O serviço telemetry define pipelines para dados de rastreio, métricas e registos. Cada entrada do pipeline especifica um recetor, um processador e um exportador. O mesmo recetor, otlp, é usado para métricas e rastreios.
  
  A secção exporters descreve como os dados recolhidos são exportados para um Google Cloud projeto. Para dados de registo e métricas, são usados exportadores.Google Cloud Estes exportadores convertem a telemetria num formato compatível com a API correspondente e, em seguida, enviam os dados transformados para o seu projetoGoogle Cloud emitindo um comando da API. Por outro lado, os dados de rastreio são enviados para o seu projeto através da API Telemetry, que suporta OTLP.
- docker-compose.creds.yaml: este ficheiro monta opcionalmente um ficheiro de credenciais no contentor otelcol.Google Cloud Este ficheiro é necessário quando um exemplo é executado numa máquina local onde as credenciais predefinidas da aplicação (ADC) estão disponíveis apenas como um ficheiro.

Autorizações necessárias

Para receber as autorizações de que precisa para que as aplicações de exemplo escrevam dados de registo, métricas e rastreio, peça ao seu administrador que lhe conceda as seguintes funções da IAM no seu projeto:
- Logs Writer (roles/logging.logWriter)
- Monitoring Metric Writer (roles/monitoring.metricWriter)
- Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
Se executar os exemplos no Cloud Shell, em Google Cloud recursos ou num ambiente de desenvolvimento local, as autorizações anteriores são suficientes para escrever dados de registo, métricas e rastreio. Para aplicações de produção, uma conta de serviço fornece normalmente as credenciais necessárias.

Para receber as autorizações de que precisa para ver os dados de registo, métricas e rastreios, peça ao seu administrador para lhe conceder as seguintes funções da IAM no seu projeto:
- Visualizador de registos (roles/logging.viewer)
- Visitante de monitorização (roles/monitoring.viewer)
- Utilizador do Cloud Trace (roles/cloudtrace.user)
Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

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

O que se segue?

Para saber mais sobre os coletores, consulte o artigo Coletor OpenTelemetry integrado na Google.

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