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

Este documento contém as informações necessárias para ajudar você a decidir se para enviar programaticamente registros do aplicativo ao Cloud Logging usando bibliotecas de cliente ou com uma agente do Logging. Os agentes do Logging enviam dados gravados em um arquivo, como stdout ou um arquivo, como registros no Cloud Logging. Serviços como O Google Kubernetes Engine, o ambiente flexível do App Engine e o Cloud Functions contêm agente do Logging. No Compute Engine, você pode instalar o Agente de operações ou o agente legado do Cloud Logging. Esses agentes coletam registros de locais de arquivo ou geração de registros conhecidos serviços 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ê só quer testar, é possível gravar registros usando o gcloud logging write comando ou enviando comandos HTTP para o endpoint de API Cloud Logging entries.write. A API Cloud Logging é compatível chamadas HTTP e gRPC. O Agente de operações e a maioria dos clientes do Logging chamam a API gRPC Logging. O Logging legado as bibliotecas de cliente e de cliente para algumas linguagens chamam o REST a API 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 sistemas no local para o Logging, recomendamos o uso BindPlane por observIQ (em inglês). Para mais informações sobre o BindPlane, consulte Sobre o observIQ e o BindPlane.

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

O serviço do Google Cloud que executa seu aplicativo é compatível
está gravando conteúdo de stdout e stderr no seu projeto?

Alguns serviços do Google Cloud são totalmente gerenciados, então você não precisa para usar agentes a fim de enviar registros ao seu projeto do Google Cloud. Você pode usar qualquer um framework de geração de registros estabelecido na linguagem de sua preferência, como Go, Node.js e Python, para enviar registros ao Como fazer login em produtos compatíveis com stdout e stderr 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 quebram enviar registros ao seu projeto. Para informações sobre como enviar registros estruturados por meio de stdout e stderr, consulte a seção Seu aplicativo tem flexibilidade para alterar 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 sem suporte enviando automaticamente registros gravados em stdout e stderr para seu projeto do Google Cloud, é possível coletar stdout e stderr fazem os registros em arquivos no disco e configura o agente para raspar esses dados e enviá-los para o Logging. Para mais informações, consulte o guia de configuração do Agente de operações ou o 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á tem o Fluentd em execução no sistema e quer use esse daemon para enviar seus registros para o Logging e, em seguida, use o Plug-in do Google Cloud Logging para README.

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 Como monitorar bibliotecas de cliente para coletar suas 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 envia ao API Logging no formato de geração de registros estruturada. 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 tecnologias de código aberto estáveis: o Fluent Bit para coleta de registros e as Coletor do OpenTelemetry para a coleta de métricas.
      • É possível coletar registros e métricas de vários aplicativos conteinerizados, consulte Monitorar e coletar registros aplicativos.
      • É 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.