Escolher uma abordagem de instrumentação

Nesta página, você encontra recomendações para instrumentar seu app em diferentes plataformas doGoogle Cloud , como o Google Kubernetes Engine (GKE) e o Cloud Run. Se o app ainda não estiver instrumentado, use estas recomendações para orientar sobre como instrumentar o app para enviar dados de telemetria ao Google Cloud. 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 suporte doGoogle Cloud .

Há recomendações para:

Para informações sobre exemplos de instrumentação, consulte os documentos listados na seção Amostras de código.

GKE

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

Tipo Recomendação
Métricas

Recomendamos que você use o Google Cloud Managed Service para Prometheus.

Para instrumentação, siga um destes procedimentos:
Traces

Faça o seguinte:

  1. Implante o coletor do OpenTelemetry criado pelo Google no Google Kubernetes Engine.

    O coletor recebe dados de rastreamento do exportador OTLP no processo do SDK, processa esses dados e os envia para seu projeto Google Cloud usando a API Telemetria (OTLP).

  2. 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 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:

  1. Usar o Agente de operações para coletar métricas e traces.

    Por exemplo, consulte Coletar métricas e traces do protocolo OpenTelemetry (OTLP). Neste guia, descrevemos como configurar o Agente de operações para receber dados de métricas e rastreamentos dos exportadores OTLP no processo do SDK, transformar esses dados e enviá-los ao seu projeto Google Cloud . Os dados de métrica são enviados usando a API Cloud Monitoring, e os dados de rastreamento são enviados usando a API Cloud Trace.

  2. Use o SDK do OpenTelemetry e o exportador OTLP para sua linguagem (link em inglês).

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:

  1. 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.
  2. 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:

  1. Use o SDK do OpenTelemetry e o exportador OTLP para sua linguagem (link em inglês).

  2. Implante um arquivo secundário do OpenTelemetry para coletar métricas e traces.

    Por exemplo, consulte os seguintes documentos:

  3. Para o serviço do Cloud Run, use o faturamento com base em instâncias. Com o faturamento com base em instâncias, a CPU é alocada durante 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ê 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 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 as funções do Cloud Run, consulte Visão geral das funções do Cloud Run.

Tipo Recomendação
Métricas A gravação direta de métricas não é compatível com as funções do Cloud Run. É possível gerar métricas com base em registros.
Traces Use o SDK do OpenTelemetry e o exportador do Cloud Trace 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.

As funções do Cloud Run coletam registros gravados em stdout e stderr automaticamente. Para mais informações, consulte Funções do Cloud Run: visão geral do monitoramento e do registro em 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 sua linguagem.
Traces Use o SDK do OpenTelemetry e o exportador do Cloud Trace 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 App Engine coleta registros gravados em stdout e stderr automaticamente. Para mais informações, consulte Gravar e visualizar registros.

Frameworks de geração de registros recomendados

Para coletar registros, recomendamos que você use um framework que possa ser configurado para gerar objetos JSON serializados para stdout, stderr ou um arquivo. O agente do Logging, integrado ou instalado, raspa o arquivo e grava registros estruturados para o Cloud Logging. Para gravar dados de registro, recomendamos o seguinte:

Amostras de código

Ao instrumentar um aplicativo com bibliotecas do OpenTelemetry, você decide como os dados de telemetria são enviados ao seu projeto Google Cloud . Há duas abordagens fundamentais:

  • Você instrumenta o código do aplicativo com o SDK do OpenTelemetry e usa o exportador OTLP no processo incluído no SDK para enviar dados a um coletor do OpenTelemetry. O coletor recebe dados do exportador em processo e os envia para o projeto Google Cloud . As mudanças feitas no código do aplicativo são neutras em relação ao fornecedor. O coletor contém a lógica para enviar a telemetria ao seu projeto Google Cloud .

  • Você instrumenta o código do aplicativo com o SDK do OpenTelemetry e usa um exportador no processo que envia dados diretamente para o projeto do Google Cloud . Algumas mudanças feitas no aplicativo são específicas do fornecedor. No entanto, não é necessário configurar ou implantar um coletor.

Recomendamos usar um coletor do OpenTelemetry para exportar seus dados de telemetria quando o ambiente for compatível com o uso de um coletor. Em alguns ambientes, é necessário usar um exportador no processo que envia dados diretamente para o projetoGoogle Cloud .

Exemplos de exportação baseada em coletor

Para exemplos de instrumentação específicos de linguagem, consulte os seguintes documentos:

Se você quiser saber como os coletores são definidos e implantados, consulte Visão geral da amostra.

Exemplos de exportação direta usando exportadores no processo

  • Migre do exportador do Trace para o endpoint OTLP. Este documento descreve a instrumentação em processo para exportar dados de rastreamento diretamente para seu projeto do Google Cloud . Exemplos são fornecidos para Go, Java, Node.js e Python.

  • Instrumentar aplicativos de IA generativa. Este documento fornece informações sobre como instrumentar ou ativar agentes de IA generativa criados com frameworks LangGraph ou Agent Development Kit (ADK).

Referências ao OpenTelemetry

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

Referências gerais:

Go

Java

JavaScript

Python