linux服务-Filebeat原理与安装

Filebeat原理与安装

参考：官网，文档配置

一、Filebeat 原理

Filebeat 是 Elastic 生态轻量级日志采集器，主打轻量、低资源占用、高可靠，专为无 Java 环境的服务器设计，可将日志转发至 Logstash/Elasticsearch/Redis/Kafka 等组件，适配容器、系统日志、应用日志等多场景采集需求，其工作原理可拆解为 4 个核心环节：

1. 核心组件

   组件	作用
   Prospectors（勘探器）	监控指定路径的日志文件，支持通配符 / 递归采集，检测文件新增、轮转、删除
   Harvesters（收割机）	单个文件的实际读取进程，记录文件偏移量（offset），逐行读取日志内容
   Registry（注册表）	本地持久化文件（默认路径/var/lib/filebeat/registry），记录每个文件的读取偏移量、inode 等信息，重启后可续传，避免重复采集
   Output（输出器）	将采集的日志转发至 ES/Kafka/Redis/Logstash 等，支持负载均衡、压缩、重试机制

2. 工作流程

   1. Prospectors 扫描指定路径，为每个日志文件启动独立 Harvester；
   2. Harvester 逐行读取日志，将数据写入内存队列（默认 2048 条）；
   3. 输出器从内存队列批量读取数据，按配置转发至目标端；
   4. 成功发送后，Registry 更新文件偏移量；若发送失败，Filebeat 自动重试（默认重试 3 次，可配置），确保数据不丢失；
   5. 日志文件轮转 / 重命名时，Prospectors 基于 inode 识别文件，保证采集不中断。

3. 核心特性

   • 轻量无依赖：仅需 Go 编译的二进制文件，无 Java 环境，内存占用通常 < 50MB；

   • 断点续传：基于 Registry 文件记录偏移量，重启 / 崩溃后可从断点继续采集；

   • 自动发现：支持容器（Docker/K8s）、系统日志等自动发现采集目标；

   • 低延迟：内存队列 + 批量发送，兼顾性能与实时性；

   • 数据增强：内置 processors 可添加主机 / 容器 / K8s 元数据，便于日志溯源。

4. 一句话总结：

   通过 Filebeat 依据 filebeat.input 配置按文件类型采集日志文件，对不同类型文件分类读取处理后将数据输出至 Elasticsearch、Redis、Kafka 等后端存储，最终在 Kibana 中实现数据的可视化展示与分析。

二、Filebeat 安装

• 环境准备
  • 系统：CentOS 7/8、Ubuntu 18.04+
  • 权限：root 或 sudo 权限
  • 网络：可访问目标输出端（如 ES/Kafka），或本地下载安装包

2.1、安装

• 手动安装

  • 下载解压

    wgethttps://artifacts.elastic.co/downloads/beats/filebeat/filebeat-8.18.8-linux-x86_64.tar.gztarxf filebeat-8.18.8-linux-x86_64.tar.gzmvfilebeat-8.18.8-linux-x86_64 filebeatmkdir/opt/filebeat/{data,log}

  • 权限说明

    chmod777filebeat -Rchmod755/opt/filebeatchmod755/opt/filebeat/filebeatchmod600/opt/filebeat/filebeat.yml# <-- 不配成600启动会异常chmod755/opt/filebeat/logchmod700/opt/filebeat/data

  • 自启脚本

    cat>/etc/systemd/system/filebeat.service<<EOF [Unit] Description=Filebeat Service After=network.target [Service] Type=simple User=root ExecStart=/opt/filebeat/filebeat -c /opt/filebeat/filebeat.yml --path.home /opt/filebeat --path.data /opt/filebeat/data --path.logs /opt/filebeat/logs Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target EOF

  • 启动

    # 1. 先手动验证 Filebeat 配置（关键：确保无语法/权限错误）/opt/filebeat/filebeattestconfig -c /opt/filebeat/filebeat.yml# 输出 "Config OK" 则配置无问题# 2. 重载 systemd 配置systemctl daemon-reload# 3. 停止旧进程+启动服务systemctl stop filebeat systemctl start filebeat# 4. 查看服务状态systemctl status filebeat

