Qual deve usar: agente de registo ou biblioteca de cliente?

Este documento fornece as informações de que precisa para ajudar a decidir se deve enviar programaticamente registos de aplicações para o Cloud Logging através de bibliotecas cliente ou de um agente de registo. Os agentes de registo enviam dados escritos num ficheiro, como stdout ou um ficheiro, como registos 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 registo integrado. Para o Compute Engine, pode instalar o agente de operações ou o agente do Cloud Logging antigo. Estes agentes recolhem registos de localizações de ficheiros conhecidas ou serviços de registo, como o Windows Event Log, o journald ou o syslogd.

Quando não pode usar uma biblioteca cliente ou um agente do Logging, ou quando só quer experimentar, pode escrever registos usando o comando gcloud logging write ou enviando comandos HTTP para o ponto final da API Cloud Logging entries.write. A API Cloud Logging suporta chamadas HTTP e gRPC. O agente de operações e a maioria das bibliotecas de cliente de registo chamam a API Logging gRPC. O agente de registo antigo e as bibliotecas cliente para alguns idiomas chamam a API REST Logging.

Escolher um agente ou bibliotecas de cliente

Quando estiver a decidir entre um agente ou as bibliotecas de cliente, considere as seguintes questões:

A sua aplicação está a ser executada fora do Google Cloud?

Se a sua aplicação não estiver a ser executada no Google Cloud, precisa de uma forma de enviar registos para a API Logging. Para encaminhar registos de sistemas no local para o Logging, recomendamos que use o Bindplane, que implementa e gere coletores do OpenTelemetry para enviar telemetria para o Google Cloud. Para mais informações, consulte o artigo Acerca do Bindplane.

O Bindplane permite-lhe recolher telemetria de várias origens e exportar esses dados para o Cloud Monitoring e o Cloud Logging.

Em alternativa, pode encaminhar os registos para o Logging diretamente a partir da aplicação através de bibliotecas de cliente. Para ambientes efémeros, como a computação sem servidor, tem de usar bibliotecas cliente para fazer chamadas diretas para a API Logging.

O Google Cloud serviço que executa a sua aplicação suporta
Escrever conteúdo stdout e stderr para o seu projeto?

Alguns Google Cloud serviços são totalmente geridos, pelo que não precisa de usar agentes para enviar registos para o seu projeto Google Cloud . Pode usar qualquer framework de registo estabelecida no idioma da sua escolha, como Go, Node.js e Python, para enviar registos para o Logging em produtos onde stdout e stderr são suportados por predefinição. Uma vantagem de depender de stdout e stderr em vez de usar bibliotecas de cliente é que as falhas de aplicação não interrompem o envio de registos para o seu projeto. Para informações sobre o envio de registos estruturados através do stdout e do stderr, consulte a secção A sua aplicação tem a flexibilidade de alterar o formato do registo?.

Pode usar bibliotecas de cliente do Logging, mas tenha em atenção que pode introduzir uma dependência do Logging para testes locais, quando não precisa necessariamente dele. A utilização das bibliotecas cliente também pode exigir uma programação mais complexa para processar explicitamente o armazenamento em buffer e as novas tentativas. Além disso, cada utilização das bibliotecas cliente de registo cria uma nova stream de ligação à API. Estas novas ligações introduzem mais complexidade, usam portas adicionais e enviam pedidos separados apenas com os registos da aplicação, o que pode ser um desperdício se não existirem muitos registos.

Os registos da aplicação têm de estar acessíveis no seu ambiente local?

Se precisar de aceder aos registos da aplicação no seu ambiente local para depuração e outros fins, pode usar os módulos de registo em alguns idiomas para gerar resultados em stdout e stderr. O registo de bibliotecas cliente para alguns idiomas suporta o encaminhamento de registos para stdout e stderr.

Quando executa a sua aplicação em serviços que não suportam o envio automático de registos escritos para o stdout e o stderr para o seu projeto doGoogle Cloud , pode recolher registos do stdout e do stderr em ficheiros no disco e configurar o agente para extrair esses registos e enviá-los para o Logging. Google Cloud Para mais informações, consulte o guia de configuração do agente do Ops ou do agente de registo antigo.

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

