Процессор Grok

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

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",
        "_type": "_doc",
        "_id": "_id",
        "_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 моделирования:

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": {
        "_type": "_doc",
        "_index": "_index",
        "_id": "_id",
        "_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": {
        "_type": "_doc",
        "_index": "_index",
        "_id": "_id",
        "_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-эндпоинтом для получения шаблонов, включенных в процессор.

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.

GET _ingest/processor/grok?ecs_compatibility=v1

По умолчанию API возвращает шаблоны в том порядке, в котором они считываются с диска. Этот порядок сортировки сохраняет группировку связанных шаблонов. Например, все шаблоны, связанные с разбором строк журнала Linux syslog, остаются сгруппированными.

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

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

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

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