Fluentd 详解:日志收集、路由与插件生态

Fluentd 中文详解:source/filter/match 配置、tag 路由、输入输出与过滤插件、文件缓冲和重试的边界、Fluent Bit 部署分工,以及通过 DataKit Log Streaming 接收日志。

最佳实践
事件记录与日志数据分析主题插画

Fluentd 是 CNCF 毕业项目,也是一款以 Ruby 为主、可通过插件扩展的日志收集器。本文讲解其架构、配置实战与适用边界,并说明更换日志接收端时的验证步骤。配置示例依据 Fluentd 1.x 与接收端文档整理。CNCF 项目页 · Fluentd 源码

核心要点速览

  • 配置三大指令。<source> 输入,<filter> 加工,<match> 选择输出,靠 tag 串联路由。同一路由内按配置顺序匹配,首个命中的 <match> 接走事件。
  • 插件分内置和外部安装。先确认目标插件的维护状态及 Fluentd、Ruby 和后端版本要求,再确定接入方式。
  • 缓冲可用内存或文件。文件缓冲能在保留磁盘数据的情况下恢复待发块,持续故障仍受队列、磁盘和重试策略约束。
  • 输出迁移先做验证。核对新接收端协议、字段和失败重试,再调整路由。

1. 配置结构与 tag 路由

<source>
  @type tail
  path /var/log/nginx/access.log
  pos_file /var/log/fluentd/nginx.pos
  tag access.nginx
  <parse>
    @type nginx
  </parse>
</source>

<filter access.nginx>
  @type record_transformer
  <record>
    hostname "#{Socket.gethostname}"
    env "production"
  </record>
</filter>

<match access.**>
  @type file
  path /var/log/aggregated/nginx
</match>

tag 是 Fluentd 的路由入口。source 给事件打 tag,匹配的过滤器按顺序加工,到首个命中的 <match> 就选择输出。把具体的规则排在宽规则前,过滤器放在对应输出前。两个相同的 <match> 不会双写,需要分发到多处时使用 out_copy 等显式分发方式。配置与匹配顺序

pos_file 记录文件读取位置,重启时可从保留的位置续读,不能用来判断后端是否已入库。启动时已有的文件如果没有保存位置,默认从文件尾读取,补读历史需显式设置 read_from_head true。每个 in_tail 配置应使用自己的位置文件,服务账号要能读取日志并写入位置文件和输出目录。tail 输入

这里的 nginx 解析器适用于匹配其格式的访问日志,并使用解析出的时间作为事件时间。自定义 log_format 要按实际格式配置解析器。示例使用的 out_file 默认按时间切片写出,不能用文件是否立即出现判断采集是否成功。Nginx 解析器 · file 输出

2. 核心插件速览

类别 常用插件
输入 in_tail(文件)、in_http(HTTP 接收)、in_syslog(UDP/TCP)、in_exec(读取外部命令输出)
过滤 record_transformer(增删改字段)、grep(模式过滤)、parser(解析已有记录中的字符串字段)、fluent-plugin-geoip(外部插件,IP 富化)
输出 out_file、out_http、out_forward(Forward 转发)、fluent-plugin-opensearch(外部插件,配置为 @type opensearch)

parser 过滤器处理已切分的事件。需要把多行合成一个事件时,应在支持多行组装的输入阶段处理。外部插件应安装到 Fluentd 实际使用的 Ruby 环境,再核对插件版本与依赖。parser 过滤器 · 插件管理 · GeoIP 插件 · OpenSearch 插件

3. 缓冲与可靠性

以下是替换第一节文件输出的示例,接收端需支持相同的 HTTP 请求格式。示例显式设置了 json_array,需要 Fluentd 1.10.4 或更新版本。

<match access.**>
  @type http
  endpoint https://logs.example.com/ingest
  json_array false
  retryable_response_codes [503]
  <format>
    @type json
  </format>
  <buffer>
    @type file
    path /var/log/fluentd/buffer/http
    flush_mode interval
    flush_interval 5s
    total_limit_size 512m
    overflow_action throw_exception
    retry_max_interval 30s
    retry_forever true
  </buffer>
