Grok Processor（Grok 处理器）

原文链接 : https://www.elastic.co/guide/en/elasticsearch/reference/5.3/grok-processor.html

译文链接 : http://www.apache.wiki/pages/viewpage.action?pageId=10027802

贡献者 : 那伊抹微笑，ApacheCN，Apache中文网

从 document（文档）中的单个 text filed（文本字段）提取 structured fields（结构化字段）。您可以选择从哪个字段来提取所匹配的字段，以及您想要匹配的 grok **pattern。grok pattern 就像正则表达式，并且支持可以重用的 aliased expressions**（别名表达式）。

此工具非常适用于 syslog logs，apache 和其它的 webserver logs，mysql logs，以及一般情况下，用于人类而不是计算机使用的任何的 log format（日志格式）。该 processor（处理器）包含超过 120 种可重用的 patterns。

如果您需要工具来帮助 building patterns（构建模式）以匹配 log（日志），您将会发现 http://grokdebug.herokuapp.com 和 http://grokconstructor.appspot.com/ 应用程序是相当有用的。

Grok Basics（Grok 基础）

Grok 以 regular expressions（正则表达式）为基础，所以在 Grok 中的任何正则表达式也是有效的。正则表达式库是 Oniguruma。您可以在 Onigiruma 网站上 查看所支持的完整的 r**egexp syntax**（正在表达式语法）。

Grok 通过利用这种正则表达式语言来工作，允许命名现有的 pattern（模式），并将它们组合成与您的字段相匹配的更复杂的 pattern（模式）。

对于重用 grok pattern（grok 模式）的语法有三种形式 : %{SYNTAX:SEMANTIC}，%{SYNTAX}，**%{SYNTAX:SEMANTIC:TYPE}**。

该 SYNTAX（语法）是将要匹配您的文本的 pattern（模式）的名称。例如，3.44 将会被 NUMBER 模式匹配并且 55.3.244.1 将会被 IP 模式匹配。该语法是告诉你如何匹配的。**NUMBER**和 **IP**都是在 default patterns set（默认模式集）中提供的 pattern（模式）。

该 SEMANTIC（语义）是您给一段被匹配的文本的标识符。例如，3.44 可以是事件的持续时间，所以你可以简单的称之为 duration。此外，字符串 55.3.244.1 可能会标识 client 发出的请求。

该 TYPE（类型）是您希望转换您命名的 field（字段）的 type（类型）。int 和 float 是目前唯一所支持的强制类型。

例如，您可能想要去匹配以下文本 : 

  1. 3.44 55.3.244.1

您可能知道该示例中的消息是一个 number（数字），后跟一个 IP address（IP 地址）。您可以通过使用下列的 Grok **expression（Grok** 表达式）来匹配这个文本。

  1. %{NUMBER:duration} %{IP:client}

Using the Grok Processor in a Pipeline（在管道中使用 Grok 表达式）

Table 20. Grok Options（表 20. Grok 选项）

Name（名称） Required（必要的） Default（默认值） Description（描述）
field yes - The field to use for grok expression parsing
patterns yes - An ordered list of grok expression to match and extract named captures with. Returns on the first expression in the list that matches.
pattern_definitions no - A map of pattern-name and pattern tuples defining custom patterns to be used by the current processor. Patterns matching existing names will override the pre-existing definition.
trace_match no false when true, _ingest._grok_match_index will be inserted into your matched document’s metadata with the index into the pattern found in patterns that matched.
ignore_missing no false If true and field does not exist or is null, the processor quietly exits without modifying the document

以下是使用提供的 pattern（模式）从 document（文档）中的 string field（字符串字段）中提取和命名结构化字段的示例。

  1. {
  2.   "message": "55.3.244.1 GET /index.html 15824 0.043"
  3. }

这个 pattern（模式）可以是 : 

  1. %{IP:client} %{WORD:method} %{URIPATHPARAM:request} %{NUMBER:bytes} %{NUMBER:duration}

以下是一个使用 Grok 处理上述 document（文档）的示例 pipeline（管道）: 

  1. {
  2.   "description" : "...",
  3.   "processors": [
  4.     {
  5.       "grok": {
  6.         "field": "message",
  7.         "patterns": ["%{IP:client} %{WORD:method} %{URIPATHPARAM:request} %{NUMBER:bytes} %{NUMBER:duration}"]
  8.       }
  9.     }
  10.   ]
  11. }

