Migrar do agente legado do Logging para o Fluentd upstream

Se você estiver usando o agente do Logging legado e tiver uma configuração altamente personalizada, recomendamos migrar para o Fluentd de código aberto. É possível configurar o Fluentd para preservar o comportamento do ambiente do agente do Logging sem interromper a coleta de registros pelo Cloud Logging. Este documento descreve o processo de migração.

Comparação dos recursos

A tabela a seguir oferece uma comparação de paridade das principais funcionalidades entre o agente do Logging legado e o Fluentd upstream.

Recursos	Agente legado do Logging	Fluentd upstream
Ingestão de registros no Cloud Logging	Sim	Sim
Registros do sistema padrão (syslog)	Sim	Sim
Entrada de aplicativo de terceiros pré-configurada	Sim	Sim ^†
Tratamento de registros estruturados (JSON) e não estruturados (texto)	Sim	Sim
Junção de exceções de várias linhas	Sim	Sim
Google Cloud enriquecimento de metadados	Sim	Sim
Enriquecimento de metadados do Kubernetes	Sim	Sim
IDs exclusivos de entrada de registro	Sim	Sim
Transformação de campo de registro	Sim	Sim
Mapeamento de gravidade	Sim	Sim
Autenticação (ADC e chaves de conta de serviço)	Sim	Sim
Protocolos de transporte REST e gRPC	Sim	Sim
Integração do Monitoring	Sim	Sim

^†  Embora o pacote google-fluentd-catch-all- config não esteja incluído na instalação padrão do Fluentd e dos plug-ins upstream, é possível manter a funcionalidade de entrada pré-configurada seguindo as etapas de migração detalhadas neste guia.

Antes de começar

Antes de iniciar a migração, verifique se você tem o seguinte:

• Uma instância de VM compatível em um projetoGoogle Cloud .
• Credenciais na instância de VM que autorizam a comunicação com o Cloud Logging. As instâncias de VM do Compute Engine normalmente têm as credenciais corretas por padrão. Para verificar se você tem as credenciais corretas, execute os procedimentos de autorização do agente do Logging.

Migrar para o Fluentd

Esta seção descreve as etapas para migrar para a versão upstream do Fluentd mantendo as principais funcionalidades fornecidas pelo agente do Logging legado.

Para migrar sua configuração, siga estas etapas:

1. Desativar o agente legado do Logging
2. Instalar uma versão estável do fluentd-package
3. Instalar plug-ins da plataforma Google Cloud
4. Migrar os arquivos de configuração dos plug-ins de entrada
5. Atualizar a configuração do syslog
6. Atualizar o arquivo de configuração do Fluentd
7. Validar se o agente do Fluentd está sendo executado corretamente
8. Desinstalar o agente legado do Logging

Observação: esta seção contém um exemplo de comando do Linux. Se você usa o Windows, adapte as etapas de comando a esse ambiente.

Desativar o agente legado do Logging

Antes de instalar o agente Fluentd upstream, pare o agente legado do Logging para evitar conflitos. Para evitar a perda de registros pendentes durante a migração, faça o flush de todos os registros em buffer no encerramento.

Para desligar normalmente o agente do Logging legado, faça o seguinte:

1. Abra uma conexão de terminal com a instância de VM usando SSH ou uma ferramenta semelhante e verifique se você tem acesso ao sudo.

2. Para transferir todos os registros em buffer antes de desligar o agente do Logging legado, ative a opção flush_at_shutdown:

   1. Atualize o arquivo /etc/google-fluentd/google-fluentd.conf para definir a flag flush_at_shutdown como true:

      # Configure the agent to flush all buffer chunks on shutdown
      <match **>
        @type google_cloud
        flush_at_shutdown true
      </match>
      

   2. Reinicie o agente para aplicar as mudanças de configuração:

      sudo service google-fluentd restart
      

3. Interrompa o agente legado do Logging:

   sudo service google-fluentd stop
   

