Grok Debugger
Grok Debugger — инструмент для интерактивного создания и тестирования Grok-шаблонов, применяемых для разбора неструктурированных текстовых сообщений. Он позволяет разрабатывать выражения, извлекающие из текстов структурированные поля, проверять корректность сопоставления шаблонов и устранять ошибки разбора.
Данная статья описывает работу с интерфейсом Grok Debugger, синтаксис шаблонов, основные типы Grok-паттернов, правила экранирования спецсимволов и рекомендации по оптимизации. Также приводятся примеры разбора логов с пояснениями.
Использование Grok Debugger
Grok Debugger доступен в разделе Навигационное меню - Параметры системы - Настройки модулей - Основное - Grok Debugger.
На странице Grok Debugger доступны четыре области: Grok-шаблон, Тестируемые значения, Пользовательские шаблоны и Результаты.
Grok‑шаблон служит для ввода основного выражения, по которому происходит разбор лога. Примитивы (%{IP}, %{INT}, %{DATA} и т. д.) комбинируются в единую цепочку, задающую последовательность захвата полей.
В области Grok‑шаблон допустимо использование только одного Grok‑шаблона.
Тестируемые значения принимают одну или несколько строк сообщений. Эти данные подаются на вход Grok‑шаблону и пользовательским определениям. Для добавления нового тестируемого значения необходимо нажать на кнопку + Добавить значение и ввести новое сообщение в появившейся строке.
Пользовательские шаблоны позволяют объявить набор переиспользуемых конструкций, каждая из которых задается в формате FIELD_NAME %{GROK_TYPE:field_name}. В базовом выражении можно ссылаться на них по имени, что упрощает поддержку и повышает читаемость основного шаблона.
Область Результаты выводит JSON‑объект с именованными полями и их значениями, полученными после применения Grok‑шаблона к тестовым строкам. В случае ошибки разбора сообщения в поле результатов возникает соответствующее сообщение: Provided Grok expressions do not match field value: .... Результат разбора сообщения можно открыть в полноэкранном представленни.
Работа с Grok‑шаблонами
Grok‑шаблон — это строка, состоящая из встроенных или пользовательских паттернов, заключенных в форму %{PATTERN:field_name}. При разборе лога Grok‑шаблон последовательно пытается сопоставить текст и извлечь значения в именованные поля.
Grok-шаблон представляет собой удобную надстройку над регулярными выражениями. Каждый встроенный Grok-паттерн (например, BASE10NUM, IP, UUID) представляет собой фрагмент регулярного выражения. Например:
NUMBER=(?:%{BASE10NUM})BASE10NUM=(?<![0-9.+-])(?>[+-]?(?:(?:[0-9]+(?:\.[0-9]+)?)|(?:\.[0-9]+)))
Синтаксис шаблонов
Объявление стандартного паттерна
%{PATTERN} — вставка одного из предопределенных Grok‑примитивов (IP, WORD, INT, DATA и пр.).
Привязка к полю
%{PATTERN:имя_поля} — при совпадении текст сохраняется в поле имя_поля.
Пользовательский паттерн
%{USER_PATTERN} или %{USER_PATTERN:имя} — ссылка на определенный пользовательский паттерн.
Необязательные фрагменты
(?: ... )? — группа без присвоения значения полю, которая соответствует фрагменту, если он присутствует. Квантификатор ? означает, что группа может встретиться 0 или 1 раз.
Альтернативы
(?:foo|bar) — группа, соответствующая одному из вариантов (в приведенном примере foo или bar).
Основные типы паттернов
Ниже приведены наиболее часто используемые предопределенные Grok‑паттерны. Каждый из них позволяет извлечь распространенный тип данных из текстовых сообщений и проиллюстрирован примером.
| Паттерн | Описание | Пример |
|---|---|---|
WORD | Набор буквенно‑цифровых символов и подчеркиваний | admin_user |
INT | Целое число | 404, 123 |
NUMBER | Целое или дробное число | 3.14, -10 |
DATA | Любая последовательность символов | захватит все до конца строки или до следующего совпадения следом идущего паттерна |
NOTSPACE | Любая нескобочная строка без пробелов | захватит до пробела |
IP | IPv4‑адрес | 192.168.0.1 |
HOSTNAME | Имя хоста | server-1.local |
UUID | Универсальный уникальный идентификатор | 123e4567-e89b-12d3-a456-426614174000 |
HTTPDATE | Метка времени в формате день/месяц/год:час:минута:сек+зона | 18/Jun/2025:11:27:27 +0000 |
TIMESTAMP_ISO8601 | Шаблон даты/времени ISO‑формата | 2025-07-03T12:34:56.789Z |
GREEDYDATA | Любая последовательность символов (жадный захват) | захватит все до конца строки или до последнего совпадения следом идущего паттерна |
Для оптимальной производительности рекомендуется отдавать предпочтение узкопрофильным паттернам (WORD, INT, IP и т. п.) и минимизировать использование жадных типов, таких как GREEDYDATA, поскольку они могут значительно замедлять разбор текстовых сообщений.
Использование регулярных выражений внутри Grok‑шаблонов
Помимо встроенных паттернов (%{WORD}, %{IP} и др.), в Grok-шаблонах допустимо использовать обычные регулярные выражения (regex) — в том числе с именованными группами и логическими конструкциями.
Это полезно в тех случаях, когда предопределенного Grok-паттерна недостаточно или требуется более строгая проверка значений.
Например, для строки:
sessionID=QZA-7513 STATUS=FAIL user=admin ip=10.0.0.5
Можно использовать такой шаблон:
^sessionID=%{WORD:prefix}-%{INT:session} STATUS=(?<status>OK|FAIL) user=%{WORD:user} ip=%{IP:ip_address}$
Здесь:
-
(?<status>OK|FAIL)— это регулярное выражение с именованной группойstatus, допускающее только два допустимых значения:OKилиFAIL -
остальные поля извлекаются с помощью стандартных Grok-паттернов
Особенности использования RegEx
Регулярные выражения можно свободно вставлять в тело Grok-шаблона и комбинировать с Grok-примитивами. Это особенно полезно, когда необходимо задать строгие условия на формат значений или ограничить допустимые варианты. Именованные группы вида (?<field_name>...) позволяют извлекать данные в поля так же, как и %{PATTERN:field_name}, но с большей гибкостью — например, при проверке принадлежности значения к фиксированному множеству, как в конструкции (?<status>OK|FAIL).
Экранирование спецсимволов
Иногда в логах встречаются символы, которые в регулярных выражениях и Grok‑шаблонах имеют специальное значение и поэтому требуют экранирования. Например, строка:
[WARN] service started at 2025-07-04T12:01:31Z
Содержит квадратные скобки, которые без экранирования Grok воспримет как начало и конец класса символов. Чтобы корректно разобрать уровень логирования WARN, шаблон необходимо определить так:
\[%{WORD:level}\] %{GREEDYDATA:message}
В данном случае экранирование \[ и \] позволяет искать буквальные символы [ и ], а не трактовать их как метасимволы, задающие класс (диапазон) символов.
При разборе полей, обернутых в двойные кавычки, необходимо экранировать знак " обратным слэшем, иначе парсер Grok будет считать кавычку частью синтаксиса шаблона. Например, для строки:
user="alice" action="login"
Корректный шаблон выглядит следующим образом:
user=\"%{WORD:username}\" action=\"%{WORD:action}\"
Без экранирования (\") Grok-интерпретатор попытается трактовать " как границу литерала или выдаст ошибку разбора.
Экранирование также необходимо для следующих символов: ., \, +, *, ?, {, }, (, ), ^, $.
Примеры разбора текстовых сообщений
Ниже приведены типовые примеры использования Grok-шаблонов при разборе текстовых сообщений.
Разбор Apache‑лога
10.19.86.202 - - [18/Jun/2025:11:27:27 +0000] "GET /index.html HTTP/1.1" 200 1024
^%{IP:client} - - \[%{HTTPDATE:timestamp}\] "%{WORD:method} %{URIPATH:request} HTTP/%{NUMBER:version}" %{INT:status} %{INT:bytes}$
В данном шаблоне используются точные типы (IP, HTTPDATE, INT) без жадных паттернов. Экранированные скобки и кавычки фиксируют структуру записи.
При работе с Grok-шаблонами рекомендуется явно указывать границы строки с помощью якорей ^ и $. Без этих символов движок Grok будет искать совпадения в любой части строки, что при несоответствии шаблону может привести к множеству лишних попыток сопоставления. Это существенно снижает производительность — особенно при массовой обработке логов — и может замедлить парсинг в 6–10 раз. Использование якорей ограничивает область разбора, позволяет быстрее отбрасывать неподходящие записи и увеличивает скорость разбора текста.
Разбор лога с использованием пользовательского шаблона
event=login user=admin ip=192.168.1.100
LOGKV %{WORD:key}=%{DATA:value}
^%{LOGKV:event} %{LOGKV:user} %{LOGKV:ip}$
Пользовательский шаблон LOGKV задает формат ключ=значение, где key и value — независимые поля. Он переиспользуется трижды, делая основной шаблон компактным и читаемым. Это особенно полезно в логах, где формат повторяется с разными полями.
Разбор лога с использованием регулярных выражений и Grok-паттернов
sessionID=QZA-7513 STATUS=FAIL user=admin ip=10.0.0.5
^sessionID=%{WORD:prefix}-%{INT:session} STATUS=(?<status>OK|FAIL) user=%{WORD:user} ip=%{IP:ip_address}$
В приведенном шаблоне объединены Grok-паттерны и обычное регулярное выражение с именованной группой (?<status>...). Такой подход позволяет использовать строгое регулярное ограничение на значение status, при этом повторно использовать готовые Grok-паттерны для других полей. Это облегчает читаемость шаблона и позволяет точно контролировать формат полей, если Grok-примитив слишком широк.