Руководство пользователя для модуля диспетчерского управления

Модуль диспетчерского управления (МДУ) предназначен для создания сценариев автоматического реагирования на изменение показателей.

Он состоит из нескольких логических элементов:

Конфигурация событий и сценариев
Реестр событий
Реестр задач

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

1. МДУ, Конструктор сценариев управления

Сценарии управления представляют собой основной компонент МДУ. Сценарий управления — это набор условий и правил, который позволяет найти событие в потоке данных из подсистемы. Данные из подсистемы должны быть предварительно приведены к общим типам (см. 4. Общие типы данных). Это позволяет обрабатывать данные из разных подсистем как единый массив данных, не делая дублирующихся правил и сценариев для каждой из них.

Сценарий состоит из:

Общие свойства
Триггеры запуска сценария (события, условия)
Последовательность шагов (мероприятий, действий)

Сценарий считается активным, если есть зафиксированные события в пределах интервала событий.

1.1. Общие свойства сценария

Включен — включен или выключен сценарий.
Название — короткая строка, отображаемая в списке сценариев.
Описание — большое текстовое поле, в котором можно писать, для чего предназначен этот сценарий и какие примечания к нему относятся.
Тип данных — общий тип данных, для которого написан данный сценарий.
Подсистема — если данные поступают из разных подсистем, то здесь можно дополнительно отфильтровать их по признаку подсистемы.
Глубина сканирования при поиске событий. При запуске сценариев из базы данных будут получаться последние данные за этот период времени для поиска в них событий, отвечающих условиям сценария.
Интервал событий. Этот параметр также отвечает за период запуска проверки условий сценария для нахождения событий. События, зарегистрированные в процессе работы сценария, будут происходить не чаще этого интервала.
Что сравнивать. Данные можно сравнивать как между собой, так и историю изменения каждого элемента. В случае форм ввода данных данные обычно целесообразно сравнивать между собой. В случае, если это оборудование, например метеостанция, то данные нужно сравнивать в истории изменений.
Идентификатор и префикс для экспорта — это неизменная строка, состоящая из определенного набора символов (латиница в нижнем регистре и знак подчеркивания, не начинается с цифры), задается вручную или может быть сгенерирована автоматически из названия. Это позволяет переносить сценарии реагирования между серверами ИТС (тестовыми и боевыми), делиться ими между собой, не боясь конфликтов при импорте. Если бы идентификаторы задавались автоматически, то при переносе было бы непонятно — один и тот же это сценарий или два разных. Если изменить идентификатор и нажать на кнопку «Сохранить», то будет создана новая копия сценария с другим ID. Эта функция позволяет делать дубликаты сценария при необходимости.

1.2. Условия сценария

Представляют собой набор логических и математических выражений, предназначенных для нахождения событий в потоке данных данного общего типа.

Условия бывают следующих типов:

Группа условий
Отклонение показателя (дифференциальное условие)
Изменение показателя (дискретное условие)
Изменение статуса
Отсутствие данных
Отклонение от тренда

В сложных сценариях реагирования настройка правил может быть неочевидной и запутанной. После формирования условий МДУ формирует описание настроенных правил на русском языке, чтобы оператору было понятнее, что он настроил в итоге.

У многих условий есть такие параметры:

Поле в Mongo — это то поле, для которого будет составлен данный сценарий.
Префикс — это префикс, который будет использоваться для создания названий переменных сценария (см. 1.3.1. Переменные сценария). Он должен быть заполнен, и у каждого условия должен быть уникальный префикс, иначе его переменные будут недоступны.
JMESPath поле — в этом поле можно переопределить условие для выборки данных из объекта в потоке данных. В большинстве случаев его нужно оставлять незаполненным. МДУ автоматически определяет, как получить данные из указанного вами поля Mongo. Оно может быть полезным в небольшом числе специфических случаев, например, если поле Mongo является массивом и нужно выбрать один из его элементов.

1.2.2. Отклонение показателя (Дифференциальное условие)

Сравнивает изменение двух средних величин на одном и том же устройстве. Позволяет отследить резкий рост или падение одного из параметров. Это условие может быть применено только к числовым полям общих типов.

На рисунке ниже изображено изменение одного из параметров на одном из устройств в потоке данных. Синие параметры находятся в условном будущем, зелёные — в условном прошлом, красной точкой отмечено отсутствие данных.

Это условие позволяет отследить:

Прирост величины на определенное количество единиц.
Падение величины на определенное количество единиц.
Прирост величины на определенное количество процентов.
Падение величины на определенное количество процентов.
Среднее значение ниже минимума.
Среднее значение выше максимума.
Исключить 0 и пустые значения

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

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

Вычисление этого условия работает следующим образом:

