Процессор Grok

Вот пример использования предоставленных шаблонов для извлечения и именования структурированных полей из строкового поля в документе.

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, который совпал.

Эти метаданные отслеживания позволяют отлаживать, какой из шаблонов совпал. Эта информация хранится в метаданных обработки и не будет индексироваться.

Процессор 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, укажите v1 в необязательном параметре запроса ecs_compatibility.

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 для отладки шаблонов grok. Оттуда вы можете протестировать один или несколько шаблонов в пользовательском интерфейсе на примерах данных. Под капотом он использует тот же движок, что и обработчик узла ввода.

Кроме того, рекомендуется включить отладовую запись для Grok, чтобы любые дополнительные сообщения также отображались в журнале сервера Elasticsearch.

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