|
|
| Строка 1: |
Строка 1: |
|
| |
|
| = Сопоставление DQL в логах =
| |
| С помощью платформы Ключ-АСТРОМ можно использовать функции и логические операторы '''DQL''' в сопоставлениях. Сопоставление фильтрует загруженные данные и сокращает объём данных, обрабатываемых создаваемым правилом. Сопоставление можно использовать при обработке логов и событий, в метриках логов, событиях логов и бакетах логов для:
| |
|
| |
| * Фильтрации записей, содержащих указанную фразу.
| |
| * Поиска определённого значения в заданном атрибуте данных логов.
| |
| * Проверки значения на NULL.
| |
| * Соединения двух или более выражений с помощью логических операторов.
| |
|
| |
| Подробнее об использовании логических операторов в '''DQL''' см. в разделе '''Логические операторы или операторы равенства'''.
| |
|
| |
| == Функции ==
| |
|
| |
| === matchesPhrase ===
| |
| Фильтрует записи, содержащие указанную фразу. Возвращает только совпадающие записи. Эта функция нечувствительна к регистру для символов ASCII, работает с многозначными атрибутами (совпадение с любым из значений), а символ звёздочки (<code>*</code>) является подстановочным знаком, относящимся только к одному термину, а не ко всему значению поля.
| |
|
| |
| '''Валидация''' Функция <code>matchesPhrase</code> выполняет нечувствительный к регистру поиск '''contains''' для всей строки запроса и не поддерживает подстановочные знаки в середине строки. Для найденных результатов выполняется дополнительная валидация:
| |
|
| |
| * Если запрос начинается с символа слова, предшествующий символ должен быть несловесным символом.
| |
| * Если запрос заканчивается символом слова, следующий символ должен быть несловесным символом.
| |
| * Если запрос начинается со звёздочки, проверка предшествующего символа не выполняется.
| |
| * Если запрос заканчивается звёздочкой, проверка следующего символа не выполняется.
| |
|
| |
| '''Синтаксис''' <code>matchesPhrase(expression, phrase [, caseSensitive])</code>
| |
| {| class="wikitable"
| |
| !Параметр
| |
| !Тип
| |
| !Обязательный
| |
| !Значение по умолчанию
| |
| !Описание
| |
| |-
| |
| |<code>expression</code>
| |
| |строка, массив
| |
| |да
| |
| |
| |
| |Выражение (строка или массив строк), которое нужно проверить.
| |
| |-
| |
| |<code>phrase</code>
| |
| |строка
| |
| |да
| |
| |
| |
| |Фраза для поиска.
| |
| |-
| |
| |<code>caseSensitive</code>
| |
| |логическое
| |
| |нет
| |
| |false
| |
| |Этот необязательный параметр (<code>caseSensitive</code>) не поддерживается сопоставлением. Функция <code>matchesPhrase</code> в сопоставлении выполняет только нечувствительный к регистру поиск.
| |
| |}
| |
| '''Пример''' В этом примере вы добавляете фильтр, который сопоставляет записи логов, содержащие фразу <code>error</code> в их содержимом.<pre>matchesPhrase(content, "error")</pre>'''Примеры обработки событий с использованием функции DQL matchesPhrase'''
| |
| {| class="wikitable"
| |
| !Часть входного события
| |
| !Запрос обработки
| |
| !Результат сопоставления
| |
| !Описание
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.1"</code>
| |
| |<code>matchesPhrase(attribute, "192.168.0.1")</code>
| |
| |Точное совпадение по одному термину.
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.123"</code>
| |
| |<code>matchesPhrase(attribute, "192.168.0.1")</code>
| |
| |После символа 1 ожидается несловесный символ.
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.123"</code>
| |
| |<code>matchesPhrase(attribute, "192.168.0.1*")</code>
| |
| |Запрос соответствует всем IP-адресам с последним октетом от 100 до 199.
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.1"</code>
| |
| |<code>matchesPhrase(attribute, "failed to login")</code>
| |
| |Точное совпадение фразы.
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.1"</code>
| |
| |<code>matchesPhrase(attribute, "failed to log")</code>
| |
| |<code>log</code> не является полным словом, после <code>log</code> ожидается несловесный символ.
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.1"</code>
| |
| |<code>matchesPhrase(attribute, "failed to log*")</code>
| |
| |Если запрос заканчивается подстановочным знаком, проверка следующего символа пропускается.
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.1"</code>
| |
| |<code>matchesPhrase(attribute, "ed to login")</code>
| |
| |<code>ed</code> не является полным словом, предшествующий символ <code>l</code> является частью слова.
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.1"</code>
| |
| |<code>matchesPhrase(attribute, "*ed to login")</code>
| |
| |Если запрос начинается с подстановочного знака, проверка предшествующего символа пропускается.
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.1"</code>
| |
| |<code>matchesPhrase(attribute, "*ed to log*")</code>
| |
| |Если запрос начинается и заканчивается подстановочным знаком, проверка предшествующего и следующего символов пропускается.
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.1"</code>
| |
| |<code>matchesPhrase(attribute, "käärmanü failed")</code>
| |
| |Между <code>käärmanü</code> и <code>failed</code> должен быть символ апострофа (<code>'</code>).
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.1"</code>
| |
| |<code>matchesPhrase(attribute, "rmanü' failed")</code>
| |
| |Не-ASCII символ <code>ä</code> рассматривается как несловесный символ.
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.1"</code>
| |
| |<code>matchesPhrase(attribute, " 'käärmanü' failed")</code>
| |
| |Если запрос начинается с несловесного символа, проверка предшествующего символа пропускается.
| |
| |
| |
| |-
| |
| |<code>attribute="Failed to assign monitoring configuration for com.astromkey.extension"</code>
| |
| |<code>matchesPhrase(attribute, "configuration for")</code>
| |
| |В запросе пробел, а в значении атрибута — табуляция.
| |
| |
| |
| |-
| |
| |<code>attribute="Failed to assign monitoring configuration for com.astromkey.extension"</code>
| |
| |<code>matchesPhrase(attribute, "failed to")</code>
| |
| |В запросе один пробел, а в значении атрибута — двойной пробел.
| |
| |
| |
| |-
| |
| |<code>attribute="Failed to assign monitoring configuration for com.astromkey.extension"</code>
| |
| |<code>matchesPhrase(attribute, "failed to")</code>
| |
| |Можно искать с несколькими пробелами.
| |
| |
| |
| |-
| |
| |<code>attribute=["Gdansk, Poland", "Linz, Austria", "Klagenfurt, Austria"]</code>
| |
| |<code>matchesPhrase(attribute, "Austria")</code>
| |
| |Функция обрабатывает многозначные атрибуты по принципу «любое совпадение», в данном случае <code>Austria</code> совпадает во втором и третьем значениях.
| |
| |
| |
| |-
| |
| |<code>attribute=["Gdansk, Poland", "Linz, Austria", "Klagenfurt, Austria"]</code>
| |
| |<code>matchesPhrase(attribute, "Pol*")</code>
| |
| |Подстановочный знак можно использовать и при работе с многозначными атрибутами.
| |
| |
| |
| |}
| |
|
| |
| === matchesValue ===
| |
| Ищет записи с определённым значением в заданном атрибуте. Возвращает только совпадающие записи. Эта функция нечувствительна к регистру для символов ASCII, работает с многозначными атрибутами (совпадение с любым из значений) и не поддерживает подстановочные знаки в середине значения.
| |
|
| |
| '''Синтаксис''' <code>matchesValue(expression, value [, caseSensitive])</code>
| |
| {| class="wikitable"
| |
| !Параметр
| |
| !Тип
| |
| !Обязательный
| |
| !Значение по умолчанию
| |
| !Описание
| |
| |-
| |
| |<code>expression</code>
| |
| |строка, массив
| |
| |да
| |
| |
| |
| |Выражение (значение или массив значений), которое нужно проверить.
| |
| |-
| |
| |<code>value</code>
| |
| |строка
| |
| |да
| |
| |
| |
| |Значение для поиска.
| |
| |-
| |
| |<code>caseSensitive</code>
| |
| |логическое
| |
| |нет
| |
| |false
| |
| |Этот необязательный параметр (<code>caseSensitive</code>) не поддерживается сопоставлением. Функция <code>matchesValue</code> в сопоставлении выполняет только нечувствительный к регистру поиск.
| |
| |}
| |
| '''Пример''' В этом примере вы добавляете фильтр записей, где атрибут <code>process.technology</code> содержит значение <code>nginx</code>.<pre>matchesValue(process.technology, "nginx")</pre>'''Примеры обработки событий с использованием функции DQL matchesValue'''
| |
| {| class="wikitable"
| |
| !Часть входного события
| |
| !Запрос обработки
| |
| !Результат сопоставления
| |
| !Описание
| |
| |-
| |
| |<code>attribute="Astromkey"</code>
| |
| |<code>matchesValue(attribute, "astromkey")</code>
| |
| |Нечувствительное к регистру равенство.
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.1"</code>
| |
| |<code>matchesValue(attribute, "192.168.0.1")</code>
| |
| |Рассматривается всё значение атрибута.
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.1"</code>
| |
| |<code>matchesValue(attribute, "*192.168.0.1")</code>
| |
| |Значение заканчивается на <code>192.168.0.1</code>.
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.1"</code>
| |
| |<code>matchesValue(attribute, "user*")</code>
| |
| |Значение начинается с <code>user</code> (без учёта регистра).
| |
| |
| |
| |-
| |
| |<code>attribute="User 'käärmanü' failed to login from 192.168.0.1"</code>
| |
| |<code>matchesValue(attribute, "*failed to log*")</code>
| |
| |Значение содержит строку <code>failed to log</code>.
| |
| |
| |
| |-
| |
| |<code>attribute="Österreich"</code>
| |
| |<code>matchesValue(attribute, "österreich")</code>
| |
| |Нечувствительно к регистру только для символов ASCII.
| |
| |
| |
| |-
| |
| |<code>attribute="Österreich"</code>
| |
| |<code>matchesValue(attribute, "Österreich")</code>
| |
| |Точное совпадение.
| |
| |
| |
| |-
| |
| |<code>attribute=["Java", "DOCKER", "k8s"]</code>
| |
| |<code>matchesValue(attribute, "docker")</code>
| |
| |Функция обрабатывает многозначные атрибуты по принципу «любое совпадение», в данном случае <code>docker</code> совпадает во втором значении.
| |
| |
| |
| |-
| |
| |<code>attribute=["Java11", "java17"]</code>
| |
| |<code>matchesValue(attribute, "java")</code>
| |
| |Ни одно из значений не равно строке <code>java</code>.
| |
| |
| |
| |-
| |
| |<code>attribute=["Java11", "java17"]</code>
| |
| |<code>matchesValue(attribute, "java*")</code>
| |
| |Оба значения начинаются со строки <code>java</code>.
| |
| |
| |
| |}
| |
|
| |
| === isNotNull ===
| |
| Проверяет, что значение не NULL.
| |
|
| |
| '''Синтаксис''' <code>isNotNull(<value>)</code>
| |
|
| |
| '''Пример''' В этом примере мы фильтруем (выбираем) данные, где поле <code>host.name</code> содержит значение.<pre>isNotNull(`host.name`)</pre>'''Примеры обработки событий с использованием функции DQL isNotNull'''
| |
| {| class="wikitable"
| |
| !Часть входного события
| |
| !Запрос обработки
| |
| !Результат сопоставления
| |
| !Описание
| |
| |-
| |
| |<code>{ attribute="Astromkey"}</code>
| |
| |<code>isNotNull(other)</code>
| |
| |Атрибут <code>other</code> не существует.
| |
| |
| |
| |-
| |
| |<code>{ attribute="Astromkey"}</code>
| |
| |<code>isNotNull(attribute)</code>
| |
| |Атрибут имеет ненулевое значение.
| |
| |
| |
| |-
| |
| |<code>{ attribute=null}</code>
| |
| |<code>isNotNull(attribute)</code>
| |
| |Атрибут имеет нулевое значение.
| |
| |
| |
| |}
| |
|
| |
| === isNull ===
| |
| Проверяет, что значение NULL.
| |
|
| |
| '''Синтаксис''' <code>isNull(<value>)</code>
| |
|
| |
| '''Пример''' В этом примере мы фильтруем (выбираем) данные, где поле <code>host.name</code> не содержит значения.<pre>filter isNull(`host.name`)</pre>'''Примеры обработки событий с использованием функции DQL isNull'''
| |
| {| class="wikitable"
| |
| !Часть входного события
| |
| !Запрос обработки
| |
| !Результат сопоставления
| |
| !Описание
| |
| |-
| |
| |<code>{ attribute="Astromkey"}</code>
| |
| |<code>isNull(other)</code>
| |
| |Атрибут <code>other</code> не существует.
| |
| |
| |
| |-
| |
| |<code>{ attribute="Astromkey"}</code>
| |
| |<code>isNull(attribute)</code>
| |
| |Атрибут имеет ненулевое значение.
| |
| |
| |
| |-
| |
| |<code>{ attribute=null}</code>
| |
| |<code>isNull(attribute)</code>
| |
| |Атрибут имеет нулевое значение.
| |
| |
| |
| |}
| |
|
| |
| == Операторы ==
| |
| Логические операторы можно использовать для соединения двух или более выражений. Ознакомьтесь с разделом '''Логические операторы или операторы равенства''', чтобы узнать больше о поведении логических операторов в '''DQL'''.
| |
|
| |
| === OR ===
| |
| Логическое сложение.
| |
|
| |
| '''Синтаксис''' <code><expression_1> or <expression_2></code>
| |
|
| |
| '''Пример''' В этом примере вы добавляете сопоставление для фильтрации записей, где содержимое содержит либо фразу <code>timestamp</code>, либо фразу <code>trigger</code>.<pre>matchesPhrase(content, "timestamp") or matchesPhrase(content, "trigger")</pre>
| |
|
| |
| === AND ===
| |
| Логическое умножение.
| |
|
| |
| '''Синтаксис''' <code><expression_1> and <expression_2></code>
| |
|
| |
| '''Пример''' В этом примере вы добавляете сопоставление для фильтрации записей, где содержимое содержит фразу <code>timestamp</code> и фразу <code>trigger</code>.<pre>matchesPhrase(content, "timestamp") and matchesPhrase(content, "trigger")</pre>
| |
|
| |
| === NOT ===
| |
| Логическое отрицание.
| |
|
| |
| '''Синтаксис''' <code>not <expression></code>
| |
|
| |
| '''Пример''' В этом примере вы добавляете сопоставление для фильтрации записей, где содержимое не содержит фразу <code>timestamp</code>.<pre>not matchesPhrase(content, "timestamp")</pre>
| |
|
| |
| === Строгое равенство ===
| |
| Логический оператор (<code>==</code>), обозначающий точное совпадение. Типы данных должны быть идентичными. Однако если десятичное значение равно 0, числа с плавающей запятой можно сравнивать с целочисленными данными. Например, <code>1==1.0</code>. Для строк поиск чувствителен к регистру. В отличие от функции <code>matchesValue</code>, оператор строгого равенства выполняет сравнение с учётом регистра, не поддерживает подстановочные знаки и не работает с элементами многозначных атрибутов.
| |
|
| |
| '''Синтаксис''' <code><expression1> == <expression2></code>
| |
|
| |
| '''Примеры использования оператора строгого равенства'''
| |
| {| class="wikitable"
| |
| !Часть входного события
| |
| !Запрос обработки
| |
| !Результат сопоставления
| |
| !Описание
| |
| |-
| |
| |<code>{ attribute="Astromkey"}</code>
| |
| |<code>attribute == "Astromkey"</code>
| |
| |Атрибут имеет строковый тип и то же значение.
| |
| |
| |
| |-
| |
| |<code>{ attribute="Astromkey"}</code>
| |
| |<code>attribute == "astromkey"</code>
| |
| |Строгое равенство чувствительно к регистру.
| |
| |
| |
| |-
| |
| |<code>{ attribute="1"}</code>
| |
| |<code>attribute == 1</code>
| |
| |Атрибуты имеют разные типы данных.
| |
| |
| |
| |-
| |
| |<code>{ attribute="1.0"}</code>
| |
| |<code>attribute == 1</code>
| |
| |Числа с плавающей запятой можно сравнивать с целочисленными значениями, если их десятичная часть равна 0.
| |
| |
| |
| |-
| |
| |<code>{ attribute=["Java", "DOCKER", "k8s"]}</code>
| |
| |<code>attribute == "Java"</code>
| |
| |Атрибуты имеют разные типы данных.
| |
| |
| |
| |}
| |
|
| |
| == Группировка ==
| |
| Можно создавать условную группировку с помощью скобок (<code>()</code>).<pre>matchesValue(process.technology, "nginx") and ( matchesPhrase(content, "error") or matchesPhrase(content, "warn") )</pre>
| |
|
| |
| == Повторное использование выражений ==
| |
| Все выражения сопоставления, используемые в событиях логов, метриках, обработке или конфигурациях бакетов, являются допустимыми '''DQL'''. Это означает, что эти выражения также можно использовать вместе с командой <code>filter</code> '''DQL''', например, в '''средстве просмотра логов'''.
| |
