创建新的 Filebeat 模块

本指南将引导您完成创建新的 Filebeat 模块的过程。

目前，所有 Filebeat 模块都位于主 Beats 存储库中。要克隆存储库并构建 Filebeat（您需要它进行测试），请按照 为 Beats 做贡献 中的一般说明操作。

概述编辑

每个 Filebeat 模块都由一个或多个“文件集”组成。我们通常会为每个支持的服务创建一个模块（例如，nginx 代表 Nginx，mysql 代表 Mysql）以及一个文件集，用于服务创建的每种类型的日志。例如，Nginx 模块具有 access 和 error 文件集。您可以贡献一个新的模块（至少有一个文件集）或为现有模块贡献一个新的文件集。

创建新的模块编辑

在 filebeat 文件夹中运行以下命令

make create-module MODULE={module}

运行 make create-module 命令后，您将在 module/{module} 下找到该模块及其生成的

module/{module}
├── module.yml
└── _meta
    └── docs.asciidoc
    └── fields.yml
    └── kibana

让我们逐个查看这些文件。

module.yml编辑

此文件包含模块可用的所有仪表板的列表，由 export_dashboards.go 脚本用于导出仪表板。每个仪表板都通过 id 和存储仪表板的本地 json 文件的名称来定义。在生成新的文件集时，此文件将使用新文件集的“默认”仪表板设置自动更新。请确保这些设置正确。

_meta/docs.asciidoc编辑

此文件包含特定于模块的文档。您应该包含有关测试了哪些版本的服务的以及在每个文件集中定义的变量的信息。

_meta/fields.yml编辑

模块级 fields.yml 包含模块级字段的描述。请查看并更新此文件中的标题和描述。标题用作文档中的标题，因此最好将其大写。

_meta/kibana编辑

此文件夹包含此模块的示例 Kibana 仪表板。要创建它们，您可以在 Kibana 中以可视化方式构建它们，然后使用 export_dashboards 导出它们。

该工具将自动导出所有仪表板依赖项（可视化、保存的搜索）。

您可以在 导出新的和修改后的 Beat 仪表板 中看到使用 export_dashboards 的各种方法。建议的方法是将您的仪表板列在模块的 module.yml 文件中

dashboards:
- id: 69f5ae20-eb02-11e7-8f04-beef1daadb05
  file: mymodule-overview.json
- id: c0a7ce90-cafe-4242-8647-534bb4c21040
  file: mymodule-errors.json

然后，像这样运行 export_dashboards

$ cd dev-tools/cmd/dashboards
$ make # if export_dashboard is not built yet
$ ./export_dashboards -yml '../../../filebeat/module/{module}/module.yml'

新的 Filebeat 模块可能与 Kibana 5.x 不兼容。要导出与 5.x 兼容的仪表板，请在开发者虚拟环境中运行以下命令

$ cd filebeat
$ make python-env
$ cd module/{module}/
$ python ../../../dev-tools/export_5x_dashboards.py --regex {module} --dir _meta/kibana/5.x

其中，--regex 参数应与您要导出的仪表板匹配。

请注意，从 Kibana 5.x 导出的仪表板与 Kibana 6.x 不兼容。

您可以通过阅读 本指南 了解有关创建和导出 Kibana 仪表板流程的更多详细信息。

创建新的文件集编辑

在 filebeat 文件夹中运行以下命令

make create-fileset MODULE={module} FILESET={fileset}

运行 make create-fileset 命令后，您将在 module/{module}/{fileset} 下找到该文件集及其生成的

module/{module}/{fileset}
├── manifest.yml
├── config
│   └── {fileset}.yml
├── ingest
│   └── pipeline.json
├── _meta
│   └── fields.yml
│   └── kibana
│       └── default
└── test

让我们逐个查看这些文件。

manifest.yml编辑

manifest.yml 是模块的控制文件，用于定义变量并引用其他文件。它是一个 YAML 文件，但在文件的许多地方，您可以使用内置变量或定义的变量，使用 {{.variable}} 语法。

该文件中的 var 部分定义了文件集变量及其默认值。模块变量可以在其他配置文件中引用，并且可以在运行时通过 Filebeat 配置覆盖其值。

