创建新的 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

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

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

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

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

此文件夹包含此模块的 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 是模块的控制文件，其中定义了变量并引用了其他文件。它是一个 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/ 文件夹包含生成 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 输入部分中有介绍。

模板文件使用 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/ 文件夹包含 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 中。您可以通过在其 manifest.yml 文件中指定文件集所需的所有管道来告诉 Filebeat 执行此操作。列表中的第一个管道被认为是入口点管道。

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

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

默认情况下，如果 Filebeat 已加载摄取管道，则不会更新它们。如果您想在开发过程中强制更新管道，请使用 ./filebeat setup --pipelines 命令。这会上传管道，即使它们已存在于节点上。

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

在 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 在另一个终端中跟踪它们，这可能很有用。

例如，如果摄取管道中存在语法错误，则测试可能会挂起。filebeat 日志输出将包含来自 elasticsearch 的错误消息。