Instale uma versão estável do fluentd-package

Instale uma distribuição estável do Fluentd (fluentd-package) nas suas instâncias de VM. Para instruções, consulte a documentação do Fluentd Install fluent-package (em inglês).

Instalar plug-ins da plataforma Google Cloud

Para permitir que o Fluentd interaja com o Cloud Logging e processe formatos de registro específicos, instale os seguintes plug-ins:

1. Se ainda não estiverem instaladas, instale as ferramentas de build para compilação de extensões:

   Debian ou Ubuntu

   Execute este comando no Debian ou no Ubuntu:

   sudo apt-get update
   sudo apt-get install -y build-essential
   

   CentOS ou RHEL

   Execute o seguinte comando no CentOS ou no RHEL:

   sudo yum update
   sudo yum groupinstall -y "Development Tools"
   

2. Instale o plug-in fluent-plugin-google-cloud:

   sudo fluent-gem install fluent-plugin-google-cloud
   

3. Instale o plug-in fluent-plugin-detect-exceptions:

   sudo fluent-gem install fluent-plugin-detect-exceptions
   

4. Opcional: se a implantação do agente do Logging legada coletar registros de aplicativos em execução em um cluster do Kubernetes, instale o plug-in fluent-plugin-kubernetes_metadata_filter:

   sudo fluent-gem install fluent-plugin-kubernetes_metadata_filter
   

5. Opcional: se o agente do Logging legado coletar e expor métricas no formato do Prometheus, instale as seguintes gems:

   sudo fluent-gem install prometheus-client -v 0.9.0
   sudo fluent-gem install fluent-plugin-prometheus -v 1.4.0
   

   Aviso: as versões do prometheus-client iguais ou mais recentes que 0.10.0 são incompatíveis, o que fará com que o Fluentd falhe durante a inicialização.

Migrar os arquivos de configuração do plug-in de entrada

Para migrar os arquivos de configuração e posição da instalação do Fluentd, siga estas etapas:

1. Crie diretórios para os arquivos de configuração e posição do Fluentd:

   # Create the destination directory for Fluentd configuration files
   sudo mkdir -p /etc/fluent/config.d
   
   # Create the destination directory for position files
   sudo mkdir -p /var/lib/fluent/pos
   