Для каждого из устройств берется набор данных из прошлого на глубину сканирования.
Граница условного настоящего перемещается в наборе этих данных.
Берется набор точек в условном прошлом и будущем (по возможности ближе к максимуму, но не ниже минимума) по условиям для выборки этих точек.
Считается средняя величина показателя в условном прошлом и условном будущем и сравнивается между собой по указанным критериям.

Данный тип условий позволяет определить резкий прирост или падение одного из параметров. Это может быть использовано, например, для определения начала пробок в час пик. В этот момент количество проехавших ТС через транспортный детектор должно резко упасть.

1.2.3. Изменение показателя (Дискретное условие)

При этом сравнении выполняются проверки для всех прошлых и/или будущих значений в отдельности.

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

В зависимости от типа данных поля (строка, число, массив), к которому будет применяться данное условие, могут быть доступны следующие операции:

Равно
Не равно
Меньше
Меньше или равно
Больше
Больше или равно
Начинается с
Не начинается с
Заканчивается на
Не заканчивается на
Содержит
Не содержит
Регулярное выражение
Не регулярное выражение
Длина массива
Входит
Не входит
Null
Не null
Появилось
Исчезло

Эти операции могут быть объединены в логические группы. Например, можно написать такое правило. Название метеостанции начинается на "Региональная" без учета регистра и заканчивается на "01" или начинается на "Городская" и заканчивается на "99".

Экспертные настройки позволяют учитывать регистр и наличие пробелов в начале и конце строки.

1.2.4. Изменение статуса

Специальное условие предназначено для полей со статусом оборудования и текстовых полей. При этом сравнении выполняются проверки для всех прошлых и/или будущих значений в отдельности. Позволяет зафиксировать изменение статусов. В отличие от дискретных условий, в этом условии можно указать расшифровку статусов на русском языке и использовать её в переменных сценария. Например, чтобы отправить сообщение: "Статус метеопоста "123" был "Онлайн", а стал "Оффлайн" в 14:00 01.02.2024".

Экспертные настройки позволяют не исключать 0 и пустые значения, учитывать регистр и наличие пробелов в начале и конце строки.

1.2.5. Отсутствие данных

В настройках сценария можно выбрать начало и конец того интервала в течение которого данные могут отсутствовать.

Правила написания интервалов:

-1 — минус одна единица
+1 — плюс одна единица
1 — абсолютное значение
если пропущено, то текущее значение.

Младшие разряды, как правило, нужно фиксировать.

Пример:

Час: 15, Минута: 0, Секунда: 0 — 15:00:00 текущего дня
Час: -1, Минута: 15, Секунда: 0 — 15:00:00 вчера
День: +1, Минута: 15, Секунда: 10 — 15:10:00 завтра
День: -14, День недели: Пн — Текущее время два понедельника назад

Таким образом можно написать любое смещение по времени.

1.2.6. Отклонение от тренда

Позволяет сравнить текущий показатель с типичным показателем для этого часа и дня недели за последнее время. Можно указать, нужно ли делать различия по дням недели. Без экспертных настроек имеет минимум опций.

Например, с помощью этого условия можно определить аномалии в пропускной способности дорог, которые могли возникнуть из-за ДТП.

Методика поиска закономерностей довольно сложная и состоит из двух этапов.

На первом этапе определяется, есть ли вообще какая-нибудь закономерность в данных по указанным параметрам. На втором — попадает ли среднее значение в эту закономерность.

Считается, что закономерность есть, если данные укладываются в Гауссово распределение и относительное среднеквадратичное отклонение не превышает какую-то величину (по умолчанию 34% от математического ожидания). Параметры, которые на это влияют, относятся к экспертным параметрам.

Параметры условия:

Группировка по дням недели — при поиске закономерности нужно ли различать дни недели. Возможны варианты:
- Не учитывать день недели
- Каждый день недели отдельно
- Будни и выходные отдельно
Площадь закономерности — относится к этапу 2. Определяет процент площади под правой и левой частью гауссианы, в которую должно попасть среднее значение. Если среднее значение не попадет в эту область, то считается, что это отклонение от тренда. По умолчанию 34% слева (это область значений меньше математического ожидания) и 34% справа (это область значений больше математического ожидания) от общей площади. Математически это вероятность отклонения в большую или меньшую сторону от ожидаемого значения.
Шаг группировки — относится к этапу 1. В каком временном диапазоне искать закономерность. Возможны значения: 1 час, 30 минут, 20 минут, 15 минут. По умолчанию 1 час.
Искать закономерность за число дней — относится к этапу 1. Как глубоко в прошлое нужно заглядывать для поиска закономерности. (Практика показала, что повторяемость данных из года в год слабее, чем за последние дни.)
Порог закономерности — относится к этапу 1. Определяет минимальное относительное (относительно математического ожидания) среднеквадратичное отклонение в Гауссовом распределении, при котором можно сказать, что в данных есть закономерность. (Является мерой отклонения от Гаусова распределения). По умолчанию 34%.

Можно указать минимум и максимум точек для вычисления средней величины. Можно дополнительно потребовать, чтобы эти точки уложились в определенный интервал времени. Исключить 0 и пустые значения.

1.3. Действия сценария

Если сценарий найдёт событие, описанное в условиях сценария, то далее будут выполнены действия, описанные в действиях конфигурации сценария.

Действия бывают нескольких типов:

Вывести уведомление
Выполнить запрос
Оставить комментарий

Можно назначить несколько действий для одного и того же сценария. У каждого действия могут быть действия, которые выполняются в случае успешного и неудачного выполнения родительского действия. Действия, описанные на одном уровне, выполняются параллельно и независимо друг от друга. Действия, описанные как действия в случае успеха или неудачи, выполняются только после основного действия. Вложенность действий не ограничена.

У действий есть число повторений и интервал повторений. МДУ будет выполнять попытки выполнить действие указанное число раз и заданным интервалом до первого успешного выполнения или до окончания попыток. Действие считается выполненным с ошибкой, если все попытки его выполнить с указанным интервалом закончились неудачно.

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

У всех действий есть экспертные настройки:

Интервал повторений при сбое — если это действие выполнить не удалось, то через этот интервал времени будет выполнена повторная попытка выполнить действие. По умолчанию: 30 секунд.
Повторений при сбое — сколько раз пытаться это действие выполнить повторно при сбое. По умолчанию: 10.

Для действия можно заполнить описание. Это может быть полезно для того, чтобы различать события при просмотре реестра событий. (см. 2. Реестр событий) В описании события можно использовать переменные сценария. (см. 1.3.1. Переменные сценария)

1.3.1. Переменные сценария

В каждом из действий можно использовать переменные сценария. Переменные сценария — это специальные предопределенные строки вида: {{название_переменной}}. Перечень и описание переменных есть в конструкторе действия. Их можно использовать как параметры запроса, если в качестве действия выбран запрос, или как часть текста уведомления, если в качестве действия было выбрано уведомление. Например, вот так:

  Интенсивность увеличилась на 40% на детекторе {{p_d_id}}, адрес: {{p_address}} в {{int_date_local}}.
  Было {{int_was}} тс/ч, стало {{int_became}} тс/ч.

Существуют переменные следующих типов:

Переменные сценария. В этих переменных содержатся данные, которые были созданы программно в процессе выполнения сценария. Например, id события в базе данных МДУ. Переменные, которые были созданы в процессе выполнения условий сценария. Например, если в сценарии есть условие «Отклонение показателя» (Дифференциальное условие), то в переменных будет усредненное значение в прошлом и будущем. Префикс этих переменных будет такой же, как было указано id условия в конструкторе условий. Изменение префикса доступно только в экспертном режиме.

Переменные объекта. Это переменные, в которых содержится информация о свойствах объекта, удовлетворяющего всем условиям сценария. Их состав зависит от того, для какого общего типа написан этот сценарий.

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

1.3.2. Действие: вывести уведомление

Выводит уведомление в ИТС. У этого действия есть следующие параметры:

Уровень уведомления: Информирование, Требует внимания оператора, Ошибка, Успешное выполнение. Этот уровень определяет цвет и оформление уведомления в списке уведомлений. Цветовая градация привязана к типам, чтобы вызывать правильные ассоциации с цветами, используемыми в системе. Например, если оператор увидит жёлтое уведомление, то это будет значить, что требуется его реакция и дальнейшее выполнение каких-то действий.
Привилегия, которой должен обладать оператор для того, чтобы увидеть это уведомление.
Скрывать через: Время, через которое это уведомление будет удалено автоматически.
Заголовок уведомления. Здесь можно использовать переменные сценария.
Текст уведомления. Здесь можно использовать переменные сценария.
Ссылка для перехода. Здесь можно использовать переменные сценария. Если она указана, то при клике по уведомлению произойдёт переход по этой ссылке.
Теги. Специальные теги, определяющие особенности показа уведомления. Сейчас доступен тег `open`: если он указан, то список уведомлений откроется при получении этого уведомления.

2. Реестр событий

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

Этот раздел создан в основном в отладочных целях.

У события есть свойства:

Id.
Статус события.
Тип данных.
Название сценария, с которой связано данное событие.
Id сценария, с которой связано данное событие.
Id устройства, с которым связано это событие.
Дата события – это дата и время, которая была у данных в потоке данных.
Дата регистрации – это дата и время фактической регистрации события.

У событий есть статусы:

Запланировано – это значит, что по данному событию будут выполняться действия, описанные в сценарии.
Пропущено – это событие было пропущено. Такое происходит, когда событие наступает чаще, чем это было указано в параметре интервал событий (в настройках сценария).

По запланированным событиям можно посмотреть подробную информацию, в которой, помимо всех свойств события, будет содержаться:

1. Описание события с подставленными переменными

2. Значения, которые участвовали в выборке для каждого из условий сценария. На основании этих значений МДУ было принято решение о наступлении события. Это состояние потока данных в момент фиксации события.

3.Параметры события. Это набор параметров и их значений в момент события. Здесь можно посмотреть значения этих параметров, чтобы более четко представлять, какие из них могли бы пригодиться в действиях и при показе уведомлений.

4. Конфигурация сценария в момент фиксации события. Приведена в отладочных целях. Её можно сравнить с текущей конфигурацией.

Для пропущенных событий эта информация не сохраняется в целях экономии места на диске.

События можно фильтровать по различным признакам. Из контекстного меню в разделе МДУ можно найти все события данного сценария. Из контекстного меню и карточки события можно перейти к конфигурации связанного сценария или найти все задачи данного события. Из контекстного меню событие можно вызвать повторно.

3. Реестр задач

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

У задачи есть следующие свойства:

Id.
Тип задачи. Совпадает с типом действия.
Статус.
Тип данных.
Название сценария, с которой связано данное событие.
Id сценария, с которой связано данное событие.
Id события, с которым связана эта задача
Id родительского действия, если это действие в случае успеха или неудачи одного из действий
Статус родительского действия, если это действие в случае успеха или неудачи одного из действий
Осталось повторов
Интервал повторов
Дата регистрации
Дата обновления
Дата следующего запуска

Пример конфигурации задачи:

У задачи могут быть статусы:

Запланировано — еще не выполнялась
Выполняется — в ходе выполнения
Выполнено — успешное выполнение
Сбой — одна из попыток выполнить действие была неудачной, но можно повторять еще
Не выполнено окончательно — все попытки исчерпаны, действие не выполнено

Задачи можно фильтровать по различным признакам. Из контекстного меню в разделе «События», можно найти все задачи данного события. Из контекстного меню и карточки задачи можно перейти к событию этой задачи или найти все задачи данного события. Из контекстного меню задачу можно запустить повторно.

4. Общие типы данных

Общие типы данных — это внутренний формат хранения и обработки данных в системе ИТС. Он позволяет обрабатывать данные от различных устройств или подсистем схожего назначения, но разных моделей, как единый поток данных, поступающий в систему. Хорошим примером могут быть метеостанции разных производителей. Методы получения данных из метеостанции могут быть разными, как и названия полей, в которых содержатся те или иные показатели. Но после приведения к общим типам данных показатели всех метеостанций будут храниться в одних и тех же полях. Например, одна метеостанция отдавала температуру в поле temperature в градусах Цельсия, вторая — в поле temp по Фаренгейту, после приведения к общим типам показатель температуры будет храниться в поле t в градусах Цельсия. Сейчас в общем типе Meteo может содержаться 75 различных показателей, которые могут измерять метеостанции, большинство из них необязательные, потому что не все метеостанции могут измерять их все.

Появление общих типов обусловлено тем, что данные проще привести к общему виду на входе в ИТС, чем каждый раз писать специальные условия для каждой из метеостанций.

Данные к общим типам приводятся адаптерами.

Накопленные данные общих типов при наличии специальной привилегии можно посмотреть в разделе "Сервисы обмена данными / Данные общих типов".

5.2. Резервное копирование сценариев МДУ.

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

Пример сохраненных версий сценария.

  dc_detector_status-20241203_1759-8d324e06d92e772130802153322d5e3f.json
  dc_detector_status-20241204_1752-8d4ae95e2d39196f3d9459e2f6582299.json
  dc_detector_status-20250130_1639-07e2d151dd31937fb8d62162719797c7.json

Видно, что у сценария с id detector_status есть три версии:

От 2024.12.03 17:59
От 2024.12.04 17:52
От 2025.01.30 16:39 — последняя и актуальная версия.

Их можно загрузить в разделе МДУ. Для этого у файла должен быть префикс dc_ и расширение .json.

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

6. Системные требования МДУ

Если настроить сценарий неправильно, то МДУ в процессе работы может быстро переполнить жёсткий диск.

При фиксации события размер одного события на диске примерно 60 Кб.

Например: если сценарий обрабатывает 1000 устройств и по ним происходят события каждые 5 минут на глубину 30 дней, то это будет около 500 Гб дискового пространства. Это не типичный случай. Если события и правда нужно фиксировать так часто, то лучше уменьшить глубину их хранения в настройках крона (см. 5.3. Очистка старых событий и задач МДУ). В типичном случае на один сценарий нужно около 2 Гб на глубину 30 дней.