Escolher uma abordagem de instrumentação

É possível escolher a abordagem de instrumentação mais eficaz para seu aplicativo com base na Google Cloud plataforma de computação e nos requisitos de telemetria. Este guia fornece recomendações para o Google Kubernetes Engine (GKE), o Compute Engine e o Cloud Run, ajudando você a decidir entre o Coletor OpenTelemetry criado pelo Google, o Agente de operações e a exportação direta do OpenTelemetry no processo.

Este documento fornece recomendações gerais, bem como orientações para as seguintes plataformas:

• GKE
• Compute Engine
• Cloud Run
• Cloud Run functions
• App Engine

Para exemplos de aplicativos, consulte Exemplos e guias de implementação.

As recomendações nesta página não são as únicas soluções, e outras abordagens podem funcionar. Para receber mais orientações, entre em contato com o Cloud Customer Care.

Recomendações gerais

Esta seção contém recomendações gerais sobre como instrumentar seu aplicativo. Para orientações específicas da plataforma, consulte Recomendações da plataforma.

• Dados de registro: recomendamos que você use um framework que possa ser configurado para gerar registros estruturados em JSON para o Cloud Logging. Para gravar dados de registro, recomendamos o seguinte:

  • Go: slog.
  • Python: logging.
  • JavaScript: Pino
  • Java: SLF4J com Log4j2.

• Dados de métricas: recomendamos que você use OpenTelemetry ou do Prometheus:

  • O OpenTelemetry fornece um framework de código aberto e bibliotecas de cliente neutras para instrumentar aplicativos para métricas.
  • As bibliotecas de cliente do Prometheus (Go, Java, Python etc.) geram métricas que podem ser expostas em um endpoint HTTP e extraídas por um agente.

• Dados de trace: recomendamos que você use o OpenTelemetry para gerar dados de trace distribuídos do código do aplicativo.

Arquiteturas de coleta do OpenTelemetry

Ao instrumentar um aplicativo com bibliotecas do OpenTelemetry, é possível encaminhar a telemetria pelo Coletor OpenTelemetry independente ou exportar diretamente do processo do aplicativo. O arquivo de configuração do Coletor OpenTelemetry controla como o coletor recebe, processa e exporta a telemetria. Em geral, recomendamos que os coletores recebam e exportem a telemetria usando o protocolo OpenTelemetry (OTLP). A API Telemetry (OTLP) implementa esse protocolo.

Há duas abordagens fundamentais para enviar telemetria ao seu Google Cloud projeto:

• Exportação baseada em coletor (neutra do fornecedor) : você instrumenta o código do aplicativo com o SDK do OpenTelemetry e usa o exportador OTLP no processo para enviar dados a um coletor do OpenTelemetry, como o Coletor OpenTelemetry criado pelo Google ou um receptor do Agente de operações. O coletor recebe a telemetria e a encaminha para seu Google Cloud projeto. O código do aplicativo permanece completamente neutro do fornecedor.

• Exportação direta (específica do fornecedor) : você instrumenta o código do aplicativo com o SDK do OpenTelemetry e configura o OpenTelemetry para enviar telemetria ao seu projeto usando a API Telemetry. Não é necessário implantar um coletor, mas o código do aplicativo inclui dependências específicas do fornecedor.

Recomendamos que você use um coletor do OpenTelemetry quando o ambiente de computação oferecer suporte a ele. Para ambientes em que a execução de um processo de coletor separado não é prática, use a exportação direta no processo.

Recomendações da plataforma

Como Google Cloud os ambientes de computação têm diferentes recursos de ciclo de vida e de arquivo secundário, o padrão de coleta ideal varia de acordo com a plataforma. As seções a seguir fornecem recomendações específicas para o ambiente de implantação.

GKE

Para informações gerais sobre o GKE, consulte Visão geral do GKE.

Tipo	Recomendação
Métricas	Recomendamos que você use o Serviço Gerenciado do Google Cloud para Prometheus. Para instrumentação, siga um destes procedimentos: Use as bibliotecas de cliente do Prometheus. Se você usar essa abordagem, também recomendamos utilizar a coleção gerenciada, que inclui instruções de instalação do exportador de cópia e colagem para aplicativos comuns. Use as bibliotecas do OpenTelemetry e o Coletor OpenTelemetry: Implante o Coletor OpenTelemetry criado pelo Google no Google Kubernetes Engine. Use o SDK do OpenTelemetry e o exportador OTLP para sua linguagem. O coletor recebe dados de métricas do exportador OTLP no processo do SDK , processa esses dados e os exporta. Certifique-se de configurar o coletor para exportar dados de métricas para o Serviço Gerenciado para Prometheus. Para mais informações, consulte Introdução ao Coletor OpenTelemetry.
Traces	Faça o seguinte: Implante o Coletor OpenTelemetry criado pelo Google no Google Kubernetes Engine. O coletor recebe dados de trace do exportador OTLP no processo do SDK's , processa esses dados e os envia ao seu Google Cloud projeto usando a API Telemetry (OTLP). Use o SDK do OpenTelemetry e o exportador OTLP para sua linguagem.
Registros	Configure seu app para gerar registros estruturados em JSON para stdout e stderr. Para ver uma lista de frameworks, consulte Frameworks de geração de registros recomendados. O GKE coleta registros gravados em stdout e stderr automaticamente. Para mais informações, acesse Sobre os registros do GKE.

Compute Engine

Para informações gerais sobre o Compute Engine, consulte Instâncias de máquina virtual.

