Сопоставление DQL в логах

Сопоставление DQL в логах

С помощью платформы Ключ-АСТРОМ можно использовать функции и логические операторы DQL в сопоставлениях. Сопоставление фильтрует загруженные данные и сокращает объём данных, обрабатываемых создаваемым правилом. Сопоставление можно использовать при обработке логов и событий, в метриках логов, событиях логов и бакетах логов для:

• Фильтрации записей, содержащих указанную фразу.
• Поиска определённого значения в заданном атрибуте данных логов.
• Проверки значения на NULL.
• Соединения двух или более выражений с помощью логических операторов.

Подробнее об использовании логических операторов в DQL см. в разделе Логические операторы или операторы равенства.

Функции

matchesPhrase

Фильтрует записи, содержащие указанную фразу. Возвращает только совпадающие записи. Эта функция нечувствительна к регистру для символов ASCII, работает с многозначными атрибутами (совпадение с любым из значений), а символ звёздочки (*) является подстановочным знаком, относящимся только к одному термину, а не ко всему значению поля.

Валидация Функция matchesPhrase выполняет нечувствительный к регистру поиск contains для всей строки запроса и не поддерживает подстановочные знаки в середине строки. Для найденных результатов выполняется дополнительная валидация:

• Если запрос начинается с символа слова, предшествующий символ должен быть несловесным символом.
• Если запрос заканчивается символом слова, следующий символ должен быть несловесным символом.
• Если запрос начинается со звёздочки, проверка предшествующего символа не выполняется.
• Если запрос заканчивается звёздочкой, проверка следующего символа не выполняется.

Синтаксис matchesPhrase(expression, phrase [, caseSensitive])

Параметр	Тип	Обязательный	Значение по умолчанию	Описание
expression	строка, массив	да		Выражение (строка или массив строк), которое нужно проверить.
phrase	строка	да		Фраза для поиска.
caseSensitive	логическое	нет	false	Этот необязательный параметр (caseSensitive) не поддерживается сопоставлением. Функция matchesPhrase в сопоставлении выполняет только нечувствительный к регистру поиск.

Пример В этом примере вы добавляете фильтр, который сопоставляет записи логов, содержащие фразу error в их содержимом.

matchesPhrase(content, "error")

Примеры обработки событий с использованием функции DQL matchesPhrase