Alguns serviços instalam agentes automaticamente ou permitem-lhe instalá-los manualmente. Se o serviço que está a usar não lhe permitir instalar agentes, tem de usar as bibliotecas de cliente para usar o Logging.

Já está a executar o Fluentd no seu sistema?

O agente de registos antigo baseia-se no Fluentd.

Se já tiver o Fluentd em execução no seu sistema e quiser usar esse daemon para enviar os seus registos para o Logging, use o Google Cloud plug-in do Logging para o fluentd.

Também está a recolher métricas de aplicações para o Cloud Monitoring?

Nas VMs do Compute Engine, o agente de operações pode recolher registos e a maioria das métricas. Consulte as funcionalidades do agente de operações para mais informações.

Se o agente Ops não resolver os seus exemplos de utilização, pode usar o agente de monitorização antigo ou as bibliotecas de cliente de monitorização para recolher as suas métricas.

A sua aplicação tem a flexibilidade de alterar o formato do registo?

Esta pergunta ajuda a decidir se a sua aplicação pode gerar registos estruturados. O registo reconhece registos estruturados se enviar os registos para a API Logging no formato de registo estruturado. As bibliotecas cliente fornecem os métodos para processar este formato.

Existem duas formas de escrever registos estruturados: uma é definir campos específicos no LogEntryenvelope, e a outra é definir o campo jsonPayload no LogEntry envelope. O esquema do primeiro é determinado pelo Cloud Logging, enquanto o esquema do segundo é determinado pelo utilizador.

Tem de configurar o agente para reconhecer registos estruturados. Por predefinição, os agentes estão configurados para detetar registos no formato JSON e processá-los como registos estruturados. Se a sua aplicação tiver o seu próprio formato de registo que não pode alterar, mas quiser que os registos sejam reconhecidos como registos estruturados, tem de escrever os registos no formato de registo estruturado, normalmente JSON, para stdout e stderr, para que os agentes os possam reconhecer como registos estruturados. Caso contrário, tem de configurar o seu agente para compreender o seu próprio formato.

Resumo de cada opção

Diagrama de padrões de registo

  • Bibliotecas de cliente do Cloud Logging

    • Vantagens

      • Pode encaminhar os registos diretamente para a API Cloud Logging.
      • Alguns idiomas podem gerar registos para stdout e stderr através da biblioteca.

    • Desvantagens

      • As falhas de sistema da aplicação impedem o envio de registos para o seu Google Cloud projeto.

  • Ops Agent

    • Vantagens

      • O agente de operações pode enviar registos e métricas através de tecnologias de código aberto estáveis: o Fluent Bit para a recolha de registos e o OpenTelemetry Collector para a recolha de métricas.
      • Pode recolher registos e métricas de muitas aplicações comuns. Consulte o artigo Monitorize e recolha registos de aplicações de terceiros.
      • Pode reter registos no seu ambiente local.
      • Pode conseguir recuperar registos de falhas de aplicações.
      • O agente de operações está em desenvolvimento ativo.

    • Desvantagens

      • O Fluent Bit só suporta a codificação UTF-8. Não suporta a codificação de conversões.

  • Agente de registos antigo

    • Vantagens
      • O agente usa o Fluentd para recolher registos, que suporta a codificação de conversões.
      • Pode reter registos no seu ambiente local.
      • Pode conseguir recuperar registos de falhas de aplicações.
    • Desvantagens
      • O agente é atualmente suportado, mas não está em desenvolvimento ativo.

  • Os registos stdout e stderr são enviados automaticamente para o seu Google Cloud projeto

    • Vantagens
      • Este processo é uma forma comum de emitir registos para ambientes locais.
      • Pode usar bibliotecas de registo arbitrárias.
      • Pode conseguir recuperar registos de falhas de aplicações.
    • Desvantagens
      • Nem todos os ambientes encaminham automaticamente os registos para o Logging.