Tipo	Recomendação
Métricas e traces	Faça o seguinte: Usar o Agente de operações para coletar métricas e traces. Por exemplo, consulte Coletar métricas e traces do protocolo OpenTelemetry (OTLP). Este guia descreve como configurar o Agente de operações para receber dados de métricas e traces dos exportadores OTLP no processo do SDK, transformar esses dados, e enviá-los ao seu Google Cloud projeto. Os dados de métricas são enviados usando a API Cloud Monitoring e os dados de trace são enviados usando a API Cloud Trace. Use o SDK do OpenTelemetry e o exportador OTLP para sua linguagem. Como alternativa, se você só quiser configurar a coleta para métricas no formato do Prometheus, use o receptor do Prometheus do Agente de operações para coletar métricas instrumentadas usando bibliotecas de cliente do Prometheus ou o SDK do OpenTelemetry.
Registros	Faça o seguinte: Configure seu app para gerar registros estruturados em JSON em um arquivo. Para ver uma lista de frameworks, consulte Frameworks de geração de registros recomendados. Instale o Agente de operações e configure um receptor. Por exemplo, consulte Receptores de geração de registros.

Cloud Run

Para informações gerais sobre o Cloud Run, consulte O que é o Cloud Run.

Tipo	Recomendação
Métricas e traces	Faça o seguinte: Use o SDK do OpenTelemetry e o exportador OTLP para sua linguagem. Implante um arquivo secundário do OpenTelemetry para coletar métricas e traces. Para exemplos, consulte os seguintes documentos: Gravar métricas OTLP usando um arquivo secundário do OpenTelemetry. Implantar o Coletor OpenTelemetry criado pelo Google no Cloud Run. O coletor recebe dados de registro, métricas e traces de exportadores OTLP no processo do SDK e transforma os dados recebidos. Em seguida, ele exporta dados de métricas usando o googlemanagedprometheus exportador e exporta dados de registro e métricas usando Google Cloud exportadores. Para o serviço do Cloud Run, use o faturamento baseado em instâncias. Com o faturamento baseado em instâncias, a CPU é alocada para todo o ciclo de vida da instância, o que é necessário porque a instrumentação do OpenTelemetry faz o processamento em segundo plano. Para mais informações, consulte Configurações de faturamento para serviços do Cloud Run. Como alternativa, se você só quiser configurar a coleta para métricas no formato do Prometheus, use o arquivo secundário do Prometheus para o Cloud Run a fim de coletar métricas instrumentadas usando bibliotecas de cliente do Prometheus ou o SDK do OpenTelemetry.
Registros	Configure seu app para gerar registros estruturados em JSON para stdout e stderr. Para ver uma lista de frameworks, consulte Frameworks de geração de registros recomendados. O Cloud Run coleta registros gravados em stdout e stderr automaticamente. Para mais informações, acesse Gravar registros de contêiner.

Cloud Run functions

Para informações gerais sobre o Cloud Run functions, consulte Visão geral do Cloud Run functions.

Tipo	Recomendação
Métricas	A gravação direta de dados de métricas não é compatível com o Cloud Run functions. É possível gerar métricas com base em registros.
Traces	Use o SDK do OpenTelemetry e o exportador do Cloud Trace na sua linguagem.
Registros	Configure seu app para gerar registros estruturados em JSON para stdout e stderr. Para ver uma lista de frameworks, consulte Frameworks de geração de registros recomendados. O Cloud Run functions coleta registros gravados em stdout e stderr automaticamente. Para mais informações, consulte Cloud Run functions: visão geral de monitoramento e geração de registros.

App Engine

Para informações gerais sobre o App Engine, consulte Visão geral do App Engine.

Tipo	Recomendação
Métricas	Use o SDK do OpenTelemetry e o exportador do Cloud Monitoring para seu idioma.
Traces	Use o SDK do OpenTelemetry e o exportador do Cloud Trace na sua linguagem.
Registros	Configure seu app para gerar registros estruturados em JSON para stdout e stderr. Para ver uma lista de frameworks, consulte Frameworks de geração de registros recomendados. O App Engine coleta registros gravados em stdout e stderr automaticamente. Para mais informações, consulte Gravar e visualizar registros.

Exemplos e guias de implementação

• A visão geral de exemplos descreve a arquitetura e os papéis necessários do Identity and Access Management para os seguintes exemplos de código baseados em coletores:

  • Go
  • Java
  • Node.js
  • Python

• Migrar do exportador do Cloud Trace para o endpoint OTLP descreve como atualizar um aplicativo que usa a exportação direta para enviar dados de trace formatados em OTLP.

• Instrumentar aplicativos de IA generativa descreve como instrumentar ou ativar agentes de IA generativa criados com o LangGraph ou o framework do Kit de Desenvolvimento de Agente (ADK).

Documentação do OpenTelemetry

Esta seção fornece links para o SDK do OpenTelemetry e os exportadores para OTLP, Cloud Trace e Cloud Monitoring.

Referências gerais:

• APIs e SDKs de linguagem
• Exportador OTLP

Go

• Go SDK
• Exportador OTLP do Go
• Exportador do Cloud Trace para Go
• Exportador do Cloud Monitoring para Go

Java

• SDK do Java
• Exportador OTLP do Java
• Exportador do Cloud Trace para Java
• Exportador do Cloud Monitoring para Java

JavaScript

• SDK para JavaScript
• Exportador OTLP do JavaScript
• Exportador do Cloud Trace em JavaScript
• Exportador do Cloud Monitoring em JavaScript

Python

• SDK do Python
• Exportador OTLP do Python
• Exportador do Cloud Trace em Python
• Exportador do Cloud Monitoring para Python