Qual devo usar: agente do Logging ou biblioteca de cliente?

Neste documento, apresentamos as informações necessárias para ajudar você a decidir se quer enviar os registros do aplicativo de maneira programática para o Cloud Logging usando bibliotecas de cliente ou um agente de geração de registros. Os agentes do Logging enviam dados gravados em um arquivo, como stdout, ou um arquivo, como registros para o Cloud Logging. Serviços como o Google Kubernetes Engine, o ambiente flexível do App Engine e o Cloud Functions contêm um agente de geração de registros integrado. Para o Compute Engine, é possível instalar o Agente de operações ou o agente legado do Cloud Logging. Esses agentes coletam registros de locais de arquivos conhecidos ou serviços de geração de registros, como Windows Event Log, journald ou syslogd.

Quando não é possível usar uma biblioteca de cliente ou um agente do Logging, ou quando você quer apenas testar, é possível gravar registros usando o comando gcloud logging write ou enviando comandos HTTP para o endpoint de API Cloud Logging entries.write. A API Cloud Logging oferece suporte a chamadas HTTP e gRPC. O Agente de operações e a maioria das bibliotecas de cliente do Logging chamam a API gRPC Logging. O agente do Logging legado e as bibliotecas de cliente para algumas linguagens chamam a API REST Logging.

Como escolher um agente ou bibliotecas de cliente

Ao decidir entre um agente ou as bibliotecas de cliente, considere as seguintes perguntas:

Seu aplicativo está sendo executado fora do Google Cloud?

Se o aplicativo não estiver em execução no Google Cloud, será necessário enviar registros para a API Logging. Para rotear registros de sistemas locais para o Logging, recomendamos que você use o BindPlane daobservIQ. Para mais informações sobre o BindPlane, consulte Sobre observIQ e BindPlane.

Como alternativa, é possível rotear os registros para o Logging diretamente do aplicativo usando bibliotecas de cliente. Para ambientes temporários, como a computação sem servidor, use bibliotecas de cliente para fazer chamadas diretas para a API Logging.

O serviço do Google Cloud que executa seu aplicativo oferece suporte
está gravando conteúdo de stdout e stderr no seu projeto?

Alguns serviços do Google Cloud são totalmente gerenciados. Portanto, você não precisa usar agentes para enviar registros ao seu projeto do Google Cloud. Use qualquer framework de geração de registros estabelecido na linguagem de sua escolha, como Go, Node.js e Python, para enviar registros ao Logging em produtos em que stdout e stderr são compatíveis por padrão. Uma vantagem de confiar em stdout e stderr em vez de usar bibliotecas de cliente é que as falhas do aplicativo não interrompem o envio de registros para seu projeto. Para informações sobre o envio de registros estruturados por stdout e stderr, consulte a seção Seu aplicativo tem flexibilidade para mudar o formato do registro?.

É possível usar bibliotecas de cliente do Logging, mas lembre-se de que ela pode gerar uma dependência do Logging para testes locais, quando isso não é necessariamente necessário. O uso das bibliotecas de cliente também pode exigir codificação mais complexa para processar explicitamente o armazenamento em buffer e as novas tentativas. Além disso, cada uso das bibliotecas de cliente do Logging cria um novo fluxo de conexão para a API. Essas novas conexões apresentam mais complexidade, usam portas adicionais e enviam solicitações separadas apenas com os registros do aplicativo, o que pode ser um desperdício se não houver muitos registros.

Os registros do aplicativo precisam estar acessíveis no seu ambiente local?

Se você precisar acessar os registros do aplicativo no ambiente local para depuração e outros fins, poderá usar os módulos de geração de registros em algumas linguagens para enviar os resultados para stdout e stderr. As bibliotecas de cliente do Logging para algumas linguagens são compatíveis com registros de roteamento para stdout e stderr.

