创建新的 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 输入 部分中。

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

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

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

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

_meta/fields.yml编辑

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 的错误消息。