作为文件集创建者，您可以为定义的变量使用任何名称。每个变量都必须具有默认值。因此，在最简单的形式中，您可以这样定义新的变量

var:
  - name: pipeline
    default: with_plugins

大多数文件集都应该定义一个名为 paths 的变量，用于设置日志文件所在位置的默认路径

var:
  - name: paths
    default:
      - /example/test.log*
    os.darwin:
      - /usr/local/example/test.log*
      - /example/test.log*
    os.windows:
      - c:/programdata/example/logs/test.log*

此文件中有很多内容，让我们分解一下

除了变量定义外，manifest.yml 文件还包含对要使用的摄取管道和输入配置的引用（请参阅下一部分）

ingest_pipeline: ingest/pipeline.json
input: config/testfileset.yml

这些应该指向文件集中的相应文件。

请注意，在评估这些文件的内容时，将扩展变量，这使您可以根据变量的值选择一个文件或另一个文件。例如

ingest_pipeline: ingest/{{.pipeline}}.json

此示例根据 pipeline 变量的值选择摄取管道文件。对于前面显示的 pipeline 变量，路径将解析为 ingest/with_plugins.json（假设在运行时没有覆盖变量值）。

在 6.6 及更高版本中，您可以指定多个摄取管道。

ingest_pipeline:
  - ingest/main.json
  - ingest/plain_logs.json
  - ingest/json_logs.json

当指定多个摄取管道时，列表中的第一个管道被认为是入口管道。

