如何自定义Filebeat日志格式

Filebeat日志格式自定义指南

一 概念澄清

在动手配置之前，先得把两个容易混淆的概念理清楚：

• Filebeat自身运行日志：这指的是Filebeat这个“搬运工”自己工作时产生的日志，比如它有没有正常启动、遇到了什么错误。这类日志通常输出到磁盘文件或控制台，方便运维人员排错。你可以选择让它以纯文本（plain）或结构化（json）的格式呈现，并且能配置日志轮转和保留策略。
• 被采集的业务日志内容：这才是Filebeat从你的应用日志文件或数据流中“搬运”出来的原始内容。我们的核心任务，就是通过一系列处理手段，比如解析、重组、添加信息，来控制这些内容最终进入Elasticsearch或Logstash时的样子。

二 自定义Filebeat自身运行日志格式

想让Filebeat“汇报工作”的日志更符合你的口味？配置起来并不复杂，关键在于修改filebeat.yml配置文件中的logging部分。

• 在这里，你可以选择输出格式是plain还是json。如果后续打算用日志分析工具自动处理，JSON格式会是更明智的选择。同时，别忘了设置好日志的存放路径、保留天数以及文件权限。
• 下面是一个配置为JSON格式的示例，结构清晰，便于机器解析：

logging:
  level: info
  to_files: true
  files:
    path: /var/log/filebeat
    name: filebeat.log
    keepfiles: 7
    permissions: 0640
    format: json

• 配置完成后，当然要验证一下效果：
  • 重启服务：在Linux系统上，执行 sudo systemctl restart filebeat。
  • 查看日志：运行 sudo tail -f /var/log/filebeat/filebeat.log，看看输出格式是否已切换。
  • 对于Windows环境，通过“服务”管理器重启Filebeat服务，然后检查其安装目录下新生成的日志文件即可。

三 自定义被采集日志的事件结构与内容

这才是重头戏。我们采集日志的最终目的，是为了更好地分析和利用它们。通过以下几步，你可以把杂乱的原始日志，变成结构清晰、信息丰富的“数据资产”。

• 添加元数据字段：给日志事件打上标签，比如来自哪个环境、哪个应用，后续筛选会非常方便。你可以选择让这些字段放在事件的根层级，或者归到一个命名空间下。

filebeat.inputs:
- type: log
  enabled: true
  paths:
    - /var/log/*.log
  fields:
    env: prod
    app: order-service
  fields_under_root: false # 设为 true 时，fields 将提升到事件根层级

• 解析与重构日志内容：面对一行包含多种信息的日志消息（message），用dissect或grok处理器可以像“拆积木”一样把它精准拆开。拆解之后，你还可以转换字段类型，甚至丢弃不必要的原始字段。

processors:
  - dissect:
      tokenizer: "[%{timestamp}] -%{parentTraceId} -%{traceId} -%{host} -%{port} -%{appName} -%{pid} -[%{level}] -[%{thread}] -%{class} -%{line} - %{message}"
      field: "message"
      target_prefix: ""
  - convert:
      fields:
        - {from: timestamp, to: "@timestamp", type: date, formats: ["yyyy-MM-dd HH:mm:ss.SSS"]}
  - drop_fields:
      fields: ["message", "timestamp"] # 解析后可删除原始字段

• 多行日志合并：Ja va异常堆栈这类跨越多行的日志，如果不做处理，会被拆成多个独立事件，导致信息碎片化。用multiline解析器可以把它们正确地“缝合”起来。

filebeat.inputs:
- type: filestream
  enabled: true
  paths:
    - /var/log/app/*.log
  parsers:
    - multiline:
        type: pattern
        pattern: '^\['
        negate: true
        match: after

• 控制输出目标：发送到Elasticsearch时，你可以自定义索引名称的格式，甚至根据需要调整索引模板的映射规则。

output.elasticsearch:
  hosts: ["localhost:9200"]
  index: "filebeat-%{[agent.version]}-%{+yyyy.MM.dd}"
  # 如需自定义模板可在 setup.template 下调整

• 应用与验证：配置完成后，老规矩，重启Filebeat服务（sudo systemctl restart filebeat）。然后，去Elasticsearch里检索一下数据（curl -X GET "localhost:9200/filebeat-*/_search?pretty"），亲眼确认日志结构是否已按你的设想完美呈现。

四 常见问题与排查

配置过程中踩坑在所难免，这里有几个高频问题的排查思路：

• 缩进与语法：YAML格式对缩进极其敏感，一个空格不对都可能让配置失效。动手前，先用filebeat test config -c filebeat.yml命令校验一下配置文件，能省去很多麻烦。
• 多行合并不生效：首先确认multiline配置是否放在了正确的输入类型（比如filestream的parsers下）。其次，检查pattern是否准确匹配了你日志中每一段“多行事件”的首行特征。
• 字段覆盖与类型：使用convert处理器可以稳妥地转换时间和数值字段的类型。需要警惕的是，避免无意中用自定义字段覆盖了系统关键字段，比如@timestamp。
• 自身日志看不到：如果配置了但找不到Filebeat自己的日志文件，请检查logging.to_files是否设为true，以及path和permissions设置是否正确。临时将日志级别level调为debug，也能帮你看到更详细的启动过程。