如何自定义Filebeat配置文件

自定义 Filebeat 配置文件

一 配置文件结构与位置

• 主配置文件通常为：/etc/filebeat/filebeat.yml。目录 /etc/filebeat/ 下还包含示例与模块配置，如 modules.d/（模块启用开关）、filebeat.reference.yml（完整配置参考）、fields.yml（字段定义）。核心配置段包括：filebeat.inputs（输入源）、filebeat.config.modules（模块加载）、output.elasticsearch / output.logstash（输出）、setup.template / setup.kibana（索引模板与 Kibana）、processors（处理器）、logging（日志）。这些段名与目录是 Filebeat 的标准布局，便于拆分与维护配置。

二 最小可用配置模板

• 示例一 输出到 Elasticsearch（开发环境）

  filebeat.inputs:
  - type: log
    enabled: true
    paths:
      - /var/log/*.log
  
  output.elasticsearch:
    hosts: ["localhost:9200"]
    index: "filebeat-%{[agent.version]}-%{+yyyy.MM.dd}"
  
  setup.template.name: "filebeat"
  setup.template.pattern: "filebeat-*"
  setup.ilm.enabled: false
  

• 示例二 输出到 Logstash（生产常用）

  filebeat.inputs:
  - type: log
    enabled: true
    paths:
      - /var/log/*.log
  
  output.logstash:
    hosts: ["192.168.10.28:5044"]
  
  filebeat.config.modules:
    path: ${path.config}/modules.d/*.yml
    reload.enabled: false
  

• 要点说明：
  • 使用 index: “filebeat-%{[agent.version]}-%{+yyyy.MM.dd}” 可按版本与日期滚动索引；若使用自有模板，可关闭 setup.ilm.enabled 并自定义 setup.template。
  • 通过 filebeat.config.modules 加载 modules.d/*.yml，便于按模块（如 nginx、system）管理配置。

三 常用自定义场景与关键参数

• 仅采集包含指定内容：使用 include_lines（如仅 404）

  filebeat.inputs:
  - type: log
    enabled: true
    paths:
      - /var/log/nginx/access.log
    include_lines: ["404"]
  

• 按条件丢弃或仅采集：使用 exclude_lines / include_lines 组合实现黑白名单过滤。
• JSON 日志解析到顶层字段：使用 json.keys_under_root: true、json.overwrite_keys: true

  - type: log
    enabled: true
    paths:
      - /var/log/nginx/access_json.log
    json.keys_under_root: true
    json.overwrite_keys: true
  

• 为不同日志打标签并写入不同索引：使用 fields / fields_under_root

  - type: log
    enabled: true
    paths:
      - /var/log/nginx/access_json.log
    fields:
      log_type: "access"
    fields_under_root: true
  - type: log
    enabled: true
    paths:
      - /var/log/nginx/error.log
    fields:
      log_type: "error"
    fields_under_root: true
  
  output.elasticsearch:
    hosts: ["localhost:9200"]
    index: "nginx-%{[log_type]}-%{+yyyy.MM.dd}"
  

• 元数据增强：使用 processors 添加主机、云、容器、Kubernetes 元数据

  processors:
    - add_host_metadata:
        when.not.contains.tags: forwarded
    - add_cloud_metadata: ~
    - add_docker_metadata: ~
    - add_kubernetes_metadata: ~
  

• 索引模板与 ILM：通过 setup.template.name / pattern 自定义模板；需要自定义生命周期管理时，可关闭 setup.ilm.enabled 并自行管理 ILM 策略。

四 校验与应用配置

• 语法与输出连通性校验

  sudo filebeat test config
  sudo filebeat test output
  

• 前台试运行（前台输出便于排查）

  sudo filebeat -e -c /etc/filebeat/filebeat.yml
  

• 重载或重启服务
  • 使用 systemd 管理的系统：

    sudo systemctl restart filebeat
    sudo systemctl status filebeat
    sudo journalctl -u filebeat -f
    

  • 使用 SysVinit 的系统：

    sudo service filebeat restart
    sudo service filebeat status
    

• 首次接入 Elasticsearch/Kibana 时，可先执行 filebeat setup 初始化索引模板与仪表板（按需）。

五 排错与最佳实践

• 权限与路径：确保运行 Filebeat 的用户对日志路径（如 /var/log/）具备读取权限；必要时使用 sudo 或调整文件权限/属主。
• YAML 语法：仅使用空格缩进、键值间保留一个空格、布尔值为 true/false（区分大小写），避免 Tab 与语法错误导致解析失败。
• 配置分段与复用：将复杂配置拆分为多个文件（如自定义 inputs、processors），通过 filebeat.config.modules.path 与 modules.d/ 管理模块，保持主配置简洁。
• 调试顺序：先 test config → 再 -e 前台运行 → 查看 journalctl 或 Filebeat 自身日志 → 最后切回后台服务。
• 版本与索引命名：在索引名中嵌入 %{[agent.version]} 可避免跨版本索引结构不一致带来的问题。