从旧版 Logging 代理迁移到上游 Fluentd

如果您使用的是旧版 Logging 代理，并且配置高度自定义，那么我们建议您迁移到开源 Fluentd。您可以配置 Fluentd，以保留 Logging 代理环境的行为，而不会中断 Cloud Logging 对日志的收集。本文档介绍了迁移流程。

特性比较

下表比较了旧版 Logging 代理与上游 Fluentd 之间的主要功能对等性。

特性	旧版 Logging 代理	上游 Fluentd
将日志提取到 Cloud Logging	是	是
标准系统日志 (syslog)	是	是
预配置的第三方应用输入	是	是 ^†
结构化 (JSON) 和非结构化（文本）日志处理	是	是
多行异常合并	是	是
Google Cloud 元数据丰富化	是	是
Kubernetes 元数据丰富	是	是
唯一日志条目 ID	是	是
日志字段转换	是	是
严重程度映射	是	是
身份验证（ADC 和服务账号密钥）	是	是
REST 和 gRPC 传输协议	是	是
监控集成	是	是

^†  尽管 google-fluentd-catch-all-config 软件包未包含在上游 Fluentd 和插件的标准安装中，但您可以按照本指南中详述的迁移步骤来保持预配置的输入功能。

准备工作

在开始迁移之前，请确保您具备以下各项：

• Google Cloud 项目中受支持的虚拟机实例。
• 虚拟机实例上用于授权与 Cloud Logging 通信的凭据。默认情况下，Compute Engine 虚拟机实例通常具有正确的凭据。如需检查您是否具有正确的凭据，请运行向 Logging 代理授权过程。

迁移到 Fluentd

本部分概述了迁移到上游 Fluentd 版本并同时保持旧版 Logging 代理提供的关键功能的步骤。

如需迁移设置，请完成以下步骤：

1. 关闭旧版 Logging 代理
2. 安装稳定版 fluentd-package
3. 安装 Google Cloud 平台插件
4. 迁移输入插件配置文件
5. 更新 syslog 配置
6. 更新 Fluentd 配置文件
7. 验证 Fluentd 代理是否正常运行
8. 卸载旧版 Logging 代理

注意： 本部分包含的是 Linux 命令示例。如果您使用的是 Windows，请根据该环境调整命令步骤。

关闭旧版 Logging 代理

在安装上游 Fluentd 代理之前，您必须停止旧版 Logging 代理，以避免冲突。为避免在迁移期间丢失任何待处理的日志，请确保在关闭时刷新所有缓冲的日志。

如需安全关闭旧版 Logging 代理，请执行以下操作：

1. 使用 SSH 或类似工具建立与虚拟机实例的终端连接，并确保您拥有 sudo 访问权限。

2. 如需在关闭旧版 Logging 代理之前刷新所有缓冲的日志，请启用 flush_at_shutdown 选项：

   1. 更新 /etc/google-fluentd/google-fluentd.conf 文件，将 flush_at_shutdown 标志设置为 true：

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

   2. 重启代理以应用配置更改：

      sudo service google-fluentd restart
      

3. 停止旧版 Logging 代理：

   sudo service google-fluentd stop
   

安装稳定版 fluentd-package

在虚拟机实例中安装稳定版 Fluentd (fluentd-package)。如需了解相关说明，请参阅 Fluentd 安装 fluent-package 文档。

安装 Google Cloud 平台插件

如需让 Fluentd 与 Cloud Logging 互动并处理特定日志格式，请安装以下插件：

1. 如果尚未安装，请安装用于扩展程序编译的 build 工具：

   Debian 或 Ubuntu

   在 Debian 或 Ubuntu 上运行以下命令：

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

   CentOS 或 RHEL

   在 CentOS 或 RHEL 上运行以下命令：

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

2. 安装 fluent-plugin-google-cloud 插件：

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

3. 安装 fluent-plugin-detect-exceptions 插件：

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

4. 可选：如果您的旧版 Logging 代理部署从 Kubernetes 集群内运行的应用收集日志，请安装 fluent-plugin-kubernetes_metadata_filter 插件：

   sudo fluent-gem install fluent-plugin-kubernetes_metadata_filter
   

