Link Search Menu Expand Document Documentation Menu
文档

本文档介绍如何在 OpenSearch 摄入管道中使用 grok 处理器。如果您的用例涉及大型或复杂数据集，请考虑使用在 OpenSearch 集群上运行的 Data Prepper grok 处理器。

Grok 处理器

grok 处理器用于使用模式匹配来解析和结构化非结构化数据。您可以使用 grok 处理器从日志消息、Web 服务器访问日志、应用程序日志以及其他遵循一致格式的日志数据中提取字段。

Grok 基础知识

grok 处理器使用一组预定义模式来匹配输入文本的部分内容。每个模式由一个名称和一个正则表达式组成。例如，模式 %{IP:ip_address} 匹配一个 IP 地址并将其分配给字段 ip_address。您可以组合多个模式以创建更复杂的表达式。例如，模式 %{IP:client} %{WORD:method} %{URIPATHPARM:request} %{NUMBER:bytes %NUMBER:duration} 匹配 Web 服务器访问日志中的一行，并提取客户端 IP 地址、HTTP 方法、请求 URI、发送的字节数和请求持续时间。

有关可用预定义模式的列表，请参阅 Grok 模式。

grok 处理器基于 Oniguruma 正则表达式库构建，并支持该库中的所有模式。您可以使用 Grok Debugger 工具来测试和调试您的 grok 表达式。

语法

以下是 grok 处理器的基本语法

{
  "grok": {
    "field": "your_message",
    "patterns": ["your_patterns"]
  }
}

配置参数

要配置 grok 处理器，您有多种选项可以定义模式、匹配特定键并控制处理器的行为。下表列出了 grok 处理器的必需和可选参数。

参数 必需/可选 描述
字段 必需 包含要解析文本的字段名称。
模式 必需 用于匹配和提取命名捕获的 grok 表达式列表。返回列表中第一个匹配的表达式。
模式定义 可选 模式名称和模式元组的字典，用于为当前处理器定义自定义模式。如果某个模式与现有名称匹配，则它会覆盖预定义的定义。
追踪匹配 可选 当参数设置为 true 时，处理器会向已处理的文档添加一个名为 _grok_match_index 的字段。此字段包含在 patterns 数组中成功匹配文档的模式的索引。此信息对于调试和了解哪个模式应用于文档很有用。默认值为 false。
描述 可选 处理器的简要描述。
如果 可选 运行处理器的条件。
忽略失败 可选 指定即使处理器遇到错误是否继续执行。如果设置为 true，则忽略失败。默认为 false。
忽略缺失 可选 指定处理器是否应忽略不包含指定字段的文档。如果设置为 true，则如果字段不存在或为 null，处理器将不会修改文档。默认值为 false。
失败时 可选 处理器失败时要运行的处理器列表。
标签 可选 处理器的标识符标签。有助于调试以区分相同类型的处理器。

创建管道

以下步骤将指导您创建带有 grok 处理器的摄入管道。

步骤 1：创建管道

以下查询创建一个名为 log_line 的管道。它使用指定的模式从文档的 message 字段中提取字段。在本例中，它提取 clientip、timestamp 和 response_status 字段

PUT _ingest/pipeline/log_line
{
  "description": "Extract fields from a log line",
  "processors": [
    {
      "grok": {
        "field": "message",
        "patterns": ["%{IPORHOST:clientip} %{HTTPDATE:timestamp} %{NUMBER:response_status:int}"]
      }
    }
  ]
}

步骤 2 (可选)：测试管道。

alert icon 注意
建议在摄取文档之前测试您的管道。

要测试管道，请运行以下查询

POST _ingest/pipeline/log_line/_simulate
{
  "docs": [
    {
      "_source": {
        "message": "127.0.0.1 198.126.12 10/Oct/2000:13:55:36 -0700 200"
      }
    }
  ]
}

响应

以下响应确认管道按预期工作

{
  "docs": [
    {
      "doc": {
        "_index": "_index",
        "_id": "_id",
        "_source": {
          "message": "127.0.0.1 198.126.12 10/Oct/2000:13:55:36 -0700 200",
          "response_status": 200,
          "clientip": "198.126.12",
          "timestamp": "10/Oct/2000:13:55:36 -0700"
        },
        "_ingest": {
          "timestamp": "2023-09-13T21:41:52.064540505Z"
        }
      }
    }
  ]
}

步骤 3：摄取文档

以下查询将文档摄取到名为 testindex1 的索引中

PUT testindex1/_doc/1?pipeline=log_line
{
  "message": "127.0.0.1 198.126.12 10/Oct/2000:13:55:36 -0700 200"
}

步骤 4（可选）：检索文档

要检索文档，请运行以下查询

GET testindex1/_doc/1

自定义模式

您可以使用默认模式，也可以使用 patterns_definitions 参数将自定义模式添加到您的管道中。自定义 grok 模式可用于管道，以从不匹配内置 grok 模式的日志消息中提取结构化数据。这对于解析来自自定义应用程序的日志消息或解析以某种方式修改过的日志消息非常有用。自定义模式遵循一个简单的结构：每个模式都有一个唯一的名称和定义其匹配行为的相应正则表达式。

以下是如何在配置中包含自定义模式的示例。在此示例中，问题编号介于 3 到 4 位之间，并解析到 issue_number 字段中，状态解析到 status 字段中

PUT _ingest/pipeline/log_line
{
  "processors": [
    {
      "grok": {
        "field": "message",
        "patterns": ["The issue number %{NUMBER:issue_number} is %{STATUS:status}"],
        "pattern_definitions" : {
          "NUMBER" : "\\d{3,4}",
          "STATUS" : "open|closed"
        }
      }
    }
  ]
}

追踪匹配的模式

要追踪哪些模式匹配并填充了字段，您可以使用 trace_match 参数。以下是如何在配置中包含此参数的示例

PUT _ingest/pipeline/log_line  
{  
  "description": "Extract fields from a log line",  
  "processors": [  
    {  
      "grok": {  
        "field": "message",  
        "patterns": ["%{HTTPDATE:timestamp} %{IPORHOST:clientip}", "%{IPORHOST:clientip} %{HTTPDATE:timestamp} %{NUMBER:response_status:int}"],  
        "trace_match": true  
      }  
    }  
  ]  
}

当您模拟管道时，OpenSearch 会返回包含 grok_match_index 的 _ingest 元数据，如以下输出所示

{
  "docs": [
    {
      "doc": {
        "_index": "_index",
        "_id": "_id",
        "_source": {
          "message": "127.0.0.1 198.126.12 10/Oct/2000:13:55:36 -0700 200",
          "response_status": 200,
          "clientip": "198.126.12",
          "timestamp": "10/Oct/2000:13:55:36 -0700"
        },
        "_ingest": {
          "_grok_match_index": "1",
          "timestamp": "2023-11-02T18:48:40.455619084Z"
        }
      }
    }
  ]
}
剩余 350 字符

有问题？。

想贡献？或。