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

Este documento fornece as informações necessárias para decidir se envia registros de aplicativo ao Cloud Logging de forma programática usando bibliotecas de cliente ou um agente de registro. Os agentes de registro 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 as funções do Cloud Run contêm um agente de registro 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 arquivo conhecidos ou serviços de geração de registro, como Windows Event Log, journald ou syslogd.

Quando você não puder usar uma biblioteca de cliente ou um agente do Logging ou quando apenas quiser fazer testes, use o comando gcloud logging write ou envie comandos HTTP para o endpoint entries.write da API Cloud Logging. 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 em Google Cloud, será necessário enviar registros para a API Logging. Para rotear registros de sistemas locais para o Logging, recomendamos o uso do Bindplane, que implanta e gerencia coletores do OpenTelemetry para enviar telemetria a Google Cloud. Para mais informações, consulte Sobre o Bindplane.

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

O serviço Google Cloud em execução no seu aplicativo oferece suporte

escrever conteúdo stdout e stderr para seu projeto?

Alguns Google Cloud serviços são totalmente gerenciados. Portanto, não é necessário usar agentes para enviar registros ao projeto Google Cloud . É possível usar qualquer framework de geração de registros estabelecido na linguagem de sua escolha, como Go, Node.js e Python, para enviar registros para o Logging em produtos compatíveis com stdout e stderr por padrão. Uma vantagem de usar stdout e stderr em vez de usar bibliotecas de cliente é que falhas no aplicativo não interrompem o envio de registros para o projeto. Para informações sobre como enviar registros estruturados por stdout e stderr, consulte a seção O 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 Google Cloud que não oferecem suporte ao envio automático de registros gravados em stdout e stderr para o projetoGoogle Cloud , é possível coletar registros stdout e stderr em arquivos no disco e configurar o agente para raspá-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 legados.

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 seu sistema e quiser usar esse daemon para enviar seus registros ao Logging, use o Google Cloud plug-in do Logging para fluentd.

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 do Monitoring legado ou as bibliotecas de cliente do Monitoring para coletar suas métricas.

Seu aplicativo tem flexibilidade para alterar o formato do registro?

Essa pergunta ajuda você a decidir se o aplicativo pode gerar registros estruturados. O Logging reconhece registros estruturados se você enviar os registros 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

• 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 o projeto Google Cloud .

• Agente de operações

  • Vantagens

    • O Agente de operações pode enviar registros e métricas usando tecnologias de código aberto estáveis: 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.

  • Desvantagens

    • O Fluent Bit só oferece suporte à codificação UTF-8. Ele não oferece suporte à conversão de codificação.

• Agente legado do Logging

  • Vantagens
    • O agente usa o Fluentd para coletar registros, que oferece suporte à conversão de codificação.
    • É 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 de stdout e stderr enviados automaticamente para o projeto 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.