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

Este documento fornece as informações necessárias para decidir se você quer enviar programaticamente registros de aplicativos ao 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 Run Functions contêm um agente de geração de registros integrado. Para o Compute Engine, instale o Agente de operações. Esse agente coleta registros de locais de arquivo conhecidos ou serviços de geração de registros, como Windows Event Log, journald ou syslogd.

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 comandos HTTP ao endpoint de API 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 Logging do gRPC. As bibliotecas de cliente para algumas linguagens chamam a API REST Logging.

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 sendo executado 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 usar o Bindplane, que implanta e gerencia coletores do OpenTelemetry para enviar telemetria ao Google Cloud. Para mais informações, consulte Sobre o Bindplane.

Também é possível encaminhar registros para o Logging diretamente do aplicativo usando bibliotecas de cliente. Para ambientes efêmeros, como a 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

escrever conteúdo stdout e stderr para 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 . Você pode 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 falhas de aplicativos não interrompem o envio de registros ao projeto. Para informações sobre como enviar registros estruturados usando stdout e stderr, consulte a seção Seu aplicativo tem a flexibilidade de 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 oferecem suporte ao envio automático de registros gravados em stdout e stderr para seu projeto doGoogle Cloud , é possível coletar registros de 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.

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 seus registros ao Logging, use o Google Cloud plug-in do Logging para fluentd (link 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 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ê os enviar 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

    • As falhas de aplicativos interrompem o envio de registros ao seu 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 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 stdout e stderr enviados automaticamente para seu 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.