Ao executar seu aplicativo em serviços do Google Cloud que não são compatíveis com o envio automático de registros gravados em stdout e stderr para seu projeto do Google Cloud, é possível coletar registros stdout e stderr em arquivos no disco e configurar o agente para extraí-los e enviá-los ao Logging. Para mais informações, consulte o guia de configuração do Agente de operações ou do agente do Logging legado.

O processo de instalação do agente é manual ou automático?

Alguns serviços instalam agentes automaticamente ou permitem que você mesmo os instale. Se o serviço usado não permitir a instalação de agentes, será necessário usar as bibliotecas de cliente para usar o Logging.

Você já executa o Fluentd no seu sistema?

O agente do Logging legado é baseado no Fluentd.

Se você já tiver o Fluentd em execução no sistema e quiser usar esse daemon para enviar os registros ao Logging, use o plug-in do Google Cloud Logging para StatefulSet (em inglês).

Você também está coletando métricas do aplicativo para o Cloud Monitoring?

Nas VMs do Compute Engine, o agente de operações pode coletar registros e a maioria das métricas. Consulte Recursos do agente de operações para mais informações.

Se o Agente de operações não atender aos seus casos de uso, use o agente legado do Monitoring ou as bibliotecas de cliente do Monitoring para coletar as métricas.

Seu aplicativo tem flexibilidade para alterar o formato do registro?

Essa pergunta ajuda você a decidir se seu aplicativo pode gerar registros estruturados. O Logging reconhecerá os registros estruturados se você enviá-los para a API Logging no formato de geração de registros estruturados. As bibliotecas de cliente fornecem os métodos para processar esse formato.

Há duas maneiras de gravar registros estruturados: uma é definir campos específicos no envelope LogEntry e a outra é definir o jsonPayload no envelope LogEntry. O esquema para o primeiro é determinado pelo Cloud Logging, enquanto o esquema para o último é determinado pelo usuário.

Configure o agente para reconhecer registros estruturados. Por padrão, os agentes são configurados para detectar registros no formato JSON e processá-los como registros estruturados. Se o aplicativo tiver um formato de registro próprio que não possa ser alterado, mas você quiser que os registros sejam reconhecidos como registros estruturados, será necessário gravar os registros no formato de geração de registros estruturados, geralmente JSON, para stdout e stderr, para que os agentes possam reconhecê-los como registros estruturados. Caso contrário, você precisará configurar seu agente para entender seu próprio formato.

Resumo de cada opção

Diagrama de padrões de geração de registros

  • Bibliotecas de cliente do Cloud Logging

    • Vantagens

      • É possível rotear registros diretamente para a API Cloud Logging.
      • Algumas linguagens podem gerar registros para stdout e stderr usando a biblioteca.
    • Desvantagens

      • Falhas no aplicativo interrompem o envio de registros para seu projeto do Google Cloud.
  • Agente de operações

    • Vantagens
      • O Agente de operações pode enviar registros e métricas usando tecnologias estáveis de código aberto: o Fluent Bit para coleta de registros e o OpenTelemetry Collector para coleta de métricas.
      • É possível coletar registros e métricas de muitos aplicativos comuns. Consulte Monitorar e coletar registros de aplicativos de terceiros.
      • É possível reter registros no ambiente local.
      • Talvez seja possível recuperar os registros das falhas do aplicativo.
      • O Agente de operações está em desenvolvimento ativo.
  • Agente legado do Logging

    • Vantagens
      • O agente usa o Fluentd para coletar registros.
      • É possível reter registros no ambiente local.
      • Talvez seja possível recuperar os registros das falhas do aplicativo.
    • Desvantagens
      • Atualmente, o agente é compatível, mas não está em desenvolvimento ativo.
  • Registros stdout e stderr enviados automaticamente para seu projeto do Google Cloud

    • Vantagens
      • Esse processo é uma maneira comum de emitir registros para ambientes locais.
      • É possível usar bibliotecas de geração de registros arbitrárias.
      • Talvez seja possível recuperar os registros das falhas do aplicativo.
    • Desvantagens
      • Nem todos os ambientes encaminham os registros automaticamente para o Logging.