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.

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 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 toda a telemetria, é usado um Google Cloud exportador. O exportador converte a telemetria num formato compatível com a API Cloud Trace, a API Cloud Monitoring ou a API Cloud Logging. Em seguida, envia os dados transformados para o seu Google Cloud projeto emitindo um comando da API.
- 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

Se executar os exemplos no Cloud Shell, em Google Cloud recursos ou num ambiente de programação local, as autorizações indicadas nesta secção são suficientes. Para aplicações de produção, normalmente, uma conta de serviço fornece as credenciais para escrever dados de registo, métricas e rastreio.

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)
- Agente do Cloud Trace (roles/cloudtrace.agent)

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

Seguem-se informações sobre as APIs necessárias para enviar dados de telemetria para um projeto do Google Cloud :

Google Cloud consola

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace 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.

Enable the APIs

CLI do Google Cloud