Часть входного события	Запрос обработки	Результат сопоставления	Описание
attribute="User 'käärmanü' failed to login from 192.168.0.1"	matchesPhrase(attribute, "192.168.0.1")	Точное совпадение по одному термину.
attribute="User 'käärmanü' failed to login from 192.168.0.123"	matchesPhrase(attribute, "192.168.0.1")	После символа 1 ожидается несловесный символ.
attribute="User 'käärmanü' failed to login from 192.168.0.123"	matchesPhrase(attribute, "192.168.0.1*")	Запрос соответствует всем IP-адресам с последним октетом от 100 до 199.
attribute="User 'käärmanü' failed to login from 192.168.0.1"	matchesPhrase(attribute, "failed to login")	Точное совпадение фразы.
attribute="User 'käärmanü' failed to login from 192.168.0.1"	matchesPhrase(attribute, "failed to log")	log не является полным словом, после log ожидается несловесный символ.
attribute="User 'käärmanü' failed to login from 192.168.0.1"	matchesPhrase(attribute, "failed to log*")	Если запрос заканчивается подстановочным знаком, проверка следующего символа пропускается.
attribute="User 'käärmanü' failed to login from 192.168.0.1"	matchesPhrase(attribute, "ed to login")	ed не является полным словом, предшествующий символ l является частью слова.
attribute="User 'käärmanü' failed to login from 192.168.0.1"	matchesPhrase(attribute, "*ed to login")	Если запрос начинается с подстановочного знака, проверка предшествующего символа пропускается.
attribute="User 'käärmanü' failed to login from 192.168.0.1"	matchesPhrase(attribute, "*ed to log*")	Если запрос начинается и заканчивается подстановочным знаком, проверка предшествующего и следующего символов пропускается.
attribute="User 'käärmanü' failed to login from 192.168.0.1"	matchesPhrase(attribute, "käärmanü failed")	Между käärmanü и failed должен быть символ апострофа (').
attribute="User 'käärmanü' failed to login from 192.168.0.1"	matchesPhrase(attribute, "rmanü' failed")	Не-ASCII символ ä рассматривается как несловесный символ.
attribute="User 'käärmanü' failed to login from 192.168.0.1"	matchesPhrase(attribute, " 'käärmanü' failed")	Если запрос начинается с несловесного символа, проверка предшествующего символа пропускается.
attribute="Failed to assign monitoring configuration for com.astromkey.extension"	matchesPhrase(attribute, "configuration for")	В запросе пробел, а в значении атрибута — табуляция.
attribute="Failed to assign monitoring configuration for com.astromkey.extension"	matchesPhrase(attribute, "failed to")	В запросе один пробел, а в значении атрибута — двойной пробел.
attribute="Failed to assign monitoring configuration for com.astromkey.extension"	matchesPhrase(attribute, "failed to")	Можно искать с несколькими пробелами.
attribute=["Gdansk, Poland", "Linz, Austria", "Klagenfurt, Austria"]	matchesPhrase(attribute, "Austria")	Функция обрабатывает многозначные атрибуты по принципу «любое совпадение», в данном случае Austria совпадает во втором и третьем значениях.
attribute=["Gdansk, Poland", "Linz, Austria", "Klagenfurt, Austria"]	matchesPhrase(attribute, "Pol*")	Подстановочный знак можно использовать и при работе с многозначными атрибутами.

matchesValue

Ищет записи с определённым значением в заданном атрибуте. Возвращает только совпадающие записи. Эта функция нечувствительна к регистру для символов ASCII, работает с многозначными атрибутами (совпадение с любым из значений) и не поддерживает подстановочные знаки в середине значения.

Синтаксис matchesValue(expression, value [, caseSensitive])

Параметр	Тип	Обязательный	Значение по умолчанию	Описание
expression	строка, массив	да		Выражение (значение или массив значений), которое нужно проверить.
value	строка	да		Значение для поиска.
caseSensitive	логическое	нет	false	Этот необязательный параметр (caseSensitive) не поддерживается сопоставлением. Функция matchesValue в сопоставлении выполняет только нечувствительный к регистру поиск.

Пример В этом примере вы добавляете фильтр записей, где атрибут process.technology содержит значение nginx.

matchesValue(process.technology, "nginx")

Примеры обработки событий с использованием функции DQL matchesValue

Часть входного события	Запрос обработки	Результат сопоставления	Описание
attribute="Astromkey"	matchesValue(attribute, "astromkey")	Нечувствительное к регистру равенство.
attribute="User 'käärmanü' failed to login from 192.168.0.1"	matchesValue(attribute, "192.168.0.1")	Рассматривается всё значение атрибута.
attribute="User 'käärmanü' failed to login from 192.168.0.1"	matchesValue(attribute, "*192.168.0.1")	Значение заканчивается на 192.168.0.1.
attribute="User 'käärmanü' failed to login from 192.168.0.1"	matchesValue(attribute, "user*")	Значение начинается с user (без учёта регистра).
attribute="User 'käärmanü' failed to login from 192.168.0.1"	matchesValue(attribute, "*failed to log*")	Значение содержит строку failed to log.
attribute="Österreich"	matchesValue(attribute, "österreich")	Нечувствительно к регистру только для символов ASCII.
attribute="Österreich"	matchesValue(attribute, "Österreich")	Точное совпадение.
attribute=["Java", "DOCKER", "k8s"]	matchesValue(attribute, "docker")	Функция обрабатывает многозначные атрибуты по принципу «любое совпадение», в данном случае docker совпадает во втором значении.
attribute=["Java11", "java17"]	matchesValue(attribute, "java")	Ни одно из значений не равно строке java.
attribute=["Java11", "java17"]	matchesValue(attribute, "java*")	Оба значения начинаются со строки java.

isNotNull

Проверяет, что значение не NULL.

Синтаксис isNotNull(<value>)

Пример В этом примере мы фильтруем (выбираем) данные, где поле host.name содержит значение.

isNotNull(`host.name`)

Примеры обработки событий с использованием функции DQL isNotNull

Часть входного события	Запрос обработки	Результат сопоставления	Описание
{ attribute="Astromkey"}	isNotNull(other)	Атрибут other не существует.
{ attribute="Astromkey"}	isNotNull(attribute)	Атрибут имеет ненулевое значение.
{ attribute=null}	isNotNull(attribute)	Атрибут имеет нулевое значение.

isNull

Проверяет, что значение NULL.

Синтаксис isNull(<value>)

Пример В этом примере мы фильтруем (выбираем) данные, где поле host.name не содержит значения.

filter isNull(`host.name`)

Примеры обработки событий с использованием функции DQL isNull

Часть входного события	Запрос обработки	Результат сопоставления	Описание
{ attribute="Astromkey"}	isNull(other)	Атрибут other не существует.
{ attribute="Astromkey"}	isNull(attribute)	Атрибут имеет ненулевое значение.
{ attribute=null}	isNull(attribute)	Атрибут имеет нулевое значение.

Операторы

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

OR

Логическое сложение.

Синтаксис <expression_1> or <expression_2>

Пример В этом примере вы добавляете сопоставление для фильтрации записей, где содержимое содержит либо фразу timestamp, либо фразу trigger.

matchesPhrase(content, "timestamp") or matchesPhrase(content, "trigger")

AND

Логическое умножение.

Синтаксис <expression_1> and <expression_2>

Пример В этом примере вы добавляете сопоставление для фильтрации записей, где содержимое содержит фразу timestamp и фразу trigger.

matchesPhrase(content, "timestamp") and matchesPhrase(content, "trigger")

NOT

Логическое отрицание.

Синтаксис not <expression>

Пример В этом примере вы добавляете сопоставление для фильтрации записей, где содержимое не содержит фразу timestamp.

not matchesPhrase(content, "timestamp")

Строгое равенство

Логический оператор (==), обозначающий точное совпадение. Типы данных должны быть идентичными. Однако если десятичное значение равно 0, числа с плавающей запятой можно сравнивать с целочисленными данными. Например, 1==1.0. Для строк поиск чувствителен к регистру. В отличие от функции matchesValue, оператор строгого равенства выполняет сравнение с учётом регистра, не поддерживает подстановочные знаки и не работает с элементами многозначных атрибутов.

Синтаксис <expression1> == <expression2>

Примеры использования оператора строгого равенства

Часть входного события	Запрос обработки	Результат сопоставления	Описание
{ attribute="Astromkey"}	attribute == "Astromkey"	Атрибут имеет строковый тип и то же значение.
{ attribute="Astromkey"}	attribute == "astromkey"	Строгое равенство чувствительно к регистру.
{ attribute="1"}	attribute == 1	Атрибуты имеют разные типы данных.
{ attribute="1.0"}	attribute == 1	Числа с плавающей запятой можно сравнивать с целочисленными значениями, если их десятичная часть равна 0.
{ attribute=["Java", "DOCKER", "k8s"]}	attribute == "Java"	Атрибуты имеют разные типы данных.

Группировка

Можно создавать условную группировку с помощью скобок (()).

matchesValue(process.technology, "nginx") and ( matchesPhrase(content, "error") or matchesPhrase(content, "warn") )

Повторное использование выражений

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