5. 可选：如果您的旧版 Logging 代理以 Prometheus 格式收集和公开指标，请安装以下 gem：

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

   警告： 版本不低于 0.10.0 的 prometheus-client 不兼容，会导致 Fluentd 在启动期间崩溃。

迁移输入插件配置文件

如需迁移 Fluentd 安装的现有配置和位置文件，请完成以下步骤：

1. 为 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. 将 google-fluentd 配置文件复制到 Fluentd 的配置目录：

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

3. 将 google-fluentd 使用的所有位置 (.pos) 文件复制到 Fluentd 的位置文件目录：

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

   位置文件用于跟踪日志文件中的读取位置。迁移后，Fluentd 会从 google-fluentd 之前使用的位置开始。

4. 更新新 Fluentd 配置文件中的 pos_file 路径，以指向新的位置文件目录：

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

5. 向 Fluentd 服务用户 _fluentd 授予对 /var/lib/fluent/ 目录的读写权限：

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

6. 为 _fluentd 用户授予对 syslog 文件的读取权限：

   sudo usermod -a -G adm _fluentd
   

更新 syslog 配置

上游 Fluentd 以非特权用户身份运行，无法绑定到编号小于 1024 的特权端口。如果您的旧版 Logging 代理设置包含通过在 port 514 上使用 @type syslog 进行的基于网络的 syslog 收集，则必须调整配置。

如需更新端口配置，请执行以下操作：

1. 将 /etc/fluent/config.d/syslog_endpoint.conf 文件的全部内容替换为以下配置：

   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. 创建或修改 /etc/rsyslog.d/40-fluentd-forward.conf 文件，以将 syslog 消息转发到新的 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. 重启 rsyslog 服务以应用更改：

   sudo systemctl restart rsyslog.service
   

更新主 Fluentd 配置文件

通过将代理的配置文件 google-fluentd.conf 中的设置复制到位于 /etc/fluent/fluentd.conf 的主 Fluentd 配置文件，来配置上游 Fluentd 代理。

注意： 安装 Google 插件后，上游版本的 Fluentd 支持旧版 Logging 代理的所有功能。如需了解详情，请参阅配置 Logging 代理。

如需配置上游 Fluentd 代理，请完成以下步骤：

1. 复制 google-fluentd.conf 文件的全部内容，以覆盖默认的上游 Fluentd 配置文件：

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

2. 更新 Fluentd 配置文件中的 buffer_path，以指向新的 Fluentd 目录：

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

3. 检查 fluentd.conf 文件，确认配置包含以下内容：

   • @include config.d/*.conf 用于导入所有输入插件配置。
   • <match **> @type google_cloud 块配置为将日志流式传输到 Cloud Logging。
   • 输出插件中的 buffer_path 现在指向 /var/lib/fluent/。
   • 输入插件中的任何 pos_file 指令都指向 /var/lib/fluent/。

4. 执行试运行以验证 Fluentd 配置：

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

   检查生成的输出中是否有任何 error 或 warn 提醒。您必须先解决所有已发现的问题，然后才能继续。如需详细了解语法变更，请参阅上游 Fluentd 的配置兼容性。

5. 重启 Fluentd 代理：

   sudo service fluentd restart
   

验证 Fluentd 代理是否正常运行

启动 Fluentd 后，验证日志是否已成功发送到 Cloud Logging：

1. 验证 Fluentd 是否在无错误的情况下运行：

   $ sudo service fluentd status
   

   服务状态应为有效（正在运行）。

2. 检查 Fluentd 日志，确保没有错误或警告：

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

   不应列出任何错误或警告。

3. 检查 Cloud Logging，确认是否已从虚拟机实例收到日志。如需了解如何查看日志，请参阅使用 Logs Explorer。

卸载旧版 Logging 代理

只有在验证新 Fluentd 是否已成功将日志发送到 Cloud Logging 后，才能移除旧版 Logging 代理及其配置文件：

Debian 或 Ubuntu

  sudo apt-get remove --purge google-fluentd

CentOS 或 RHEL

  sudo yum remove google-fluentd