如何配置Filebeat的输入插件

配置 Filebeat 输入插件

要让Filebeat高效地采集数据，第一步就是正确配置输入插件。这就像给数据采集器装上合适的“探头”，不同的数据源需要不同的探头。下面，咱们就来拆解一下配置的核心要点。

一 配置结构与通用字段

Filebeat的输入配置，其骨架非常清晰。所有输入定义都放在 filebeat.inputs 这个数组下面，你可以同时配置多个输入源，互不干扰。每个输入都以 - type: <类型> 开头，常见的类型包括 filestream（处理文件，目前最推荐）、log（旧版文件输入，已不推荐）、stdin、tcp 以及 container（专门处理容器日志）。

无论选择哪种类型，有几个通用字段是绝大多数场景下都会用到的：

• enabled: 这个开关控制是否启用该输入，默认是开启的（true）。
• tags: 可以给采集到的事件打上标签，方便后续筛选和分类，比如 [“prod”, “web”]。
• fields: 用于添加自定义字段，这些字段默认会嵌套在事件的 fields 对象下。
• fields_under_root: 如果设为 true，上面自定义的字段就会被提升到事件的顶级，和系统自带字段平起平坐，查询起来更方便。
• processors: 这是事件处理链，可以在数据发送前进行加工，比如丢弃特定事件（drop_event）、删除字段（drop_fields）、重命名（rename）或转换类型（convert）等。

一个典型的配置骨架长这样：

filebeat.inputs:
- type: filestream
  paths:
    - /var/log/*.log
  fields:
    app: nginx
  fields_under_root: true
  tags: [“prod”, “web”]
  processors:
    - add_fields:
        fields:
          env: prod

二 常用输入类型与关键选项

选对输入类型，事情就成功了一半。下面看看几种主流的选择。

• 文件类输入
  • 推荐 filestream：这是目前处理文件日志的首选，功能强大且性能好。其关键选项包括：
    • paths: 指定文件路径，支持 glob 模式。比如 /var/log/*.log 匹配单层目录，而 /data/**/*.log 则可以递归匹配所有子目录下的日志文件。
    • parsers: 内置了解析器，可以直接处理多行日志（multiline）、NDJSON格式（ndjson）和容器日志格式（container）。
    一个配置示例如下：

    filebeat.inputs:
    - type: filestream
      paths: [“/var/log/app/*.log”]
      parsers:
        - multiline:
            type: count
            count_lines: 3
        - ndjson:
            add_error_key: true
            overwrite_keys: true
            target: json_fields
    

  • 旧版 log：这个类型虽然还能用，但官方已不推荐，建议新项目直接使用 filestream。
• 标准输入与 TCP 输入
  • stdin：主要用于调试，或者从管道接收数据，配置极其简单。

    filebeat.inputs:
    - type: stdin
    

  • tcp：用于接收通过网络TCP协议发送过来的日志流，适合接收其他应用直接推送的日志。
    • 关键选项：host（监听地址和端口，如 0.0.0.0:9000）、max_message_size（单条消息最大尺寸，如 10MiB）。

    filebeat.inputs:
    - type: tcp
      host: “0.0.0.0:9000”
      max_message_size: 10MiB
    

• 容器日志输入
  • container：专门为容器环境设计，能自动解析常见的容器日志格式，提取时间戳等信息。
    • 关键选项：paths，通常指向Docker或容器运行时存放日志的目录，例如 /data/docker/containers/*/*.log。

    filebeat.inputs:
    - type: container
      paths: [“/data/docker/containers/*/*.log”]
    

• 重要提示
  • 请注意，docker 这个输入类型从 7.2.0 版本起就已经被废弃了，现在统一使用 container 类型。

三 行过滤与 JSON 解析

数据采集进来，往往还需要“精加工”。行过滤和JSON解析就是两个最常用的工具。

• 行过滤
  • include_lines: 只采集匹配指定正则表达式的行。比如只收集错误和警告日志：[‘^ERR’, ‘^WARN’]。
  • exclude_lines: 排除匹配指定正则表达式的行。比如忽略调试日志：[‘^DBG’]。
  • exclude_files: 直接忽略匹配正则表达式的整个文件。比如不处理压缩文件：[‘.gz$’]。
  • 执行顺序：需要留意的是，如果同时设置了 include 和 exclude，Filebeat 会先执行 include_lines，再对匹配到的行执行 exclude_lines。
• JSON 解析
  • 对于文件或容器日志中已经是JSON格式的 message 字段，可以将其自动解析成结构化的字段。关键选项有：
    • json.keys_under_root: 如果设为 true，解析出来的键会直接放到事件的顶级。
    • json.add_error_key: 解析失败时，会添加一个 error 字段记录问题。
    • json.overwrite_keys: 当解析出的键与事件原有的顶级字段（如 @timestamp）冲突时，是否覆盖原字段。
    • json.target: 将整个解析结果放入指定的字段下，而不是分散到顶级。
    一个将JSON日志解析到独立字段的示例如下：

    filebeat.inputs:
    - type: filestream
      paths: [“/var/log/app/*.json”]
      parsers:
        - ndjson:
            add_error_key: true
            overwrite_keys: true
            target: json_data
            json.keys_under_root: false
    

四 多行日志与容器场景

处理复杂日志格式是实际运维中的常见挑战，这里有两个典型场景的应对策略。

• 多行日志
  • 像Ja va异常堆栈这种跨越多行的日志，需要合并成一个完整事件。使用 filestream.parsers.multiline 可以轻松搞定，常见策略有两种：
    • 按固定行数聚合：比如无论内容，总是将5行合并为一个事件。

      filebeat.inputs:
      - type: filestream
        paths: [“/var/log/app/stack.log”]
        parsers:
          - multiline:
              type: count
              count_lines: 5
      

    • 按正则模式合并：更智能的方式。例如，以下配置将以 “Caused by:” 开头的行视为一个新事件的开始，并将其之前的行合并。

      filebeat.inputs:
      - type: filestream
        paths: [“/var/log/app/stack.log”]
        parsers:
          - multiline:
              pattern: ‘^Caused by:’
              negate: true
              match: after
      

• 容器日志
  • 直接使用 container 输入类型，并指定到容器日志的存储路径（例如 /data/docker/containers/*/*.log）即可。Filebeat 会自动识别常见的日志格式，并提取出有效的时间戳等信息。
  • 如果之前在使用旧的 docker 类型，建议尽快迁移到 container 类型。

五 调试与运行

配置写好了，怎么验证它是否按预期工作呢？这里有几个快速验证和调试的方法。

• 快速验证
  • 控制台输出：在配置文件中将输出设置为控制台，并美化格式，可以直观地看到采集到的事件结构。

    output.console:
      pretty: true
    

  • 启动命令：
    • 前台调试模式启动：filebeat -e -c filebeat.yml
    • 指定自定义配置文件目录启动：filebeat -e -c config/your.yaml
• 运行示例
  • TCP 输入测试：
    1. 启动配置了 type: tcp, host: “0.0.0.0:9000” 的 Filebeat。
    2. 另开一个终端，发送测试数据：echo ‘hello filebeat’ | nc 127.0.0.1 9000
    3. 观察 Filebeat 控制台的输出，应该能看到接收到的事件。
  • 文件输入测试：
    1. 启动配置了 type: filestream, paths: [“/tmp/test/*.log”] 的 Filebeat。
    2. 向目标文件写入日志：echo ‘{“level”:“info”,“msg”:“start”}’ > /tmp/test/a.log
    3. 观察 Filebeat 控制台，确认日志被正确采集并解析。