</match>

文件缓冲 + retry_forever 可以在持久磁盘上保留待发块,并持续重试可重试的失败。示例明确把 HTTP 503 列入重试范围。其他非成功状态需要按接收端语义配置,例如错误的请求体导致的 400 通常需要先修格式。实际能积压多久,要看输入速率、队列上限和磁盘空间。上例的 512m 是缓冲实例的容量上限,还需留出文件系统空间。HTTP 输出 · 缓冲配置

out_forward 可在多个接收节点间做加权负载均衡和故障切换,分流不会产生副本。默认不等待 ACK,启用 require_ack_response true 后等待接收端 in_forward 的确认,按至少一次方式发送。若接收端已处理但 ACK 丢失,重试可能产生重复。这个 ACK 也不能证明下游已经持久化或建立索引。Forward 输出

4. Fluentd vs Fluent Bit 一句话区分

Fluentd 适合需要特定插件和加工规则的链路,Fluent Bit 适合关注节点资源开销的采集场景。 二者可以通过 Forward 协议传日志。Kubernetes 中可以用 Fluent Bit DaemonSet 采集,再交给 Fluentd 汇聚,也可以按所需插件直接输出。内存和吞吐取决于流量、插件、缓冲和目标端,应按实际配置测量。Fluent Bit 官方对比 · Forward 互通

将 Fluentd 日志发送到新接收端

保留已有输入和过滤链时,可以先验证输出适配。观测云 Log Streaming 文档列出了 Fluentd HTTP 与 InfluxDB 输出接入方式。按部署方式启用 DataKit 的 Log Streaming 采集器,再将 HTTP 输出指向可访问的 /v1/write/logstreaming?source=nginx&service=web。普通文本模式可用 json_array false 的逐行 JSON,再通过 Pipeline 或采集器的 json_as_fields 选项处理字段。type=influxdb 另有行协议要求,不能把同样的 JSON 请求体加个参数就发过去。

用带固定事件标识的样本核对接收结果。Fluentd 的 tag 和事件时间是独立元数据,普通 JSON 输出需要把要保留的值显式写入记录,再按接收端规则映射。重点检查事件时间、多行日志、字段类型和去重口径,再用隔离样本观察接收失败后的积压、补发和重复。等新端能查到这些事件,再逐步调整生产路由。

常见问题(FAQ)

Fluentd 的 tag 和日志里的字段有什么区别?

tag 是事件的路由元数据,字段是记录本身的数据。tag 决定“这条日志流往哪”。如果接收端也要按 tag 查询,可通过 record_transformer 将 ${tag} 显式写入一个业务字段。record_transformer

buffer 目录写满会怎样?

区分 Fluentd 达到缓冲上限和文件系统写不进数据两种情况。overflow_action 为缓冲溢出提供 throw_exception、block 或 drop_oldest_chunk,无法替代磁盘容量管理。in_tail 遇到 BufferOverflowError 会暂停读取和更新位置文件,解除后继续。等待期间如果源文件轮转并删除,仍可能读不到积压的原始日志。缓冲配置 · tail 的溢出行为

Fluentd 性能瓶颈在哪?

先分辨是解析和过滤占用 CPU,还是缓冲磁盘、网络和接收端拖慢发送。单机没有固定的 EPS 门槛。可以按插件支持情况使用多 worker,或将日志分散到多个实例,比较时用相同解析规则、记录大小、负载和输出确认方式。多 worker

配置文件改完怎么生效?

先用运行环境中的 fluentd --dry-run -c fluent.conf 检查配置与插件能否加载。Linux 的 fluent-package 常用配置路径是 /etc/fluent/fluentd.conf,旧 td-agent 已停止维护。systemctl reload fluentd 取决于服务单元是否支持 reload。Unix 下向 supervisor 发送 SIGHUP 会通过重启 worker 重新加载,内存缓冲刷新失败时不会重试,应先确认所用插件和缓冲的行为。配置文件路径 · 命令选项 · 信号处理

系列阅读

资料核对日期:2026-11-06。


获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通,按量计费,真正的云服务!

立即开始

选择观测云版本

代码托管平台