此 pipeline（管道）将这些 named captures（命名捕获）作为文档中的新字段插入，如下所示 : 

  1. {
  2.   "message": "55.3.244.1 GET /index.html 15824 0.043",
  3.   "client": "55.3.244.1",
  4.   "method": "GET",
  5.   "request": "/index.html",
  6.   "bytes": 15824,
  7.   "duration": "0.043"
  8. }

Custom Patterns and Pattern Files（自定义模式和模式文件）

该 Grok processor 采用基本的 pattern（模式）进行预包装。这些 pattern（模式）可能并不总是有你想要的。Pattern 有一个非常基本的格式。每个 entry 描述有一个 name（名称）和 pattern（模式）本身。

您也可以在 pattern_definitions 选项下添加您自己的 pattern（模式）到 processor definition（处理器定义）中。

以下是一个指定自定义 pattern definitions（模式定义）的 pipeline（管道）: 

  1. {
  2.   "description" : "...",
  3.   "processors": [
  4.     {
  5.       "grok": {
  6.         "field": "message",
  7.         "patterns": ["my %{FAVORITE_DOG:dog} is colored %{RGB:color}"]
  8.         "pattern_definitions" : {
  9.           "FAVORITE_DOG" : "beagle",
  10.           "RGB" : "RED|GREEN|BLUE"
  11.         }
  12.       }
  13.     }
  14.   ]
  15. }

Providing Multiple Match Patterns（提供多个匹配模式）

有时一种 pattern（模式）不足以捕捉一个 field（字段）的潜在结构。假设我们要匹配包含您最喜欢的猫或狗宠物品种的所有 message（消息）。实现这一点的一个方法是提供两个不同的 pattern（模式），而不是一个真正复杂的表达式所捕获相同的 **or**行为。

以下是针对 simulate API（模拟 API）执行的这种配置的示例 : 

  1. curl -XPOST 'localhost:9200/_ingest/pipeline/_simulate?pretty' -H 'Content-Type: application/json' -d'
  2. {
  3.   "pipeline": {
  4.   "description" : "parse multiple patterns",
  5.   "processors": [
  6.     {
  7.       "grok": {
  8.         "field": "message",
  9.         "patterns": ["%{FAVORITE_DOG:pet}", "%{FAVORITE_CAT:pet}"],
  10.         "pattern_definitions" : {
  11.           "FAVORITE_DOG" : "beagle",
  12.           "FAVORITE_CAT" : "burmese"
  13.         }
  14.       }
  15.     }
  16.   ]
  17. },
  18. "docs":[
  19.   {
  20.     "_source": {
  21.       "message": "I love burmese cats!"
  22.     }
  23.   }
  24.   ]
  25. }
  26. '

响应如下 : 

  1. {
  2.   "docs": [
  3.     {
  4.       "doc": {
  5.         "_type": "_type",
  6.         "_index": "_index",
  7.         "_id": "_id",
  8.         "_source": {
  9.           "message": "I love burmese cats!",
  10.           "pet": "burmese"
  11.         },
  12.         "_ingest": {
  13.           "timestamp": "2016-11-08T19:43:03.850+0000"
  14.         }
  15.       }
  16.     }
  17.   ]
  18. }

两种 pattern（模式）都将使用适当的匹配来设置该字段 pet。但是如果要跟踪是哪以个模式匹配并且填充了字段，该怎么办呢？我们可以通过使用 trace_match参数来做到这一点。

以下是一个一样 pipeline（管道）的输出，但是使用的是 “trace_match“: true 的配置 : 

  1. {
  2.   "docs": [
  3.     {
  4.       "doc": {
  5.         "_type": "_type",
  6.         "_index": "_index",
  7.         "_id": "_id",
  8.         "_source": {
  9.           "message": "I love burmese cats!",
  10.           "pet": "burmese"
  11.         },
  12.         "_ingest": {
  13.           "_grok_match_index": "1",
  14.           "timestamp": "2016-11-08T19:43:03.850+0000"
  15.         }
  16.       }
  17.     }
  18.   ]
  19. }

在上述响应中，您可以看到匹配的 pattern（模式）的 index（索引）为 "**1**"。这就是说，它是在 patterns 中用于匹配的第二个（索引从零开始）模式。

这些所跟踪的元数据可以调试哪些 patterns（模式）被匹配到了。这些信息存储在 ingest metadata（元数据）中，并且不会被索引。