2.2、默认配置

• 默认配置说明：vim /opt/filebeat/filebeat.yml

  # 日志输入配置（核心）filebeat.inputs: - type: filestream# 7.16+ 推荐类型（替代原 log 类型）id: my-filestream-id# 唯一标识，便于管理多输入源enabled:false# 默认为关闭，启用需改为 truepaths:# 日志路径支持通配符- /var/log/*.log# 扩展配置（常用）encoding: utf-8# 编码格式，默认 utf-8exclude_lines:['^DBG']# 过滤以 DBG 开头的行include_lines:['^ERR|^WARN']# 仅保留 ERR/WARN 开头的行exclude_files:['\.gz$']# 过滤 .gz 压缩文件recursive_glob.enabled:true# 开启子目录递归采集（最大 8 级）# 模块配置（系统/nginx 等预制采集规则）filebeat.config.modules: path:${path.config}/modules.d/*.yml reload.enabled:false# 生产建议关闭自动重载# ES 索引模板配置setup.template.settings: index.number_of_shards:1# 分片数，生产建议 3-5（根据数据量调整）# Kibana 关联（可视化用）setup.kibana:# hosts: ["kibana:5601"] # 启用时填写 Kibana 地址# 输出目标配置（按需选择）output.elasticsearch: hosts:["localhost:9200"]# ES 集群地址，多节点用逗号分隔preset: balanced# 负载均衡策略# 数据增强处理器processors: - add_host_metadata:# 添加主机元数据（IP/主机名等）when.not.contains.tags: forwarded - add_cloud_metadata: ~# 云环境元数据（AWS/Azure 等）- add_docker_metadata: ~# Docker 容器元数据- add_kubernetes_metadata: ~# K8s 集群元数据

• 关键配置说明

  类型	适用场景	备注
  filestream	通用文件采集（7.16+ 推荐）	替代 log 类型，性能更优
  container	容器日志采集	适配 Docker/K8s 容器日志
  syslog	系统日志	标准 syslog 协议采集
  stdin	标准输入	测试场景用
  tcp/udp	网络日志	采集 TCP/UDP 传输的日志
  winlog	Windows 日志	仅 Windows 环境支持

