Filebeat 模块是什么
模块是为常见软件预设好的采集配置：Nginx、系统日志、MySQL 等，启用后按模板读取对应路径，并用服务端预置的解析管线把原始文本转成结构化字段。它的价值是省掉自己写解析规则——不用为每种日志格式维护一套正则，同时自带仪表盘，装完就能看。代价是日志格式与预设不符时解析会失败，需要先确认实际格式。
基本信息
| 适用平台 | Filebeat 7.x / 8.x，模块目录 modules.d |
|---|---|
| 启用命令 | filebeat modules enable 模块名 |
| 初始化命令 | filebeat setup 加载解析管线与看板 |
| 依赖条件 | 解析管线在 Elasticsearch 侧，需要连通并有权写入 |
典型使用场景
- 标准软件采集：Nginx、系统日志、数据库等常见服务快速接入
- 快速验证：先跑通模块看数据流，再决定是否自定义解析
- 统一字段：模块输出的字段名遵循约定，看板可直接复用
- 多模块组合：一台主机上同时采集多种服务的日志
- 迁移过渡：旧解析规则替换为模块时并行验证
启用与初始化
启用与初始化
filebeat modules enable nginx system # 启用模块
filebeat modules list # 确认启用状态
filebeat setup --pipelines --dashboards # 加载解析管线与看板
# modules.d/nginx.yml 按实际路径调整
# - module: nginx
# access:
# enabled: true
# var.paths: ["/var/log/nginx/access.log"]
# error:
# enabled: true
# var.paths: ["/var/log/nginx/error.log"]
# 验证：前台运行并观察输出
# filebeat -e -c filebeat.yml模块配置要点
| 配置项 | 作用 | 注意 |
|---|---|---|
| enabled | 是否启用该日志类型 | 启用了但路径为空等于没采 |
| var.paths | 日志文件路径列表 | 指错时静默采集不到数据 |
| var.convert_timezone | 时区转换 | 跨时区部署时需要处理 |
| setup 加载 | 解析管线与看板 | 需连到正确的 Elasticsearch 集群 |
| 模块输出字段 | 结构化字段名 | 与自定义规则混用时字段要统一 |
模块的解析发生在 Elasticsearch 侧的解析管线上：只启用模块而没执行 setup，字段不会结构化，检索时还得靠正则硬匹配。
自定义格式的日志不要硬套模块解析：先禁用模块的解析部分，或用处理器覆写输出字段，否则大量解析失败反而更难排查。