2. Copie os arquivos de configuração google-fluentd para o diretório de configuração do Fluentd:

   sudo cp /etc/google-fluentd/config.d/* /etc/fluent/config.d/
   

3. Copie todos os arquivos de posição (.pos) usados pelo google-fluentd para o diretório position-file do Fluentd:

   sudo cp /var/lib/google-fluentd/pos/*.pos /var/lib/fluent/pos/
   

   Os arquivos de posição são usados para rastrear posições de leitura em arquivos de registro. A migração permite que o Fluentd comece no mesmo ponto em que o google-fluentd estava usando.

4. Atualize o caminho pos_file nos novos arquivos de configuração do Fluentd para apontar para o novo diretório de arquivos de posição:

   sudo sed -i 's#/var/lib/google-fluentd#/var/lib/fluent#g' /etc/fluent/config.d/*.conf
   

5. Conceda ao usuário do serviço Fluentd ,_fluentd, acesso de leitura e gravação ao diretório /var/lib/fluent/:

   sudo chown -R _fluentd:_fluentd /var/lib/fluent/
   

6. Conceda ao usuário _fluentd acesso de leitura aos arquivos syslog:

   sudo usermod -a -G adm _fluentd
   

Atualizar a configuração do syslog

O Fluentd upstream é executado como o usuário sem privilégios, que não pode se vincular a portas privilegiadas numeradas abaixo de 1024. Se a configuração legada do agente do Logging incluir a coleta de syslog baseada em rede usando @type syslog em port 514, ajuste a configuração.

Para atualizar a configuração da porta, faça o seguinte:

1. Substitua todo o conteúdo do arquivo /etc/fluent/config.d/syslog_endpoint.conf pela seguinte configuração:

   sudo tee /etc/fluent/config.d/syslog_endpoint.conf > /dev/null <<EOF
   <source>
     @type syslog
     port 5140
     <transport tcp>
     </transport>
     bind 127.0.0.1
     tag syslog
   </source>
   EOF
   

2. Crie ou modifique o arquivo /etc/rsyslog.d/40-fluentd-forward.conf para encaminhar mensagens syslog à nova porta do Fluentd:

   sudo tee /etc/rsyslog.d/40-fluentd-forward.conf > /dev/null <<EOF
   # Forward all syslog messages to Fluentd on localhost:5140 via TCP
   *.* @@127.0.0.1:5140
   EOF
   

3. Reinicie o serviço rsyslog para aplicar as mudanças:

   sudo systemctl restart rsyslog.service
   

Atualizar o arquivo de configuração principal do Fluentd

Configure o agente Fluentd upstream replicando as configurações do arquivo de configuração do agente, google-fluentd.conf, para o arquivo de configuração principal do Fluentd, localizado em /etc/fluent/fluentd.conf.

Observação: ao instalar os plug-ins do Google, a versão upstream do Fluentd oferece suporte a todos os recursos do agente do Logging legado. Para mais informações, consulte Configurar o agente do Logging.

Para configurar o agente Fluentd upstream, siga estas etapas:

1. Copie todo o conteúdo do arquivo google-fluentd.conf para substituir o arquivo de configuração padrão do Fluentd upstream:

   sudo cp /etc/google-fluentd/google-fluentd.conf /etc/fluent/fluentd.conf
   

2. Atualize o buffer_path nos arquivos de configuração do Fluentd para apontar para o novo diretório do Fluentd:

   sudo sed -i 's#/var/log/google-fluentd#/var/log/fluent#g' /etc/fluent/fluentd.conf
   

3. Inspecione o arquivo fluentd.conf para confirmar se a configuração inclui o seguinte:

   • @include config.d/*.conf está presente para importar toda a configuração do plug-in de entrada.
   • O bloco <match **> @type google_cloud está configurado para transmitir registros para o Cloud Logging.
   • O buffer_path no plug-in de saída agora aponta para /var/lib/fluent/.
   • Qualquer diretiva pos_file nos plug-ins de entrada aponta para /var/lib/fluent/.

4. Execute uma simulação para verificar sua configuração do Fluentd:

   sudo fluentd -c /etc/fluent/fluentd.conf --dry-run
   

   Verifique se há alertas de error ou warn na saída resultante. Resolva todos os problemas identificados antes de continuar. Para detalhes sobre mudanças na sintaxe, consulte Compatibilidade de configuração para Fluentd upstream.

5. Reinicie o agente Fluentd:

   sudo service fluentd restart
   

Validar se o agente do Fluentd está em execução corretamente

Depois de iniciar o Fluentd, verifique se os registros estão sendo enviados com sucesso para o Cloud Logging:

1. Verifique se o Fluentd está sendo executado sem erros:

   $ sudo service fluentd status
   

   O status do serviço precisa estar ativo (em execução).

2. Verifique os registros do Fluentd e confira se não há erros ou avisos:

   sudo tail -n 100 /var/log/fluent/fluentd.log | grep -iE "error|warn|failed|exception" || true
   

   Nenhum erro ou aviso deve ser listado.

3. Verifique o Cloud Logging para confirmar se os registros estão sendo recebidos da sua instância de VM. Para informações sobre como visualizar seus registros, consulte Como usar a Análise de registros.

Desinstalar o agente legado do Logging

Só depois de validar que o novo Fluentd está enviando registros para o Cloud Logging, remova o agente do Logging legado e os arquivos de configuração dele:

Debian ou Ubuntu

  sudo apt-get remove --purge google-fluentd

CentOS ou RHEL

  sudo yum remove google-fluentd