• 文件采集高级配置

  filebeat.inputs: - type: filestream paths: - /var/log/app/*.log encoding: gbk# 适配中文日志（如 Windows 生成的 gbk 编码文件）exclude_lines:['^DBG']# 过滤调试日志include_lines:['sometext']# 仅保留含指定文本的行recursive_glob.enabled:true# 递归采集子目录日志

2.3、参数说明

• filebeat.inputs：type 所支持的类型

  • 参数

    Azure Event Hub Container 容器 Kafka Log(deprecatedin7.16.0, use filestream)Log(已弃用于7.16.0，请使用 filestream)MQTT Redis Stdin(标准输入)Streaming Syslog(系统日志)TCP UDP Unified Logs(统一日志)Unix winlog(Windows 日志)

• input.file：官方参数说明

  • 参数

    paths： 文件路径 可以使用 recursive_glob.enabled 开启深度 recursive_glob.enabled 开启文件深度查询 单个8级 encoding： 支持编码 普通，latin1，utf-8，utf-16be-bom，utf-16be，utf-16le，big5，gb18030，gbk，hz-gb-2312，euc-kr，euc-jp，iso-2022-jp，shift-jis exclude_lines： 删除匹配的行 如 exclude_lines：['^ DBG']删除以DEG开头的任意行 include_lines： 需要匹配的行 如 include_lines：['^ ERR'，'^ WARN']导出以ERR或开头的任何行WARN 如： 导出所有包含的日志行sometext，但以DBG（调试消息）开头的行 include_lines：['sometext']exclude_lines：['^ DBG']exclude_files： 过滤指定的文件 如 exclude_files：['\ .gz $']# 过滤任何以.gz的文件

三、实战使用示例

3.1、控制台输出

• 配置文件

  # 配置文件：test-console.ymlfilebeat.inputs: - type: stdin enabled:trueoutput.console:# 格式化输出，便于阅读pretty:true# 如果是指定配置文件，使用前 先将systemctl stop filebeatfilebeat -e -c test-console.yml# -e 表示输出到标准错误（控制台）

• 测试

  # 控制台随便搞条日志2025-12-1517:19:43.517[main]WARN[166]- No MyBatis mapper was foundin'[com.yyy.zzz.qqq.qqq]'package. Please check your configuration.# 会按照格式直接原模原样打印出来{"message":"2025-12-15 17:19:43.517 [main] WARN [166] - No MyBatis mapper was found in '[com.yyy.zzz.qqq.qqq]' package. Please check your configuration.","input":{"type":"stdin"},}

3.2、文件输出

• 配置文件 - 输出到控制台

  catfileout-filebeat.yml filebeat.inputs: - type: filestream enabled:truepaths: - /var/log/messages exclude_lines:['^DEBUG|^DBG']exclude_lines:['\.gz$']#output.console:# pretty: trueoutput.file: path:"/tmp/filebeat"# 日志存储目录（需提前创建）filename: filebeat.log# 文件名rotate_every_kb:10240# 每 10MB 轮转一次（扩展配置）number_of_files:5# 保留 5 个轮转文件（扩展配置）

• 测试

  filebeat]# ./filebeat -e -c fileout-filebeat.yml# 会输出成一个文件ls/tmp/filebeat/ messages.log-20251215.ndjson

3.3、重置日志读取偏移量

• 修改registry文件

  # 编辑 Registry 文件 是 --path.data /opt/filebeat/datacd/opt/filebeat/data/registry/filebeatvimlog.json# 找到目标文件的记录，比如 messages，它会有很多行，直接拉到最下面{"k":"filestream::.global::native::73025661-64768","v":{"ttl":-1,"updated":[2062166666919,1765788708],"cursor":{"offset":327021},"meta":{"source":"/var/log/messages","identifier_name":"native"}}}

  字段	含义
  k	唯一标识符，格式为filestream::.global::native::inode-设备号（你的环境中 inode 是 73025661，设备号 64768）
  v.cursor.offset	文件读取偏移量（核心修改字段）
  v.meta.source	日志文件路径（用于定位目标文件）
  op	操作类型（set = 更新记录，无需修改）

• 修改offset

  将"cursor":{"offset":327021}" 改为 "cursor":{"offset":0}

3.4、输出到es

• 配置文件

  [root@node1 filebeat]# cat filebeat.ymlfilebeat.inputs: - type: filestream enabled:truepaths: - /root/tmplog/*.log fields: type:"tp-log"fields_under_root:true# 关键：将 fields 下的字段提升到根层级- type: filestream enabled:truepaths: - /var/log/*.log fields: type:"syslog"fields_under_root:true# 关键：将 fields 下的字段提升到根层级，如果不提升的话 下面分组获取不到 when.equalssetup.kibana: host:"10.4.50.130:5601"#space.id:output.elasticsearch:#hosts: ["localhost:9200"]hosts:["10.4.50.130:9200","10.4.50.139:9200","10.4.50.167:9200"]protocol:"http"username:"elastic"password:"Elastic@123456"indices: - index:"filebeat-tp-log"# 基础别名（无日期）when.equals:# fields:type: "tp-log"type:"tp-log"# 匹配fileds的就给它放到filebeat-tp-log索引中- index:"filebeat-sys-log"when.equals: type:"syslog"- index:"filebeat-other-log"when.not.equals:# 这里是不匹配就给它放到 other-log下面type:["tp-log","syslog"]bulk_max_size:200timeout: 30s max_retries:5

• 验证

  systemctl restart filebeatcurl-u elastic:密码 http://10.4.50.130:9200/_cat/indices greenopen.ds-filebeat-sys-log-2025.12.16-000001 D8qdwGHNSeCWLXQCH_YSDQ318980848.4kb459.8kb459.8kb greenopen.ds-filebeat-tp-log-2025.12.16-000001 ewJn2uSkScqZq4g_EnsvtQ318976240291.4mb145.2mb145.2mb

3.5、输出到kafka

• 编写 Filebeat 配置

  cat>/etc/filebeat/filebeat.yml<<EOF filebeat.inputs: - type: log enabled: true paths: - /var/log/nginx/access.log # Nginx 访问日志 - /var/log/nginx/error.log # Nginx 错误日志 # 自定义字段：便于后续 Logstash/ES 过滤 fields: service: nginx env: prod ip: 192.168.9.32 # 字符编码（适配中文日志） encoding: utf-8 # 仅保留错误日志中的 ERROR/WARN 行 include_lines: ['^ERROR|^WARN'] # 禁用默认模块（避免干扰） filebeat.config.modules: path:${path.config}/modules.d/*.yml reload.enabled: false # 输出到 Kafka output.kafka: hosts: ["192.168.9.31:9092", "192.168.9.32:9092"] # Kafka 集群地址 topic: "nginx-logs-prod" # 自定义 Kafka 主题 partition.round_robin: reachable_only: true # 仅发送到可达的分区 required_acks: 1 # 主分区确认后即认为发送成功 compression: gzip # 启用 gzip 压缩，减少网络传输 compression_level: 4 # 压缩级别（1=最快，9=最优） max_message_bytes: 1048576 # 单消息最大 1MB # 数据增强：添加主机元数据 processors: - add_host_metadata: ~ - add_cloud_metadata: ~ EOF

• 验证配置并重启

  # 验证配置语法filebeattestconfig -c /etc/filebeat/filebeat.yml# 重启 Filebeatsystemctl restart filebeat# 查看运行状态systemctl status filebeat

• 验证 Kafka 数据

  # 进入 Kafka 安装目录，消费主题数据cd/usr/local/kafka/bin ./kafka-console-consumer.sh --bootstrap-server192.168.9.31:9092 --topic nginx-logs-prod --from-beginning

四、参数说明

4.1、索引匹配

• 索引匹配1

  # 如果直接用filelds需要将它提到root级别- type: log# 或- type: filestream fields: type:"tp-log"fields_under_root:trueoutput.elasticsearch: indices: - index:"filebeat-tp-log"when.equals: type:"tp-log"# 不匹配时，会加到这个索引中- index:"filebeat-other-log"when.not.equals: type:["tp-log","syslog"]

• 索引匹配2

  # 匹配生成索引scan_frequency: 5s tags:['thedd']encoding: utf-8 output.elasticsearch: indices: - index:"filebeat-tp-log"when.equals:# <--用这种方式也行type:"thedd"- index:"filebeat-thedddd"when.contains: tags:"thedd"

• 收集debug日志

  logging: level: debug to_files:truefiles: path: /var/log/filebeat name: filebeat-8188.log keepfiles:1permissions: 0644 selectors:["filestream","multiline","publish"][root@node1 filebeat]# tail -f /var/log/filebeat/filebeat-8188.log-20251219-20.ndjson{"log.level":"info","@timestamp":"2025-12-19T18:02:52.882+0800","log.origin":{"function":"github.com/elastic/beats/v7/libbeat/cmd/instance.(*Beat).launch","file.name":"instance/beat.go","file.line":782},"message":"filebeat stopped.","service.name":"filebeat","ecs.version":"1.6.0"}

4.2、Multiline

4.2.1、参数说明

• 核心组合对照表

  组合（negate + match）	核心规则（以 pattern 为基准）	合并方向
  true + after	当前行匹配 pattern → 触发合并；当前行不匹配 → 作为新日志起始行	匹配到 pattern 的行是主行，其他行都跟在主行后面
  false + after	当前行不匹配 pattern → 触发合并；当前行匹配 → 作为新日志起始行	没匹配到 pattern 的行是主行，匹配到的行跟在主行后面
  true + before	当前行匹配 pattern → 触发合并；当前行不匹配 → 作为新日志起始行	几乎不用（日志顺序乱时才用）
  false + before	当前行不匹配 pattern → 触发合并；当前行匹配 → 作为新日志起始行	几乎不用（日志顺序乱时才用）

• 示例一：negate: false + match: after

  • 配置

    filebeat.inputs: - type: filestream enabled:truepaths: - /var/log/app/error.log# 匹配以YYYY-MM-DD日期开头的日志行（适配业务日志格式）multiline.pattern: ^\d{4}-\d{2}-\d{2}# 匹配日期开头的行multiline.negate:falsemultiline.match: after multiline.max_lines:1000# 限制最大合并行数，防止内存溢出multiline.timeout: 5s# 超时未匹配则强制结束合并

  • 效果

    2025-12-16 00:01:04.123[main]WARN[123]-testwarn log some warn detail another warn line# 合并后（变成1条日志）2025-12-16 00:01:04.123[main]WARN[123]-testwarn log some warn detail another warn line

• 示例二：negate: true + match: after（匹配异常）

  • 配置

    filebeat.inputs: - type: filestream enabled:truepaths: - /var/log/app/all.log# 匹配以at开头的异常堆栈行（适配DM数据库异常日志）multiline.pattern: ^at# 匹配at开头的堆栈行multiline.negate:truemultiline.match: after multiline.timeout: 5s# 超时强制结束合并

  • 效果

    # 原始日志2025-12-16 00:01:03.052 ERROR - 网络通信异常 dm.jdbc.driver.DMException: 网络通信异常 at dm.jdbc.driver.DBError.throwException(...)# 合并后（变成1条日志）2025-12-16 00:01:03.052 ERROR - 网络通信异常 dm.jdbc.driver.DMException: 网络通信异常 at dm.jdbc.driver.DBError.throwException(...)

• 其它两种几乎不用，简单说：只有日志行顺序完全反了（比如先出堆栈、后出日期），才用match: before，效果是把乱序的日志还原成正常顺序，日常不用管

4.2.2、示例

• 配置

  # ======================== Filebeat 核心输入配置 ========================# 定义日志输入源的集合filebeat.inputs:# 注释掉filestream类型（新版），改用log类型（旧版对多行日志兼容性更稳定）#- type: filestream# 指定输入类型为log（经典日志采集模式，适配多行日志场景）- type: log# 是否启用该输入源（true=启用，false=禁用）enabled:true# 配置需要采集的日志文件路径，支持通配符；此处采集/root/tmplog目录下所有.log后缀的文件paths: - /root/tmplog/*.log# 可选：自定义字段（当前注释未启用），用于后续ES索引路由/日志分类#fields:# type: "tp-log"#fields_under_root: true # 是否将自定义字段放到日志根节点（而非fields子节点）# 排除指定规则的日志行：匹配"年月日 时分秒.毫秒 [xxx] DEBUG/INFO"开头的行，只采集WARN/ERROR等重要日志exclude_lines:'^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]+ \[.*\] (DEBUG|INFO)'# ======================== 多行日志合并配置 ========================# 多行日志合并类型：基于正则表达式匹配multiline.type: pattern# 匹配日志起始行的正则：以"YYYY-MM-DD HH:MM:SS.xxx"开头的行（日志的首行）multiline.pattern: ^\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}\.\d+# 反转匹配规则：true表示"非匹配pattern的行"（即日志后续行）需要合并multiline.negate:true# 合并方式：after表示"非匹配行"合并到上一个匹配行（日志首行）之后multiline.match: after# 单个多行日志的最大行数限制：防止超大日志撑爆内存，超出则截断multiline.max_lines:500# 多行合并超时时间：10秒内无新行则结束当前多行日志合并multiline.timeout: 10s# ======================== 文件生命周期配置 ========================# 忽略超过72小时未修改的旧文件（不再监控/读取），需与clean_inactive配合ignore_older: 72h# 读取到文件末尾后关闭文件句柄（适用于静态日志文件，避免占用资源）close_eof:true# 清理96小时未访问的文件注册表记录（需大于ignore_older，建议差值24h）clean_inactive: 96h# 文件被删除后，关闭对应的harvester进程并清理注册表close_removed:true# 文件被重命名后，关闭旧文件句柄并重新监控新名称（若匹配paths规则）close_renamed:true# ======================== 基础采集配置 ========================# 扫描日志文件的频率：每5秒检查一次文件是否有新内容scan_frequency: 5s# 自定义标签：用于后续ES索引路由（匹配when.contains.tags: "thedd"）tags:['thedd']# 日志文件编码格式：UTF-8（适配中文日志，避免乱码）encoding: utf-8# 单个文件的最大harvester进程数：1表示单进程读取，避免并发读取冲突harvester_limit:1# 强制关闭文件句柄：即使文件还在写入，也按规则关闭（避免句柄泄漏）force_close_files:true# ======================== Kibana 配置 ========================# 配置Kibana地址，用于导入索引模板/可视化面板（非必填，但建议配置）setup.kibana: host:"10.4.50.130:5601"# Kibana的IP+端口# ======================== Elasticsearch 输出配置 ========================output.elasticsearch:# ES集群节点地址列表，多个节点用逗号分隔（提高可用性）#hosts: ["localhost:9200"] # 本地ES（注释掉，改用集群）hosts:["10.4.50.130:9200","10.4.50.139:9200","10.4.50.167:9200"]# 通信协议：http（若ES开启HTTPS则改为https）protocol:"http"# ES认证用户名（需提前创建有写入权限的用户）username:"elastic"# ES认证密码password:"Elastic@123456"# 索引路由规则：根据日志标签/字段分发到不同ES索引indices:# 当日志包含tags: "thedd"时，写入filebeat-thedddd索引- index:"filebeat-thedddd"when.contains: tags:"thedd"# 批量写入ES的最大条数：200条/批（平衡写入性能和内存）bulk_max_size:200# ES请求超时时间：30秒（避免网络波动导致写入失败）timeout: 30s# 写入失败后的最大重试次数：5次（重试后仍失败则丢弃）max_retries:5

• 说明

  #- type: filestream- type: log# 搞了一天 type换成log 多行日志才合并 也是无奈# 生成个日志cat>/root/tmplog/test-8188.log<<EOF 2025-12-16 00:01:03.052 [Druid-ConnectionPool-Create-24293395] ERROR [2787] - create connection SQLException, url: jdbc:dm://127.0.0.1:5236/doshare?zeroDateTimeBehavior=convertToNull&useUnicode=true&characterEncoding=UTF-8, errorCode 6001, state 08S01 dm.jdbc.driver.DMException: 网络通信异常 at dm.jdbc.driver.DBError.throwException(SourceFile:774) ~[DmJdbcDriver-18_8.1.3.26.jar!/:?] at dm.jdbc.a.a.init(SourceFile:152) ~[DmJdbcDriver-18_8.1.3.26.jar!/:?] 2025-12-16 00:01:04.123 [main] WARN [123] - test warn log some warn detail another warn line EOF

• 先加数据视图，在用analytics-discover查看，看下章添加

五、kibana添加索引

• 左侧找到Manager，进行添加操作，按步骤加
  

• 查看message

  
  

六、其它补充

6.1常见问题

• 日志采集重复
  • 原因：Registry 文件损坏 / 删除，导致 Filebeat 从头读取；
  • 解决：恢复 Registry 备份，或通过filebeat clean registry清理后重新采集（需确认可重复）。
• 日志采集延迟
  • 原因：内存队列过小、批量发送配置不合理；
  • 解决：增加队列大小（queue.mem.events: 4096），调整批量发送参数（output.kafka.bulk_max_size: 500）。
• 配置验证失败
  • 排查命令：filebeat test config -c /etc/filebeat/filebeat.yml，根据报错修复语法（如缩进、字段名错误）。
• 无日志输出
  • 检查 Filebeat 日志：tail -f /var/log/filebeat/filebeat；
  • 确认日志文件权限：Filebeat 进程需有读取日志文件的权限（建议添加 filebeat 用户到日志所属组）；
  • 确认路径正确性：避免通配符错误（如/var/log/*.log漏写星号）。
• 生产环境建议
  1. 配置分层：按业务拆分配置文件（如 filebeat-nginx.yml、filebeat-app.yml），便于管理；
  2. 监控告警：监控 Filebeat 进程状态、Registry 目录大小、输出端（ES/Kafka）写入速率；
  3. 日志轮转：配置 Filebeat 自身日志轮转（/etc/logrotate.d/filebeat），避免日志文件过大；
  4. 版本选择：生产环境优先选择 6.8.x/7.17.x（LTS 版本），避免频繁升级；
  5. 安全加固：ES/Kafka 开启认证，Filebeat 配置加密传输（SSL/TLS）。