上游 Fluentd 的配置兼容性

从 Logging 代理迁移到上游 Fluentd 时，您可能会遇到配置不兼容的情况，需要采取解决方法来防止启动错误。本文档介绍了如何解决配置不兼容问题。

旧版 Logging 代理与上游 Fluentd 之间的语法变化

旧版 Logging 代理依赖于 Fluentd v0.12 语法，而上游 Fluentd 采用 v1 标准。此过渡涉及弃用各种参数，并引入新的嵌套指令来处理核心功能，从而取代之前使用的扁平配置结构。

为防止启动失败并确保日志得到正确处理，您必须移除或替换已弃用的参数。以下部分介绍了如何更新已弃用的参数。

输出插件配置

下表列出了必须在输出插件配置中更新的参数，以避免出现错误：

旧版 Logging 代理语法 上游 Fluentd 语法 备注
不适用 <buffer> Fluentd 输出插件支持 <match> 部分下的 <buffer> 部分，用于配置事件的缓冲。如需了解详情，请参阅 Fluentd 文档中的配置：缓冲区部分。
buffer_type @type
buffer_path path
buffer_chunk_limit chunk_limit_size
disable_retry_limit retry_forever
retry_limit retry_max_times
max_retry_wait retry_max_interval
num_threads flush_thread_count
partial_success 不适用 移除此形参。上游 Fluentd 默认永久启用部分成功，仅舍弃无效行。

以下是旧版 Logging 代理中 google-cloud 输出插件配置的示例：

<match **>
  @type google_cloud
  buffer_type file
  buffer_path /var/log/google-fluentd/buffers
  buffer_chunk_limit 512KB
  flush_interval 5s
  disable_retry_limit false
  retry_limit 3
  retry_wait 10
  max_retry_wait 300
  num_threads 8
</match>

执行更新后，配置如下所示：

<match **>
  @type google_cloud
  <buffer>
    @type file
    path /var/log/google-fluentd/buffers
    chunk_limit 512KB
    flush_interval 5s
    retry_forever false
    retry_max_times 3
    retry_wait 10
    retry_max_interval 300
    flush_thread_count 8
  </buffer>
</match>

输入插件配置

下表列出了必须在输入插件配置中更新的参数，以避免出现错误：

旧版 Logging 代理语法 上游 Fluentd 语法 备注
format <parse> 如需了解详情，请参阅 Fluentd 文档中的配置：解析部分。
protocol_type <transport> 指明 syslog 传输的协议，可以是 udp、tcp, 或 tls。
auto_typecast 在 json 解析插件中使用时，请移除此参数。

以下是旧版 Logging 代理中的输入插件配置示例：

<source>
    @type tail
    path /var/log/my-app.log
    format json
</source>

执行更新后，配置如下所示：

<source>
    @type tail
    path /var/log/my-app.log
    <parse>
      @type json
    </parse>
</source>

Ruby Time 对象序列化

上游 Fluentd 需要对 <record> 过滤条件（例如 record_transformer）内使用的原始 Ruby Time 对象进行显式转换。如果不进行显式转换，这些对象会在缓冲区刷新期间导致严重的序列化错误。

如果您的配置使用 ${time} 和 enable_ruby true，您必须将对象显式转换为原始类型（整数或字符串）。

以下是旧版 Logging 代理中的过滤插件配置示例：

<filter foo.bar>
  @type record_transformer
   enable_ruby true
  <record>
    raw_timestamp ${time}
  </record>
</filter>

执行更新后，配置如下所示：

<filter foo.bar>
  @type record_transformer
   enable_ruby true
  <record>
    raw_timestamp ${time.to_i}
  </record>
</filter>

gRPC 传输和压缩默认设置

借助 google_cloud 输出插件，您可以配置是使用 gRPC 还是 REST/JSON 与 Cloud Logging API 通信。

为提升性能，我们建议启用 gRPC 传输并配置 grpc_compression_algorithm gzip。这种组合可最大限度地减少网络开销和 CPU 消耗，尤其是在处理大量日志时。

如需实现这些优化，请使用以下配置：

<match **>
  @type google_cloud
  use_grpc true
  grpc_compression_algorithm gzip
</match>

此外，由于 gRPC 依赖于端口 443 上的 HTTP/2 流式传输，因此您必须确保网络基础设施允许 gRPC/HTTP/2 流量。在 gRPC 受限的环境中，您必须明确定义 use_grpc false 以恢复为标准 HTTP/REST 通信。

RabbitMQ 正则表达式模式

旧版 Logging 代理用于 RabbitMQ 日志提取的正则表达式模式通常与新版 RabbitMQ 的输出格式不兼容。这些差异可能会导致日志在收集过程中被错误处理或静默舍弃。

新版 RabbitMQ 日志在时间戳中加入了毫秒级精度（例如 YYYY-MM-DD HH:MM:SS.L），并包含特定的严重程度和 PID 标记（例如 [info] <0.213.0>），而旧版正则表达式无法匹配这些内容。

如果您的 Fluentd 代理已配置为收集 RabbitMQ 日志，则必须更新 <parser> 部分，以正确处理当前的日志格式。

以下是旧版 Logging 代理的 RabbitMQ 输入插件配置示例：

<source>
  @type tail
  path /var/log/rabbitmq/*.log
  pos_file /var/lib/google-fluentd/pos/rabbitmq.pos
  tag rabbitmq
  format multiline
  format_firstline /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/
  format1 /^(?<time>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) \[(?<severity>\w+)\] (?<message>.*)/
  time_format %Y-%m-%d %H:%M:%S
</source>

执行更新后，配置如下所示：

<source>
  @type tail
  path /var/log/rabbitmq/*.log
  pos_file /var/log/fluentd/pos/rabbitmq.pos
  read_from_head true
  tag rabbitmq
  <parse>
    @type multiline
    format_firstline /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}/
    format1 /^(?<time>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}) \[(?<severity>[^\]]+)\] <(?<pid>[^>]+)> (?m:(?<message>.*))$/
    time_format %Y-%m-%d %H:%M:%S.%L
  </parse>
</source>