Esta página foi traduzida pela API Cloud Translation.

Visão geral dos exemplos de instrumentação

Este documento descreve a estrutura dos exemplos de instrumentação fornecidos para as linguagens Go, Java, Node.js e Python. Esses exemplos fornecem orientações sobre como instrumentar um aplicativo.

Talvez você se interesse por outros exemplos que ilustram diferentes configurações:

Correlacionar 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 os dados de rastro 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 rastros de um aplicativo.

Como as amostras funcionam

Os exemplos para Go, Java, Node.js e Python usam o protocolo OpenTelemetry para coletar dados de trace e métrica. Os exemplos configuram um framework de registro 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 os exemplos no Cloud Shell, em recursos Google Cloudou em um ambiente de desenvolvimento local.

Análise detalhada

Os exemplos usam o OpenTelemetry Collector como um sidecar para receber e enriquecer a telemetria do aplicativo, que é enviada ao seu projeto do Google Cloud usando um exportadorGoogle Cloud . O exportador converte o 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 para seu projeto do Google Cloud emitindo um comando de API.

Os exemplos mostram como fazer o seguinte:

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

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

Recomendamos que seus aplicativos gravem registros estruturados, o que resulta no payload do registro sendo 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 ao seu projeto do 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 esses exemplos.
Configure os 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 os receptores, exportadores, processadores e pipelines.
  
  O serviço telemetry define pipelines para dados de rastro, métrica e registro. Cada entrada de pipeline especifica um receptor, um processador e um exportador. O mesmo receptor, otlp, é usado para métricas e rastros.
  
  A seção exporters descreve como os dados coletados são exportados para um projeto do Google Cloud. Para toda a telemetria, um exportador Google Cloud é utilizado. 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, ele envia os dados transformados para seu projeto do Google Cloud emitindo um comando de API.
- docker-compose.creds.yaml: esse arquivo monta opcionalmente um arquivo de credenciaisGoogle Cloud no contêiner otelcol. Esse arquivo é necessário quando um exemplo é executado em uma máquina local em que as credenciais padrão do aplicativo (ADC) estão disponíveis apenas como um arquivo.

Permissões necessárias

Se você executar os exemplos no Cloud Shell, em recursos Google Cloudou em um ambiente de desenvolvimento local, as permissões listadas nesta seção serão suficientes. Para aplicativos de produção, geralmente uma conta de serviço fornece as credenciais para gravar dados de registro, métricas e rastreamento.

Para receber as permissões necessárias para que os aplicativos de exemplo gravem dados de registro, métricas e rastreamento, 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
- Agente do Cloud Trace (roles/cloudtrace.agent)

Para ter as permissões necessárias para visualizar seus dados de registro, métrica e rastreamento, 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 por meio de papéis personalizados ou de outros papéis predefinidos.

APIs necessárias

Confira a seguir informações sobre as APIs necessárias para enviar dados de telemetria a um projeto do Google Cloud:

Console do Google Cloud

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Google Cloud CLI

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

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com