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

Grok‑шаблон:

^%{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}

Grok‑шаблон:

^%{LOGKV:event} %{LOGKV:user} %{LOGKV:ip}$

Пользовательский шаблон LOGKV задает формат ключ=значение, где key и value — независимые поля. Он переиспользуется трижды, делая основной шаблон компактным и читаемым. Это особенно полезно в логах, где формат повторяется с разными полями.

Разбор лога с использованием регулярных выражений и Grok-паттернов

Лог:

sessionID=QZA-7513 STATUS=FAIL user=admin ip=10.0.0.5

Grok‑шаблон:

^sessionID=%{WORD:prefix}-%{INT:session} STATUS=(?<status>OK|FAIL) user=%{WORD:user} ip=%{IP:ip_address}$

В приведенном шаблоне объединены Grok-паттерны и обычное регулярное выражение с именованной группой (?<status>...). Такой подход позволяет использовать строгое регулярное ограничение на значение status, при этом повторно использовать готовые Grok-паттерны для других полей. Это облегчает читаемость шаблона и позволяет точно контролировать формат полей, если Grok-примитив слишком широк.