Уведомления

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

Для этого и существует система уведомлений js-контроллера. Она собирает такие сообщения, отображает их в панели администратора и делает доступными для адаптеров, которые их пересылают.

Как пользователь их видит

В панели администратора, на вкладке Хосты, каждый хост отмечен значком, указывающим количество открытых уведомлений. Нажатие на этот значок открывает диалоговое окно Уведомления для конкретного хоста: по одной вкладке на каждую категорию, содержащее уведомления, сгруппированные по экземплярам, каждое с меткой времени. Кнопка Подтвердить очищает уведомления для данной категории.

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

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

Зарегистрируйте свои категории

Адаптер, желающий генерировать собственные сообщения, описывает свои категории в io-package.json в notifications. Структура двухуровневая: область видимости с несколькими категориями.

"notifications": [
  {
    "scope": "meinAdapter",
    "name": {
      "en": "My adapter",
      "de": "Mein Adapter"
    },
    "description": {
      "en": "Notifications of my adapter",
      "de": "Meldungen meines Adapters"
    },
    "categories": [
      {
        "category": "loginFailed",
        "name": {
          "en": "Login rejected",
          "de": "Anmeldung abgelehnt"
        },
        "description": {
          "en": "The service rejected the stored credentials.",
          "de": "Der Dienst hat die hinterlegten Zugangsdaten abgelehnt."
        },
        "severity": "alert",
        "regex": [],
        "limit": 3
      }
    ]
  }
]

Поля категории:

Что касается выбора уровня: alert предназначен для действий, которые необходимо выполнить для обеспечения дальнейшего функционирования системы. notify предназначен для действий, которые необходимо знать. info предназначен для всего остального. Объявление всего уровня alert приведет лишь к тому, что пользователь в конечном итоге закроет диалоговое окно, не прочитав его.

Отправить сообщение

Во время выполнения программы достаточно одного вызова:

await this.registerNotification('meinAdapter', 'loginFailed',
    'Die Anmeldung wurde abgelehnt. Bitte Zugangsdaten prüfen.');

Три основных элемента информации - это область, категория и текст для пользователя.

Текст должен объяснять, что нужно делать, а не просто рассказывать о том, что пошло не так.

Если категория null пройдена, система проверяет сообщение на соответствие шаблонам regex данной области и самостоятельно сортирует его.

Четвертый параметр может предоставлять дополнительную информацию (contextData), которую могут оценивать адаптеры пересылки.

Что должно быть в уведомлении, а что нет

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

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

Временные сбои бесполезны. Соединение, которое восстанавливается через десять секунд, должно быть зафиксировано в журнале и в info.connection, а не в диалоговом окне уведомления.

Разграничение

Адаптер может взаимодействовать тремя способами, и их часто путают:

Сообщения о сбоях - это совсем другое: они отправляются разработчику, а не пользователю. См. Отчеты о дорожно-транспортных происшествиях.