如何自定义Filebeat日志输出格式

Filebeat日志输出格式自定义指南

一 概念澄清

• Filebeat自身运行日志：指 Filebeat 进程内部打印的日志（如启动、连接、发布事件等），可配置为文本或JSON两种格式，便于人读或机器解析。
• 被采集并输出的业务日志事件：指 Filebeat 从文件/容器等采集到的日志内容，其“输出格式”取决于你选择的输出插件（如 Elasticsearch、Logstash、Kafka、File、Console），可通过模板、索引名、codec 等方式自定义。

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

• 在配置文件的 logging 段设置输出到文件与格式，常用选项：
  • level：日志级别（debug/info/warn/error）
  • to_files：是否写入文件
  • files.path / name：日志目录与文件名
  • keepfiles / permissions / rotateeverybytes：保留文件数、权限、单个文件大小
  • format / json：日志格式；设置 format: json 或 logging.json: true 输出为 JSON
  • 其他：如 to_syslog / to_eventlog 可改为输出到 syslog 或 Windows 事件日志
• 示例（文本与 JSON 二选一）：

# 文本格式（默认）
logging:
  level: info
  to_files: true
  files:
    path: /var/log/filebeat
    name: filebeat.log
    keepfiles: 7
    permissions: 0644
    rotateeverybytes: 10485760

# JSON 格式（机器可解析）
logging:
  level: info
  to_files: true
  format: json
  files:
    path: /var/log/filebeat
    name: filebeat.log
    keepfiles: 7
    permissions: 0644

• 使配置生效：
  • Linux：sudo systemctl restart filebeat
  • Windows：在服务管理器中重启 Filebeat 服务
• 验证：tail -f /var/log/filebeat/filebeat 或 filebeat.log，观察是否为 JSON 或文本格式。

三 自定义业务日志事件的输出格式

• 控制台输出（便于调试）
  • 直接输出事件为 JSON；开启 pretty: true 更易读

output.console:
  pretty: true

• 文件输出（落盘为自定义格式）
  • 指定路径、文件名、滚动策略；事件仍以 JSON 写入（如需特定文本格式，建议在下游处理）

output.file:
  path: "/tmp/filebeat"
  filename: events
  rotate_every_kb: 10000
  number_of_files: 7
  permissions: 0600

• Elasticsearch 输出（控制索引名与模板）
  • 通过 index 模板自定义索引命名；如需完全自定义文档内容，建议在 Logstash 或 processors 中处理

output.elasticsearch:
  hosts: ["http://es-node:9200"]
  index: "app-logs-%{+yyyy.MM.dd}"
  # 如需禁用 ILM 并使用自定义模板
  setup.ilm.enabled: false
  setup.template.name: "app-template"
  setup.template.pattern: "app-*"
  setup.template.overwrite: true
  setup.template.settings:
    index.number_of_shards: 3
    index.number_of_replicas: 0

• Logstash 输出（交给 Logstash 做最终渲染）
  • 将事件以 JSON 发送到 Logstash，由 Logstash 的 filter/output 决定最终格式

output.logstash:
  hosts: ["logstash:5044"]

• Kafka 输出（自定义消息体）
  • 使用 codec.format 按字符串模板拼装输出（适合需要特定文本/JSON 结构的场景）

output.kafka:
  enabled: true
  hosts: ["kafka1:9092","kafka2:9092"]
  topic: app-logs
  codec.format:
    string: '{"@timestamp":"%{[@timestamp]}","host":"%{[host.name]}","service":"%{[fields.service]}","msg":"%{[message]}"}'

• 事件字段层面的自定义（配合任何输出）
  • 使用 processors 增删改字段，控制最终输出结构

processors:
  - add_fields:
      fields:
        env: prod
        team: backend
  - mutate:
      remove_field: ["agent.ephemeral_id", "input.type"]

• 多类型日志分流示例（按标签写入不同索引）

filebeat.inputs:
- type: log
  paths:
    - /var/log/nginx/access.log
  tags: ["access"]
  fields:
    log_type: nginx_access

- type: log
  paths:
    - /var/log/nginx/error.log
  tags: ["error"]
  fields:
    log_type: nginx_error

output.elasticsearch:
  hosts: ["http://es:9200"]
  indices:
    - index: "nginx-access-%{+yyyy.MM.dd}"
      when.contains:
        tags: "access"
    - index: "nginx-error-%{+yyyy.MM.dd}"
      when.contains:
        tags: "error"
  setup.ilm.enabled: false
  setup.template.name: "nginx-template"
  setup.template.pattern: "nginx-*"
  setup.template.overwrite: true

• 验证
  • 控制台/文件：直接观察输出是否符合预期
  • ES：检查索引文档字段与内容（如 _cat/indices、_search）
  • Kafka：用消费者查看消息体是否符合模板

四 常见问题与排查

• 修改配置后未生效：确认已重启 Filebeat；检查 YAML 缩进与语法；查看 Filebeat 自身日志是否有报错（/var/log/filebeat/filebeat 或 Windows 事件日志）。
• 想要完全自定义文本格式：优先选择 output.console 或 output.file 配合模板；若写入 Elasticsearch，建议在 Logstash 或 processors 中完成结构化与渲染。
• 索引未按预期生成：核对 index 模板与日期格式（如 %{+yyyy.MM.dd}），以及 ILM 是否关闭（setup.ilm.enabled: false）。