« GeoIP 处理器 Gsub 处理器 »
Elastic 文档 ›Elasticsearch 指南 [8.16] ›摄取管道 ›摄取处理器参考

Grok 处理器

编辑

Grok 处理器

编辑

从文档中的单个文本字段中提取结构化字段。您可以选择要从中提取匹配字段的字段，以及您期望匹配的 Grok 模式。Grok 模式类似于正则表达式，它支持可重复使用的别名表达式。

此处理器打包了许多可重用模式。

如果您需要帮助构建与您的日志匹配的模式，您会发现Grok 调试器工具非常有用！Grok 构造器也是一个有用的工具。

在管道中使用 Grok 处理器

编辑

表 23. Grok 选项

名称 必填 默认值 描述

field

是

-

用于 Grok 表达式解析的字段

patterns

是

-

要匹配并提取命名捕获的 Grok 表达式的有序列表。返回列表中第一个匹配的表达式。

pattern_definitions

否

-

模式名称和模式元组的映射，定义当前处理器要使用的自定义模式。与现有名称匹配的模式将覆盖预先存在的定义。

ecs_compatibility

否

已禁用

必须为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

否

-

处理器的标识符。用于调试和指标。

以下是如何使用提供的模式从文档中的字符串字段中提取并命名结构化字段的示例。

resp = client.ingest.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"
            }
        }
    ],
)
print(resp)
response = client.ingest.simulate(
  body: {
    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'
        }
      }
    ]
  }
)
puts response
const response = await client.ingest.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",
      },
    },
  ],
});
console.log(response);
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行为。

以下是在模拟 API 上执行此类配置的示例

resp = client.ingest.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!"
            }
        }
    ],
)
print(resp)
response = client.ingest.simulate(
  body: {
    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!'
        }
      }
    ]
  }
)
puts response
const response = await client.ingest.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!",
      },
    },
  ],
});
console.log(response);
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 端点。

resp = client.ingest.processor_grok()
print(resp)
response = client.ingest.processor_grok
puts response
const response = await client.ingest.processorGrok();
console.log(response);
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。

resp = client.ingest.processor_grok(
    ecs_compatibility="v1",
)
print(resp)
response = client.ingest.processor_grok(
  ecs_compatibility: 'v1'
)
puts response
const response = await client.ingest.processorGrok({
  ecs_compatibility: "v1",
});
console.log(response);
GET _ingest/processor/grok?ecs_compatibility=v1

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

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

resp = client.ingest.processor_grok(
    s=True,
)
print(resp)
response = client.ingest.processor_grok(
  s: true
)
puts response
const response = await client.ingest.processorGrok({
  s: "true",
});
console.log(response);
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 表达式的计算时间过长，并由以下设置控制

表 24. Grok 看门狗设置

名称 默认值 描述

ingest.grok.watchdog.interval

1s

检查是否有 Grok 计算时间超过最大允许执行时间的频率。

ingest.grok.watchdog.max_execution_time

1s

Grok 表达式计算的最大允许执行时间。

Grok 调试

编辑

建议使用Grok 调试器来调试 Grok 模式。在那里，您可以针对样本数据在 UI 中测试一个或多个模式。在底层，它使用与摄取节点处理器相同的引擎。

此外，建议启用 Grok 的调试日志记录，以便也可以在 Elasticsearch 服务器日志中看到任何其他消息。

PUT _cluster/settings
{
  "persistent": {
    "logger.org.elasticsearch.ingest.common.GrokProcessor": "debug"
  }
}
« GeoIP 处理器 Gsub 处理器 »