Escolha a abordagem de instrumentação mais eficaz para seu aplicativo com base na plataforma de computação do Google Cloud e nos requisitos de telemetria. Este guia oferece recomendações para o Google Kubernetes Engine (GKE), o Compute Engine e o Cloud Run, ajudando você a decidir entre o coletor do OpenTelemetry criado pelo Google, o Agente de operações e a exportação direta do OpenTelemetry em processo.
Este documento fornece recomendações gerais, além de orientações para as seguintes plataformas:
Para ver 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:
Dados de métricas: recomendamos que você use o OpenTelemetry ou as bibliotecas de cliente do Prometheus:
- O OpenTelemetry fornece um framework de código aberto e independente de fornecedor e bibliotecas de cliente 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 copiadas 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 as bibliotecas do OpenTelemetry, é possível rotear a telemetria pelo OpenTelemetry Collector independente ou exportar diretamente do processo do aplicativo. O arquivo de configuração do OpenTelemetry Collector controla como o coletor recebe, processa e exporta telemetria. Em geral, recomendamos que os coletores recebam e exportem telemetria usando o protocolo OpenTelemetry (OTLP). A API Telemetry (OTLP) implementa esse protocolo.
Há duas abordagens fundamentais para enviar telemetria ao seu projeto do Google Cloud :
Exportação baseada em coletor (independente de fornecedor): instrumente o código do aplicativo com o SDK do OpenTelemetry e use o exportador OTLP em processo para enviar dados a um coletor do OpenTelemetry, como o coletor do OpenTelemetry criado pelo Google ou um receptor do Agente de Operações. O coletor recebe a telemetria e a encaminha para o projeto do Google Cloud . O código do aplicativo permanece totalmente neutro em relação ao 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 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 for compatível com um. Para ambientes em que a execução de um processo de coletor separado não é prática, use a exportação direta em processo.
Recomendações de plataforma
Como os ambientes de computação do Google Cloud têm diferentes recursos de ciclo de vida e sidecar, o padrão de coleta ideal varia de acordo com a plataforma. As seções a seguir fornecem recomendações específicas para seu 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:
|
| Traces | Faça o seguinte:
|
| Registros | Configure seu app para gerar
registros estruturados em JSON para O GKE coleta registros gravados em
|
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:
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:
|
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:
Como alternativa, se você quiser configurar a coleta apenas 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 O Cloud Run coleta registros gravados em
|
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 | Não é possível gravar dados de métricas diretamente no Cloud Run functions. É possível gerar métricas com base em registros. |
| Traces | Use o SDK do OpenTelemetry e o exportador OTLP para sua linguagem (link em inglês). |
| Registros | Configure seu app para gerar
registros estruturados em JSON para O Cloud Run functions coleta registros gravados em
|
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 OTLP para sua linguagem (link em inglês). |
| Traces | Use o SDK do OpenTelemetry e o exportador OTLP para sua linguagem (link em inglês). |
| Registros | Configure seu app para gerar
registros estruturados em JSON para O App Engine coleta registros gravados em
|
Exemplos e guias de implementação
A visão geral do exemplo descreve a arquitetura e os papéis necessários do Identity and Access Management para os seguintes exemplos de código baseados em coletor:
Migrar do exportador do Trace para o endpoint OTLP descreve como atualizar um aplicativo que usa a exportação direta para enviar dados de trace formatados em OTLP.
Observabilidade para desenvolvedores de agentes de IA 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
Nesta seção, fornecemos links para o SDK do OpenTelemetry e os exportadores do OTLP em diferentes linguagens.
Referências gerais: