Фильтрация CMDB (TQL)
БДКЕ может содержать огромное количество КЕ, десятки и сотни тысяч. Одновременно их все просмотреть невозможно. КЕ могут делиться по функциональному, организационному и иному признаку на группы. Эти признаки интересны разным пользователям. Каждый пользователь желает видеть только интересующую его группу КЕ. Памир помогает в решении таких задач. Памир имеет инструмент фильтрации БДКЕ – Topology Query Language (TQL), язык описания топологии графа. TQL оперирует такими понятиями, как ТКЕ и связи. Он позволяет создавать маску из ТКЕ и накладывать ее на БДКЕ. Результатом выполнения TQL является ограниченный список КЕ. TQL используется:
- как самостоятельный инструмент – для фильтрации БДКЕ;
- в правилах доступа – для ограничения видимости БДКЕ;
- в дашбордах – для ограничения КЕ, доступных для отображения в виджетах;
- в мониторинге – для привязки шаблонов и тревог к избранным КЕ.
Построение TQL
Topology Query Language (TQL) - это язык запросов для описания топологии графа. Он позволяет описывать различные свойства графов, такие как количество вершин и ребер, наличие циклов, связность и т.д. TQL является мощным инструментом для анализа и визуализации БДКЕ.
Вершина – точка на графе, которая имеет определенные свойства:
- соответствие ТКЕ;
- смежность с другими вершинами.
Вершины могут быть связаны друг с другом ребрами, которые образуют граф.
Ребра соединяют две вершины и имеют определенные свойства:
- тип (композиция, ассоциация, агрегация);
- мощность;
- направление мощности.
Фильтрация по ТКЕ
Построение TQL выполняется в модальном окне.
Через контекстное меню (открывается по правой кнопке мыши) можно добавлять ТКЕ. Для выбора определенного типа КЕ достаточно создать вершину данного типа и нажать кнопку «Применить».
ТКЕ имеют иерархическую структуру. Для выбора КЕ, которые имеют общего родителя, нет необходимости добавлять все ТКЕ. Достаточно выбрать родительский тип. Будут выбраны все КЕ дочерних типов.
Для выбора всех КЕ типа СУБД PostgreSQL, MySQL достаточно создать TQL с ТКЕ СУБД
Связанные ТКЕ
TQL может состоять из нескольких несвязанных вершин. В таком случае будут выбраны КЕ все указанных типов. Между ними будут построены все существующие связи. Связи можно скрыть, выключив переключатель.
TQL может фильтровать БДКЕ по связям между КЕ. Для этого нужно кликнуть на внутреннюю область вершины и, не отпуская левую кнопку мыши, связать с другой вершиной. При движении курсора TQL подсветит вершины, до которых может быть установлена связь. Эти настройки берутся из Дополнительных связей ТКЕ.
В открывшемся диалоговом окне нужно выбрать тип связи, установить направление.
Связанные вершины графа будут соединены линией. На линии выводится название связи и ее символ. Редактировать связь можно, кликнув на ее названии левой кнопкой мыши. Изображения типов связей:
- композиция – полилиния, начальный корректор изображен в виде черного закрашенного ромба. Ромб располагается со стороны композирующего КЕ;
- агрегация – полилиния, начальный корректор изображен в виде бесцветного ромба. Ромб располагается со стороны агрегирующего КЕ;
- ассоциация – полилиния, конечный корректор изображен в виде стрелки.
Итоговый TQL показан на примере КЕ PostgreSQL
Мощность связи
TQL позволяет накладывать количественные ограничения на связанные узлы. По умолчанию накладывается ограничение
от 1 до *, где * означает бесконечность, со стороны конца связи. Это ограничение можно интерпретировать
следующим образом.
Отобразить все КЕ типа А, которые связаны как минимум с одним КЕ типа Б.
Мощность связи можно корректировать, если включить пункт «Ограничения» в меню настройки связи. Возможные значения:
- любое натуральное число;
- начальное значение может быть
0; - конечное значение может быть бесконечностью
*; - конечное значение не может быть меньше начального.
Сохранение поиска
Построенный TQL можно сохранить для дальнейшего использования по кнопке Сохранить.
Фильтрация
Фильтр TQL – это логическое выражение над свойствами КЕ, которое применяется к отдельному узлу TQL. Фильтры задаются в двух местах:
| Где используется | Когда применяется | Результат |
|---|---|---|
| В билдере TQL | Сохраняется в TQL-запросе и применяется при каждом его выполнении | Определяет, какие КЕ войдут в результат TQL |
| На графе (расширенный TQL фильтр) | Задается поверх выполненного запроса, сам запрос при этом не изменяется | Ограничивает состав КЕ и связей, отображаемых на графе |
В обоих случаях условия создаются в одном конструкторе. При пост-фильтрации на графе дополнительно доступно условие CI (Конкретная КЕ).
Фильтрация в билдере TQL
В билдере фильтр задается отдельно для каждого узла TQL. Условия применяются ко всем КЕ выбранного ТКЕ.
Чтобы открыть фильтр, наведите курсор на узел, нажмите кнопку с иконкой шестеренки и выберите «Редактировать».
В окне фильтра доступен переключатель «Добавлять в результат запроса»:
- если переключатель включен, найденные КЕ узла добавляются в результат;
- если переключатель выключен, узел и его условия продолжают участвовать в выполнении TQL, но найденные КЕ этого узла не добавляются в результат.
После настройки условий нажмите «Применить».
Настройка условий фильтрации
Если условий еще нет, нажмите кнопку «Добавить группу» – будет создана корневая группа условий. Внутри группы нажмите «+» и выберите нужный пункт.
Доступны следующие пункты:
- Добавить условие (Атрибут) – отбор КЕ по значению выбранного атрибута;
- Добавить условие (Статус КЕ) – отбор по текущему статусу КЕ;
- Добавить условие (Статус ИЗ) – отбор по значению выбранного Индикатора здоровья;
- Добавить условие (CI) – отбор по конкретным КЕ, доступно только при пост-фильтрации на графе;
- Добавить группу – вложенная группа условий со своим логическим оператором.
Чтобы удалить условие или группу, нажмите кнопку с иконкой корзины.
Условие по атрибуту
Условие по атрибуту настраивается последовательно:
- Выберите атрибут КЕ.
- Выберите оператор.
- Укажите значение, если оно требуется выбранному оператору.
Список атрибутов формируется из атрибутов, настроенных для ТКЕ выбранного узла. Набор доступных операторов и формат значения зависят от типа значения атрибута.
| Оператор | Описание |
|---|---|
| Равно | Значение атрибута равно указанному значению. Для списка строк списки сравниваются целиком, без учета порядка элементов. |
| Не равно | Значение атрибута не равно указанному значению. |
| Больше чем | Значение атрибута больше указанного значения. |
| Меньше чем | Значение атрибута меньше указанного значения. |
| Больше либо равно | Значение атрибута больше указанного значения или равно ему. |
| Меньше либо равно | Значение атрибута меньше указанного значения или равно ему. |
| Между | Значение атрибута попадает в указанный диапазон, границы диапазона включаются. |
| Содержится | Значение атрибута совпадает с одним из значений указанного списка. |
| Содержит | Список строк содержит указанное значение. |
| Не содержит | Список строк не содержит указанного значения. |
| Поиск по подстроке | Текстовое значение атрибута содержит указанную подстроку, регистр символов не учитывается. |
| Не заполнен | У атрибута отсутствует значение. |
| Заполнен | Атрибуту присвоено значение. |
| Пустая строка | Значением атрибута является строка нулевой длины. |
| Не пустая строка | Значением атрибута является непустая строка. |
| Пустой список | Значением атрибута является пустой список. |
| Не пустой список | Значением атрибута является непустой список. |
| Содержится и не равен | Адрес или сеть атрибута входит в указанную сеть и не совпадает с ней. |
| Содержится или равен | Адрес или сеть атрибута входит в указанную сеть или совпадает с ней. |
| Содержит и не равен | Сеть атрибута включает указанный адрес или сеть и не совпадает с ним. |
| Содержит или равен | Сеть атрибута включает указанный адрес или сеть или совпадает с ним. |
SQL условие ($1) | Для выбранного атрибута применяется пользовательское условие PostgreSQL. |
Для операторов «Не заполнен», «Заполнен», «Пустая строка», «Не пустая строка», «Пустой список» и «Не пустой список» значение указывать не требуется.
Отсутствующее значение и пустая строка – разные состояния. Оператор «Не заполнен» проверяет отсутствие значения, а оператор «Пустая строка» – наличие строки нулевой длины.
Доступность операторов
Набор операторов определяется типом значения атрибута.
| Тип значения атрибута | Доступные операторы |
|---|---|
| Строка | Равно, Не равно, Содержится, Поиск по подстроке, Не заполнен, Заполнен, Пустая строка, Не пустая строка, SQL условие |
| Текст | Поиск по подстроке, Не заполнен, Заполнен, Пустая строка, Не пустая строка, SQL условие |
| Целое число, Число с плавающей запятой, Дата и время | Равно, Не равно, Больше чем, Меньше чем, Больше либо равно, Меньше либо равно, Между, Содержится, Не заполнен, Заполнен, SQL условие |
| Логическое значение (Boolean) | Равно, Не заполнен, Заполнен, SQL условие |
| Список строк | Равно, Содержит, Не содержит, Пустой список, Не пустой список, Не заполнен, Заполнен, SQL условие |
| JSONB | Равно, Не заполнен, Заполнен, SQL условие |
| IP адрес/сеть | Равно, Не равно, Содержится и не равен, Содержится или равен, Содержит и не равен, Содержит или равен, Не заполнен, Заполнен, SQL условие |
| Файл | Условия не поддерживаются |
Если у атрибута изменить тип значения, ранее сохраненные условия могут оказаться недопустимыми. Такое условие подсвечивается в конструкторе как недоступное, а выполнение TQL завершается ошибкой.
Способ задания значения
Для условия по атрибуту способ задания значения выбирается переключателем слева от поля значения:
- Литерал – значение вводится вручную. Вид поля определяется типом значения атрибута: строка, число, дата и время, переключатель для логического типа, редактор JSON, а также список значений для оператора «Содержится» и пара полей для оператора «Между»;
- Из списка – значение выбирается из группы «Атрибуты пользователя». В этом случае значение атрибута КЕ сравнивается со значением атрибута пользователя, выполнившего запрос.
Предлагаются только те атрибуты пользователя, тип значения которых совпадает с типом значения выбранного атрибута КЕ. Для оператора «Содержится» выбор из атрибутов пользователя недоступен.
Для операторов «Равно» и «Не равно» значение вводится в поле, построенном по схеме выбранного атрибута, например в виде выпадающего списка для атрибута с перечислением.
В условиях «Статус КЕ», «Статус ИЗ» и «CI» значение всегда выбирается из списка.
SQL условие ($1)
Оператор «SQL условие ($1)» доступен для атрибутов всех типов и позволяет задать условие PostgreSQL для выбранного
атрибута. Условие вводится в SQL-редакторе, который открывается кнопкой в поле значения.
В поле вводится только выражение без ключевого слова WHERE. При выполнении запроса каждое вхождение $1 заменяется
ссылкой на колонку value таблицы значений выбранного атрибута. Таблица значений зависит от типа значения атрибута,
например для строкового атрибута это string_values.
Например, для атрибута name типа «Строка» задано условие:
$1 = 'any_name'
Значения атрибутов хранятся отдельно от КЕ, поэтому запрос узла логически примет вид:
SELECT cis.id
FROM cis
JOIN ci_attribute_values ON ci_attribute_values.ci_id = cis.id
AND ci_attribute_values.attribute_id = '<идентификатор атрибута name>'
JOIN string_values ON string_values.id = ci_attribute_values.value_id
WHERE string_values.value = 'any_name';
Фактический запрос сложнее: он строится по всей топологии TQL и содержит дополнительные таблицы и служебные условия.
Пример показывает только принцип подстановки $1.
В SQL-условии можно использовать конструкции PostgreSQL, допустимые в выражении WHERE для выбранной колонки.
Плейсхолдер $1 можно использовать в выражении несколько раз.
При нажатии кнопки «Применить» SQL-условия проверяются на сервере. Условие с ошибкой подсвечивается, а фильтр не применяется.
Условие по статусу КЕ
Условие «Статус КЕ» отбирает КЕ по их текущему статусу. Доступны операторы «Равно» и «Содержится». Значение выбирается из списка статусов:
NOT_CONF;N/A;OK;WARNING;ERROR;CRITICAL;MAINTENANCE.
Например, условие «Статус КЕ – Равно – OK» оставит только КЕ со статусом OK.
Статус КЕ вычисляется как максимальное значение среди Индикаторов здоровья КЕ, доступных пользователю на чтение. КЕ, у которых нет ни одного доступного Индикатора здоровья, условию не удовлетворяют.
Условие по статусу ИЗ
Условие «Статус ИЗ» отбирает КЕ по состоянию конкретного Индикатора здоровья.
Чтобы настроить условие:
- Выберите Индикатор здоровья. В списке предлагаются ИЗ, привязанные к ТКЕ выбранного узла.
- Выберите оператор. Доступны «Равно» и «Содержится».
- Укажите значение. Используется тот же список статусов, что и в условии «Статус КЕ».
Условие применяется к выбранному Индикатору здоровья, а не к общему статусу КЕ. Учитываются только Индикаторы здоровья, доступные пользователю на чтение. Если у ТКЕ узла нет ни одного Индикатора здоровья, пункт меню недоступен.
Логические операторы и группы
Условия внутри группы объединяются одним из логических операторов, который выбирается в заголовке группы:
- И – КЕ должна соответствовать всем условиям группы;
- ИЛИ – КЕ должна соответствовать хотя бы одному условию группы.
По умолчанию используется оператор И.
Группы можно вкладывать друг в друга. Вложенная группа обрабатывается как отдельное выражение – аналогично выражению в скобках.
Например:
Название содержит подстроку «service»
И
(
Статус КЕ = WARNING
ИЛИ
Статус КЕ = ERROR
)
В результате останутся КЕ, название которых содержит service, а статус имеет значение WARNING или ERROR.
Пост-фильтрация TQL запросов
Пост-фильтрация («Расширенный TQL фильтр») позволяет ограничить результат уже выполненного запроса, не изменяя сам TQL-запрос. Условия задаются для выбранных узлов TQL, объединяются с собственными условиями этих узлов по И, после чего запрос выполняется заново. Сохраненный TQL-запрос при этом не изменяется.
Используйте пост-фильтрацию, когда результат запроса содержит слишком много КЕ и связей и требуется временно оставить на графе только интересующие данные.
Чтобы открыть пост-фильтр:
- Выполните TQL-запрос.
- На панели инструментов над графом нажмите кнопку с иконкой воронки – «Расширенный TQL фильтр».
- Нажмите «Добавить» и выберите узел TQL, к которому требуется применить фильтр.
Для одного узла задается один набор условий. Чтобы ограничить несколько узлов, добавьте их по очереди. Условия по атрибутам, статусу КЕ и статусу ИЗ, а также группы И и ИЛИ настраиваются так же, как в билдере.
При пост-фильтрации дополнительно доступно условие CI (Конкретная КЕ). КЕ выбираются из числа найденных этим узлом в текущем результате. Условие использует единственный оператор «Содержится», указать можно несколько КЕ.
Пример фильтрации по конкретной КЕ
Рассмотрим пример фильтрации графа интеграционной шины FESB:
- Изначальный граф содержит множество взаимосвязанных объектов, что затрудняет анализ.
- В пост-фильтре выбирается узел FESB.
- Добавляется условие CI (Конкретная КЕ).
- Выбирается оператор «Содержится».
- Указывается значение «192.168.162.50:80 (fesb-pamir-1)».
- Нажимается кнопка «Применить».
В результате на графе останется выбранная КЕ и связанные с ней объекты, соответствующие топологии TQL. Ветви, которые не соответствуют условию, будут скрыты.
Чтобы удалить условия пост-фильтрации и вернуть исходное отображение графа, нажмите «Сбросить».
Такой же фильтр доступен на вкладках дашбордов – кнопка с иконкой воронки на панели вкладки. В отличие от фильтра на графе БДКЕ он сохраняется в настройках вкладки и применяется при каждом ее открытии.
Использование TQL для формирования шаблонов
Для разрешения шаблонов Памир использует шаблонизатор Jinja. Подробную документацию по нему вы можете прочитать на официальном сайте Jinja.
Памир использует квадратные скобки [ ] для подстановки выражений и переменных.
Ссылки на узлы TQL
Для адресации к экземплярам узла TQL нужно использовать идентификатор ноды в TQL запросе и название ТКЕ.
Строго говоря,
указывать ТКЕ - не обязательно, достаточно перед идентификатором ноды написать символ _. Но для лучшей читаемости
шаблона рекомендуется указывать название ТКЕ.
[[configuration_item_1]]
Ссылка на узел TQL не используется само по себе. Она применяется для получения атрибутов и полей КЕ.
Атрибуты
Для адресации к полям КЕ используется ключевое слово attributes
[[configuration_item_1.attributes.name]]
Поля
Для адресации к полям КЕ используется ключевое слово fields
ci_id- идентификатор КЕci_name- наименование КЕ, полученное в результате применения правил наименованияci_type_name- название ТКЕ
Идентификатор КЕ
[[configuration_item_1.fields.ci_id]]
Наименование КЕ
[[configuration_item_1.fields.ci_name]]
Название ТКЕ
[[configuration_item_1.fields.ci_type_name]]
Функции
set_if_not_value– установить указанное значение при отсутствии значения у переменной, аргумент - значение которое нужно использовать;
[[configuration_item_1.attributes.name|set_if_not_value("n/a")]]
skip_if_not_value– пропустить при отсутствии у переменной значения (подставит пустую строку), аргументов нет;
[[configuration_item_1.attributes.name|skip_if_not_value]]
datetimeformat– значение переменной в формате iso даты преобразовать в указанный формат, аргумент - строка с форматом вывода даты (в виде кодов C стандарта), по умолчанию используется "%d %B %Y %H:%M";
[[configuration_item_1.attributes.date|datetimeformat]]
[[configuration_item_1.attributes.date|datetimeformat("%d.%B.%Y")]]
fresh- [ добавить описание ]grouped- [ добавить описание ]
[ добавить описание использования пробелов ]