使用多个管道的其中一个原因可能是将此文件集收集到的所有日志发送到入口管道，并让它将处理的不同部分委派给其他管道。您可以在 ingest/*.json 部分 中了解有关设置此操作的详细信息。

config/*.yml编辑

config/ 文件夹包含生成 Filebeat 输入配置的模板文件。Filebeat 输入主要负责跟踪文件、筛选和多行拼接，因此您将在模板文件中配置这些内容。

一个典型的示例如下所示

type: log
paths:
{{ range $i, $path := .paths }}
 - {{$path}}
{{ end }}
exclude_files: [".gz$"]

您将在运行 make create-fileset 时自动生成的模板文件中找到此示例。在此示例中，paths 变量用于构造输入 paths 选项的 paths 列表。

您添加到 config/ 文件夹中的任何模板文件都需要以 YAML 格式生成有效的 Filebeat 输入配置。Filebeat 输入配置接受的选项在 Filebeat 文档的 Filebeat 输入 部分中有记录。

模板文件使用由 Go 标准库 定义的模板语言。

以下是另一个也配置多行拼接的示例

type: log
paths:
{{ range $i, $path := .paths }}
 - {{$path}}
{{ end }}
exclude_files: [".gz$"]
multiline:
  pattern: "^# User@Host: "
  negate: true
  match: after

尽管您可以在 config/ 文件夹下添加多个配置文件，但只会加载由 manifest.yml 文件指示的文件。您可以使用变量在配置之间动态切换。

ingest/*.json编辑

ingest/ 文件夹包含 Elasticsearch 摄取管道 配置。摄取管道负责解析日志行并在数据上执行其他操作。

此文件夹中的文件是 JSON 或 YAML 文档，代表 管道定义。与 config/ 文件夹一样，您可以定义多个管道，但根据 manifest.yml 中的信息，在运行时只会加载一个管道。

生成器会创建一个类似于以下内容的 JSON 对象

{
  "description": "Pipeline for parsing {module} {fileset} logs",
  "processors": [
    ],
  "on_failure" : [{
    "set" : {
      "field" : "error.message",
      "value" : "{{ _ingest.on_failure_message }}"
    }
  }]
}

或者，您可以使用 YAML 格式的管道，它使用更简单的语法

description: "Pipeline for parsing {module} {fileset} logs"
processors:
on_failure:
 - set:
     field: error.message
     value: "{{ _ingest.on_failure_message }}"

从这里开始，您通常会在 processors 数组中添加处理器来执行实际解析操作。有关可用摄取处理器的信息，请参阅 处理器参考文档。尤其是，您可能会发现 grok 处理器 对解析非常有用。以下是解析 Nginx 访问日志的示例。

{
  "grok": {
    "field": "message",
    "patterns":[
      "%{IPORHOST:nginx.access.remote_ip} - %{DATA:nginx.access.user_name} \\[%{HTTPDATE:nginx.access.time}\\] \"%{WORD:nginx.access.method} %{DATA:nginx.access.url} HTTP/%{NUMBER:nginx.access.http_version}\" %{NUMBER:nginx.access.response_code} %{NUMBER:nginx.access.body_sent.bytes} \"%{DATA:nginx.access.referrer}\" \"%{DATA:nginx.access.agent}\""
      ],
    "ignore_missing": true
  }
}

请注意，您应该遵循使用模块和文件集名称作为前缀的字段命名约定：{module}.{fileset}.field，例如 nginx.access.remote_ip。此外，请查看我们的 命名约定。

在 6.6 及更高版本中，摄取管道可以使用 pipeline 处理器 将部分处理委托给其他管道。

如果您希望文件集以不同的格式（例如，相同日志文件的 csv 版本和 json 版本）摄取相同逻辑信息，这会非常有用。想象一下一个入口摄取管道，它检测日志条目的格式，然后根据格式有条件地将该日志条目的进一步处理委托给另一个管道。

{
  "processors": [
    {
      "grok": {
        "field": "message",
        "patterns": [
          "^%{CHAR:first_char}"
        ],
        "pattern_definitions": {
          "CHAR": "."
        }
      }
    },
    {
      "pipeline": {
        "if": "ctx.first_char == '{'",
        "name": "{< IngestPipeline "json-log-processing-pipeline" >}" 
      }
    },
    {
      "pipeline": {
        "if": "ctx.first_char != '{'",
        "name": "{< IngestPipeline "plain-log-processing-pipeline" >}"
      }
    }
  ]
}

为了使上述管道正常工作，Filebeat 必须将入口点管道以及任何子管道加载到 Elasticsearch 中。您可以在 Filebeat 的 manifest.yml 文件中指定文件集所需的所有管道，从而告诉 Filebeat 执行此操作。列表中的第一个管道被认为是入口点管道。

ingest_pipeline:
  - ingest/main.json
  - ingest/plain_logs.yml
  - ingest/json_logs.json

在开发管道定义时，我们建议使用 模拟管道 API 进行测试和快速迭代。

默认情况下，Filebeat 不会更新已加载的 Ingest 管道。如果要在开发过程中强制更新管道，请使用 ./filebeat setup --pipelines 命令。即使管道已存在于节点上，此命令也会上传管道。

_meta/fields.ymledit

fields.yml 文件包含文件集中字段的顶级结构。它用作以下内容的真实来源：

除了文件集中的 fields.yml 文件之外，在模块级别还有一个 fields.yml 文件，位于 module/{module}/_meta/fields.yml 下，该文件应包含在模块级别定义的字段以及模块本身的描述。在大多数情况下，您应该在文件集级别添加字段。

在创建 pipeline.json 后，可以生成一个基本 field.yml。

make create-fields MODULE={module} FILESET={fileset}

请始终检查生成的文件，并确保字段正确。您必须手动添加字段文档。

如果字段正确，则可以生成文档、配置和 Kibana 索引模式。

make update

testedit

在 test/ 目录中，您应该放置由服务生成的示例日志文件。我们有集成测试，由 CI 自动执行，这些测试将在 test/ 文件夹下的每个日志文件上运行 Filebeat，并检查是否存在解析错误以及所有字段是否都有文档记录。

此外，假设您有一个 test.log 文件，您可以在同一目录中添加一个 test.log-expected.json 文件，其中包含通过 Elasticsearch 搜索找到的预期文档。在这种情况下，集成测试将自动检查每次运行的结果是否相同。

为了使用示例日志测试文件集或生成预期输出，应在 Filebeat 目录下使用以下过程针对特定模块在本地运行测试

Filebeat 日志被写入 build 目录。在另一个终端中使用 tail -F build/system-tests/run/test_modules.Test.*/output.log 尾随它们可能很有用。

例如，如果 ingest 管道中存在语法错误，测试可能会一直挂起。Filebeat 日志输出将包含来自 Elasticsearch 的错误消息。