Grok 处理器从文档里的单个文本字段提取结构化字段。你选择从哪个字段提取匹配的字段，也就是期望 Grok 模式将匹配的字段。Grok 模式类似于支持可以重用的别名表达式的正则表达式。

该处理器附带许多可重用的模式（reusable patterns）。

如果需要构建匹配日志的模式，那么你将发现 Grok Debugger 工具相当有用！Grok Constructor 也是有用的工具。

1. 在管道中使用 Grok 处理器

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`	否	-	有条件地执行处理器。请查看 Conditionally run a processor
`ignore_failure`	否	`false`	忽略处理器的失败。请查看 Handling pipeline failures
`on_failure`	否	-	处理处理器的失败。请查看 Handling pipeline failures
`tag`	否	-	处理器的标识符。用于调试和度量

下面的示例使用提供的模式从文档中的一个字符串字段提取及命名结构化字段。


curl -X POST "localhost:9200/_ingest/pipeline/_simulate?pretty" -H 'Content-Type: application/json' -d'
{
  "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"
        }
      }
    }
  ]
}

2. 自定义模式

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"
        }
      }
    }
  ]
}

3. 提供多个匹配模式

有时一个模式不足以捕获字段的可能结构。假设我们想要匹配所有包含你最喜欢的宠物品种（猫或狗）的消息。一种实现方法是提供两种不同的模式，而不是非常复杂的、捕获 or 行为的一个表达式。

下面是通过模拟 API 执行的配置示例：


curl -X POST "localhost:9200/_ingest/pipeline/_simulate?pretty" -H 'Content-Type: application/json' -d'
{
  "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 中的第二个（索引从 0 开始）模式。

该追踪元数据可用于调试哪个模式匹配。该信息被存储在摄取元数据中，并且不被索引。

4. 从 REST 端点检索模式

Grok 处理器附带自己的 REST 端点，用于检索处理器中包含的模式。


curl -X GET "localhost:9200/_ingest/processor/grok?pretty"

上面的请求将返回包含 key-value 形式的内建模式字典的响应体。


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

默认情况下，该 API 返回遗留的 Grok 模式列表。这些遗留模式早于 Elastic 公共模式（Elastic Common Schema，ECS），并且不使用 ECS 字段名。为返回提取 ECS 字段名的模式，请在可选的 ecs_compatibility 查询参数中，指定 v1。


xxxxxxxxxx
curl -X GET "localhost:9200/_ingest/processor/grok?ecs_compatibility=v1&pretty"

默认情况下，该 API 按照从磁盘读取的顺序返回模式。这种排序顺序保留相关模式的分组。比如，与解析 Linux syslog 行相关的所有模式都集中在一起。

可以使用可选的布尔 s 查询参数按键名对返回的模式进行排序。


xxxxxxxxxx
curl -X GET "localhost:9200/_ingest/processor/grok?s&pretty"

该 API 返回如下响应：


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

当内置模式在不同版本之间发生变化时，这可以作为参考。

5. Grok 看门狗

执行时间过长的 Grok 表达式将被中断，然后 Grok 处理器将失败。Grok 处理器有一个看门狗线程，它决定 Grok 表达式的求值时间是否过长，并且由以下设置控制：

Grok 看门狗设置

名称	默认值	描述
`ingest.grok.watchdog.interval`	1s	多长时间检查一次是否存在执行时间超过最大允许执行时间的 grok 求值
`ingest.grok.watchdog.max_execution_time`	1s	grok 表达式求值的最大允许执行时间

6. Grok 调试

建议使用 Grok Debugger 调试 Grok 模式，通过它，可以使用样例数据在 UI 中测试一或多个模式。在底层，它使用与 ingest 节点处理器相同的引擎。

另外，建议为 Grok 启用调试日志，以便在 Elasticsearch 服务日志中也可以看到额外的消息。

参考文档

https://www.elastic.co/guide/en/elasticsearch/reference/8.6/grok-processor.html