跳到主要内容

Grok 处理器

从文档中的单个文本字段提取结构化字段。你可以选择从哪个字段提取匹配的字段,以及你期望匹配的 grok 模式。grok 模式类似于支持可复用别名的正则表达式。

该处理器内置了大量可复用模式。

如果你需要构建用于匹配日志的模式,Grok Debugger 工具非常有用!Grok Constructor 也是一个有用的工具。

在管道中使用 Grok 处理器​

参数必填默认值描述
field是-用于 grok 表达式解析的字段。
patterns是-一组有序的 grok 表达式,用于匹配并提取命名捕获组。返回列表中第一个匹配的表达式即停止。
pattern_definitions否-一个模式名与模式组成的映射,定义当前处理器使用的自定义模式。与现有名称匹配的模式将覆盖原有定义。
ecs_compatibility否disabled必须为 disabled 或 v1。若为 v1,处理器使用带有 Elastic Common Schema (ECS) 字段名称的模式。
trace_match否false为 true 时,_ingest._grok_match_index 会被插入到匹配文档的元数据中,表示 patterns 列表中匹配成功的模式的索引。
ignore_missing否false为 true 且 field 不存在或为 null 时,处理器静默退出且不修改文档。
description否-处理器的描述。有助于说明该处理器或其配置的用途。
if否-有条件地执行处理器。参阅有条件地运行处理器。
ignore_failure否false忽略处理器的失败。参阅处理管道失败。
on_failure否-处理器的失败处理。参阅处理管道失败。
tag否-处理器的标识符。有助于调试和指标统计。

以下示例使用内置模式,从文档的字符串字段中提取并命名结构化字段。

POST _ingest/pipeline/_simulate
{
"pipeline": {
"description": "...",
"processors": [
{
"grok": {
"field": "message",
"patterns": ["%{IP:client} %{WORD:method} %{URIPATHPARAM:request} %{NUMBER:bytes:int} %{NUMBER:duration:double}"]
}
}
]
},
"docs": [
{
"_source": {
"message": "55.3.244.1 GET /index.html 15824 0.043"
}
}
]
}

该管道会在文档中插入这些命名捕获组作为新字段,结果如下:

{
"docs": [
{
"doc": {
"_index": "_index",
"_id": "_id",
"_version": "-3",
"_source": {
"duration": 0.043,
"request": "/index.html",
"method": "GET",
"bytes": 15824,
"client": "55.3.244.1",
"message": "55.3.244.1 GET /index.html 15824 0.043"
},
"_ingest": {
"timestamp": "2016-11-08T19:43:03.850+0000"
}
}
}
]
}

自定义模式​

Grok 处理器自带一组基础模式。这些模式不一定总能满足你的需求。模式的格式非常简单:每个条目都有一个名称和模式本身。

你可以在处理器定义的 pattern_definitions 选项下添加自定义模式。以下是指定自定义模式定义的管道示例:

{
"description": "...",
"processors": [
{
"grok": {
"field": "message",
"patterns": ["my %{FAVORITE_DOG:dog} is colored %{RGB:color}"],
"pattern_definitions": {
"FAVORITE_DOG": "beagle",
"RGB": "RED|GREEN|BLUE"
}
}
}
]
}

提供多个匹配模式​

有时一个模式不足以捕获字段的所有可能结构。假设我们想匹配所有包含你最喜欢的猫或狗品种的消息。一种实现方式是提供两个不同的可匹配模式,而不是用一个极其复杂的表达式来实现相同的 or 行为。

以下是对 simulate API 执行的此类配置示例:

POST _ingest/pipeline/_simulate
{
"pipeline": {
"description": "parse multiple patterns",
"processors": [
{
"grok": {
"field": "message",
"patterns": ["%{FAVORITE_DOG:pet}", "%{FAVORITE_CAT:pet}"],
"pattern_definitions": {
"FAVORITE_DOG": "beagle",
"FAVORITE_CAT": "burmese"
}
}
}
]
},
"docs": [
{
"_source": {
"message": "I love burmese cats!"
}
}
]
}

响应:

{
"docs": [
{
"doc": {
"_index": "_index",
"_id": "_id",
"_version": "-3",
"_source": {
"message": "I love burmese cats!",
"pet": "burmese"
},
"_ingest": {
"timestamp": "2016-11-08T19:43:03.850+0000"
}
}
}
]
}

两个模式都会用相应的匹配结果设置 pet 字段。但如果我们想追踪是哪个模式匹配并填充了字段呢?可以使用 trace_match 参数。以下是同一管道配置了 "trace_match": true 后的输出:

{
"docs": [
{
"doc": {
"_index": "_index",
"_id": "_id",
"_version": "-3",
"_source": {
"message": "I love burmese cats!",
"pet": "burmese"
},
"_ingest": {
"_grok_match_index": "1",
"timestamp": "2016-11-08T19:43:03.850+0000"
}
}
}
]
}

在上面的响应中,可以看到匹配的模式索引是 "1",即 patterns 中第二个(索引从零开始)匹配的模式。

此追踪元数据可用于调试哪个模式匹配成功。该信息存储在摄取元数据中,不会被索引。

从 REST 端点检索模式​

Grok 处理器自带一个用于检索其内置模式的 REST 端点。

GET _ingest/processor/grok

上述请求会返回一个包含内置模式字典的键值表示形式的响应体:

{
"patterns": {
"BACULA_CAPACITY": "%{INT}{1,3}(,%{INT}{3})*",
"PATH": "(?:%{UNIXPATH}|%{WINPATH})",
...
}
}

默认情况下,该 API 返回一组传统 Grok 模式。这些传统模式早于 Elastic Common Schema (ECS),不使用 ECS 字段名。要返回提取 ECS 字段名的模式,请在可选的 ecs_compatibility 查询参数中指定 v1。

GET _ingest/processor/grok?ecs_compatibility=v1

默认情况下,API 按模式从磁盘读取的顺序返回。这种排序方式保留相关模式的分组,例如所有解析 Linux syslog 行相关的模式会保持在一起。

你可以使用可选的布尔型 s 查询参数,改为按模式键名排序返回。

GET _ingest/processor/grok?s

API 返回如下响应:

{
"patterns": {
"BACULA_CAPACITY": "%{INT}{1,3}(,%{INT}{3})*",
"BACULA_DEVICE": "%{USER}",
"BACULA_DEVICEPATH": "%{UNIXPATH}",
...
}
}

当跨版本引用内置模式时,这会很有用。

Grok 看门狗​

执行时间过长的 grok 表达式会被中断,grok 处理器随后抛出异常并失败。grok 处理器有一个看门狗线程,用于确定 grok 表达式求值何时耗时过长,由以下设置控制:

名称默认值描述
ingest.grok.watchdog.interval1s检查是否存在超出最大允许执行时间的 grok 求值的频率。
ingest.grok.watchdog.max_execution_time1sgrok 表达式求值的最大允许执行时间。

Grok 调试​

建议使用 Grok Debugger 来调试 grok 模式。在调试器中,你可以在 UI 中用一个或多个模式测试样例数据。其底层使用与摄取节点处理器相同的引擎。

此外,建议为 Grok 启用 debug 日志,以便在 Elasticsearch 服务器日志中查看附加消息:

PUT _cluster/settings
{
"persistent": {
"logger.org.elasticsearch.ingest.common.GrokProcessor": "debug"
}
}

原文链接