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

É possível enviar registros de aplicativos para o Cloud Logging usando um agente do Logging ou chamando bibliotecas de cliente diretamente do seu código. Escolher a abordagem certa para seu ambiente de execução ajuda a coletar registros de maneira confiável, sem adicionar dependências desnecessárias ou sobrecarga operacional ao aplicativo.

Os agentes do Logging coletam dados gravados em stdout, stderr, locais de arquivos conhecidos ou serviços de registro do sistema, como Windows Event Log, journald ou syslogd, e os enviam para o Logging. Serviços como o Google Kubernetes Engine, o ambiente flexível do App Engine e o Cloud Run functions incluem um agente do Logging integrado, enquanto para o Compute Engine, é possível instalar o Agente de operações.

Quando não for possível usar uma biblioteca de cliente ou um agente do Logging, ou quando você quiser apenas fazer testes, use o comando gcloud logging write ou envie solicitações HTTP para o endpoint entries.write da API Cloud Logging. A API Logging é compatível com chamadas HTTP e gRPC: o Agente de Operações e a maioria das bibliotecas de cliente do Logging chamam a API Logging gRPC, enquanto as bibliotecas de cliente de algumas linguagens chamam a API Logging REST.

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, você precisará de uma maneira de 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 ao Google Cloud. Para mais informações, consulte Sobre o BindPlane.

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

O serviço Google Cloud que executa seu aplicativo é compatível com

gravar conteúdo de stdout e stderr no seu projeto?

Alguns serviços do Google Cloud são totalmente gerenciados, então não é necessário usar agentes para enviar registros ao seu projeto do 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 ao Logging em produtos em que stdout e stderr são compatíveis por padrão. Uma vantagem de usar stdout e stderr em vez de bibliotecas de cliente é que as falhas do aplicativo não interrompem o envio de registros para o projeto. Para informações sobre como enviar registros estruturados por meio de 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 o 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 o projeto doGoogle Cloud , é possível coletar registros de stdout e stderr em arquivos no disco e configurar o agente para extrair e enviar esses registros para o Logging. Para mais informações, consulte o guia de configuração do Agente de Operações.

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?

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 Logging para o FluentdGoogle Cloud .

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

Seu aplicativo tem flexibilidade para alterar o formato do registro?

Essa pergunta ajuda a decidir se o aplicativo pode gerar registros estruturados. O Logging reconhece registros estruturados se você os enviar para a API Logging no formato de registro estruturado. 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 campo 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

    • As falhas do aplicativo interrompem o envio de registros para o projeto do 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: o Fluent Bit para coleta de registros e o coletor do OpenTelemetry 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ó aceita codificação UTF-8. Ele não é compatível com a conversão de codificação.

• Registros de stdout e stderr enviados automaticamente para o 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.