DQL в логах

DQL в логах

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

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

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

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

Функции

matchesPhrase

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

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

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

Синтаксис

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, "dynaTrace")	Применимый	Равенство без учета регистра.
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)

timestamp	content	event.type	host.name
2022-08-03 11:27:19	2022-08-03 09:27:19.836 [QueueProcessor] RemoteReporter...	LOG	HOST-AF-710319

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

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

isNull

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

Синтаксис

isNull(<value>)

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

filter isNull(host.name)

timestamp	content	event.type	host.name
2022-08-03 12:53:26	2022-08-03T10:52:31Z localhost haproxy[12529]: 192.168.19.100:38440	LOG

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

Часть входного события	Обработка запроса	Результат совпадения	Описание
{"attribute":"astromkey"}	isNull(other)	Применимый	Атрибут other не существует.
{"attribute":"astromkey"}	isNull(attribute)	Непригодный	Имеет attribute ненулевое значение.
{"attribute":null}	isNull(attribute)	Применимый	Значение параметра 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 == "dynatrace"	Непригодный	Строгое равенство чувствительно к регистру.
{"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-выражениями. Это означает, что вы также можете использовать эти выражения вместе с командой DQL-фильтра, например, в средстве просмотра логов.