Версия: 8.6

Управление агентами

Агент — это специальная программа, которую можно установить на удаленное устройство с целью сбора данных и выполнения каких-либо действий (полный список поддерживаемых платформ).

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

Задания могут быть самого разного рода: запустить bash или PowerShell - скрипт, обратиться к HTTP REST интерфейсу, выполнить запрос к СУБД.

Для ускорения работы и упрощения написания заданий для агентов, используются плагины.
Плагины бывают как встроенные (например, плагин для работы с HTTP или плагины работы с наиболее популярными версиями СУБД), так и устанавливаемые на агенте отдельно (например, для сбора данных из Zabbix).

Также следует отметить, что мы предоставляем возможность разрабатывать собственные плагины самостоятельно, что бывает полезно в ряде случаев. Например, написать кастомный плагин для взаимодействия со специфической системой бронирования билетов.
Инструкция по написанию плагинов (github).

Подключение агентов к платформе Monq осуществляется через координатор по HTTPS протоколу, используя API-ключ для авторизации.

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

Основные возможности агентов:

Обработка поступающих сценариев заданий
Генерация результирующего артефакта и отправка его в потоки данных
Прямой запуск команд взаимодействия с консолью ОС (sh, bash, windows command, powershell)
Запуск параллельного выполнения нескольких заданий
Подключение плагинов интеграций, таких как Zabbix, Kubernetes, vCenter, PostgreSQL, SCOM, Nagios и другие

По умолчанию все задания выполняются на системном агенте

Системный агент получает задания от системного координатора, имеющего метку SharedAgents

Подключение внешних агентов к системному координатору недоступно

Экран «Управление агентами»

Экран управления агентами и координаторами находится в разделе главного меню «Сбор данных (ETL)» → «Управление агентами» и содержит следующие вкладки:

Координаторы
Агенты

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

Доступ к экрану регулируется ролевой моделью: права зависят от назначенной пользователю роли.

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

Координаторы

На вкладке «Координаторы» пользователю доступны следующие возможности:

Просмотр списка созданных координаторов
Поиск и фильтрация координаторов в списке
Выполнение действий с координаторами из списка
Переход в карточку координатора
Создание нового координатора

Список координаторов

На вкладке «Координаторы» представлена таблица со списком существующих координаторов. Таблица имеет следующие поля:

Название: рядом с названием расположена иконка-индикатор активности координатора
Метки: рядом с названием метки присутствует иконка , сообщающая о принадлежности метки координатору. Также отображается числовая индикация общего количества меток координатора. Клик по ней раскрывает список всех меток.
API-ключ
Состояние: отображает текущее состояние ВКЛ/ВЫКЛ и позволяет его переключить

Системный координатор в списке не отображается

Поиск координаторов

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

Строка поиска
Позволяет фильтровать список по полям «Название», «Описание» и «API-ключ»
Рубрикатор
Предоставляет возможности фильтрации по параметрам:
- Состояние: запущен или остановлен
- Метки: отображается до 5 меток текущего контекста (с возможностью развернуть полный список или найти через строку поиска)

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

Создание координаторов

Нажмите в верхнем правом углу экрана «Создать координатор».
Заполните поля:
- Владелец
- Название координатора
- Добавьте метки
  Метки используются для распределения заданий потоков данных между координаторами
  При добавлении метки на координатор, она автоматически присваивается всем подключенным к нему агентам.
  при добавлении метки SharedAgents к созданному координатору
  планировщик распределит запуск заданий с меткой SharedAgents (установленной по умолчанию) также и на подключенные агенты.
  При подключении агента, координатор также запоминает и хранит в себе набор персональных меток всех подключенных к нему агентов.
Нажмите «Создать»

Готово! Новый координатор создан, API-ключ для подключения агентов скопирован в буфер обмена.

Настройка координаторов

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

В верхней части экрана карточка содержит:

«Хлебные крошки», с возможностью вернуться на вкладку «Координаторы»
Название координатора с иконкой-индикатором состояния: «Запущен» / «Остановлен»
API-ключ, с возможностью его копирования в буфер
Количество активных агентов координатора, с возможностью перехода к ним
При переходе откроется вкладка «Агенты» с выбранным координатором и состоянием «Запущен» (даже если агентов 0)
Управление состоянием: Остановить/Запустить
Дополнительные действия , такие как остановка координатора, копирование API-ключа, перевыпуск API-ключа и удаление координатора

Основная информация

Владелец: выбирается из списка РГ, в которых у пользователя есть право на редактирование раздела «Координаторы агентов»
Название: должно быть уникальным в рамках РГ
Описание
Метки: позволяют назначать координатору собственные идентификаторы, которые автоматически распространяются на все подключенные к нему агенты, обеспечивая их удобную идентификацию и фильтрацию.
Особенности работы с метками:
- Добавление меток возможно из списка уже доступных в контексте владельца координатора или создание собственных уникальных меток
- Метки чувствительны к регистру: «Метка» и «метка» - считаются разными
- Нельзя добавить одинаковую метку дважды на один координатор
- При смене РГ координатора уже назначенные метки сохраняются
- Установленные на координаторе метки автоматически наследуются всеми подключенными к нему агентами
- Чтобы метка добавилась, после ее ввода нажмите Enter или пробел
- Чтобы добавить метку с пробелом в названии, используйте copy-paste
- Чтобы удалить метку, нажмите на иконку крестика рядом с ее названием

Конфигурации агентов

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

Конфигурация распределяется на агент по аналогии с заданиями, однако выполняется непрерывно, занимая слот агента.

Создание новой конфигурации

Нажмите «Создать конфигурацию»
После создания конфигурация сразу появляется в списке и отрывается боковая панель с настройками:
- Состояние конфигурации
- Название — автоматически присваивается «Новая конфигурация агента [N]», где N — порядковый номер новой конфигурации. Название должно быть уникальным в пределах одного координатора
- Описание — произвольный текст для удобства идентификации
- Метки агентов — определяют, каким агентам будет выдаваться конфигурация
  - «Агент содержит любую метку из списка» - применяется логический оператор «ИЛИ»
  - «Агент содержит все метки из списка» - применяется логический оператор «И»
    - Если агент имеет все указанные метки + еще какие-то - он все равно получит такую конфигурацию
    - Если хоть одна метка не существует - конфигурация не будет выдана, т.к. агент не найдется
  - Несуществующая метка помечается особым образом, и при сохранении пользователь увидит предупреждение
    Такая метка может стать валидной, если впоследствии подключится агент с этой меткой
  - Можно указать одну или несколько меток
  - Метки чувствительных к регистру
- Содержимое файла конфигурации - YAML-скрипт определяет логику работы на стороне агента. По умолчанию пустой.
  Пользователю доступна опция «Проверить код»: она включает в себя базовую проверку структуры и синтаксиса правил написания кода на языке YAML, а также важные кастомные настройки:
  - Наличие единственного узла continuous-jobs.
    Использование jobs или комбинации jobs и continuous-jobs - недопустимо
  - Внутри continuous-jobs должен быть непустой список шагов init-step
  - Внутри каждого шага обязателен узел plugin
  При сохранении конфигурации проверка кода выполняется автоматически.
  При обнаружении ошибок отображается сообщение с указанием строк, где найдена проблема. Если скрипт корректен, выводится «OK».
По завершении настройки сохраните конфигурацию

Сразу после сохранения новая конфигурация отображается в конце списка. При обновлении страницы конфигурации сортируются по алфавиту

Изменение существующей конфигурации

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

Поведение агентов при сохранении изменений:

Название или описание: не влияет на выполнение конфигурации
Изменение логики меток:
- Агенты прекращают выполнение конфигурации, если они перестали удовлетворять обновленным условиям
- Агенты продолжают выполнение конфигурации, если они продолжают удовлетворять обновленным условиям
- Агенты начинают выполнение конфигурации, если теперь они соответствуют новым условиям
Изменение YAML-скрипта:
Все выполнявшие конфигурацию агенты, автоматически останавливают ее и сразу же запускают заново по обновленному скрипту

перезагрузка агентов не требуется

все изменения применяются динамически

Если координатор остановлен

рядом с кнопкой сохранения конфигурации будет доступна опция «Запустить координатор»

Внесенные изменения можно отменить в любой момент до сохранения

Запуск и остановка конфигурации

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

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

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

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

Удаление конфигурации

Выберите удаляемую конфигурацию
В боковой панели нажмите меню дополнительных действий → «Удалить»
Во всплывающем окне подтвердите удаление

Запуск и остановка координаторов

После создания нового координатора он переходит в состояние «Запущен» автоматически. Координатор сразу начинает распределять задания на подключенные к нему агенты.

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

Кнопка запуска в списке координаторов находится в столбце «Состояние», а в личной карточке - в правом верхнем углу экрана.

Состояние координатора напрямую влияет на выполнение конфигураций агентов

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

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

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

Перевыпуск API-ключа

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

Кнопка перевыпуска находится в меню дополнительных действий → «Перевыпустить API-ключ»

После перевыпуска API-ключа

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

Удаление координаторов

Удаление координатора доступно как из общего списка координаторов, так и из его личной карточки.

Кнопка удаления находится в меню дополнительных действий → «Удалить»

при удалении координатора

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

Агенты

На вкладке «Агенты» пользователю доступны следующие возможности:

Просмотр списка агентов
Поиск и фильтрация агентов в списке
Выполнение действий с агентами из списка
Переход в карточку агента
Создание нового координатора

Список агентов

На вкладке «Агенты» представлена таблица со списком существующих агентов. Таблица имеет следующие поля:

Название: слева от названия расположена иконка-индикатор активности агента, справа - его версия, а снизу - описание (при наличии)
Тип: статический/динамический
IP-адрес хоста, на котором установлен агент
Координатор, к которому подключен агент
Метки: личные и унаследованные от координатора (отмечаются иконкой ).
Справа отображается общее количество меток, а клик по нему раскрывает полный список.
Конфигурации: рядом с названием присутствует иконка, сообщающая о типе конфигурации. Справа отображается общее количество конфигураций агента, а клик по нему раскрывает полный список.
Слоты: отображается общее число слотов в круговой диаграмме, разбитой на аналогичное количество частей. Цвета диаграммы соответствуют типам конфигураций, занимающих слоты.

системный агент

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

Поиск агентов

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

Строка поиска
Позволяет фильтровать список по полям «Название», «Описание» и «IP-адрес»
Рубрикатор
Предоставляет возможности фильтрации по параметрам:
- Состояние: запущен или остановлен
- Тип: статический или динамический
- Координатор, к которому подключен искомый агент
- Метки: отображаются личные метки агентов, а также метки координаторов с отличительной иконкой
- Конфигурации: отображаются конфигурации агентов с соответствующими их типу отличительными иконками

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

Настройка агентов

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

В верхней части экрана карточка содержит:

«Хлебные крошки», с возможностью вернуться на вкладку «Агенты»
Название Агента с иконкой-индикатором состояния: «Запущен» / «Остановлен»
Метки, унаследованные от координатора и личные
Информацию о версии, типе и количестве слотов агента, а также координаторе, к которому он подключен (с возможностью перехода в настройки координатора)
Кнопку «Создать конфигурацию»
Вкладки с настройками и информацией: «Конфигурации», «Плагины» и «Онлайн-логирование»

Если агент отключен

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

Конфигурации

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

Параметры подключения
Отображает конфигурационный файл для подключения агента к координатору. Содержимое файла доступно только для чтения. Редактирование возможно только из локальной директории агента.
Назначенные конфигурации
Помещенная в эту секцию конфигурация занимает один из доступных слотов и начинает выполняться. Если слотов у агента меньше, чем конфигураций, они выполняются в соответствии с приоритетом конфигураций.
Рядом с названием присутствует иконка, сообщающая о типе конфигурации.
При выборе конфигурации открывается ее содержимое.
Неиспользуемые конфигурации
Конфигурации в этой секции игнорируются агентом, независимо от их типа. Перемещать конфигурацию сюда следует, если требуется временно отключить ее выполнение или освободить слот.

Пользователь может назначать или отменять выполнение конфигураций, а также изменять приоритет их выполнения с помощью перетаскивания (drag and drop).

Типы конфигураций

Конфигурация с координатора
Унаследована от координатора согласно настройкам распределения и используется для массовых распределений на агенты с указанными метками или на все подключаемые агенты.
Доступна только для просмотра, а также содержит ссылку для быстрого перехода к настройкам на координаторе.
Личная конфигурация
Создана через web-интерфейс и используется для точечного исполнения рабочей конфигурации одним конкретным статическим агентом. Редактирование доступно только через интерфейс в карточке агента.
Кнопка «Создать конфигурацию» предназначена именно для конфигураций такого типа.
Локальная конфигурация
Располагается в файловой системе агента (не важно, статический он или динамический). Подходит для автономной работы агента, когда нет связи с координатором.
Через веб-интерфейс доступна только для чтения, а изменения вносятся непосредственно в директории агента.

Приоритет конфигураций

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

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

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

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

важно

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

В таком случае при получении агентом новой конфигурации и отсутствии свободных слотов - она будет добавлена в секцию «Неиспользуемые конфигурации».

Смена имени агента сбрасывает внесенные ранее изменения и инициирует его регистрацию с нуля.

Примеры работы приоритетов:

Сценарий 1: У агента 3 слота. При подключении у него есть локальная конфигурация и конфигурация с координатора. Эти конфигурации будут выполнены. Если пользователь создаст личную конфигурацию и сразу применит ее, она займет один из слотов, а другие две конфигурации продолжат выполняться. После перезапуска агента все 3 конфигурации продолжат выполнение.
Сценарий 2: У агента 3 слота, и изначально назначены локальная и конфигурация с координатора. Пользователь добавляет личную конфигурацию, но не активирует ее сразу. После перезапуска агент будет продолжать выполнять локальную и конфигурацию с координатора. Личная конфигурация останется неиспользуемой до ее активации.
Сценарий 3: У агента 3 слота, и пользователь вручную распределил конфигурации между секциями «Назначенные конфигурации» и «Неиспользуемые конфигурации». Например, занял все 3 слота личными конфигурациями. После переподключения агента к системе эти настройки будут сохранены, приоритетность по умолчанию применена не будет. Новые полученные агентом конфигурации добавятся в секцию «Неиспользуемые конфигурации», если свободных слотов нет.

важно

Выполнение конфигурации подразумевает бесконечный процесс и слот всегда будет им занят, поэтому количество мест в секции «Назначенные конфигурации» напрямую зависит от количества слотов агента.

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

Личная конфигурация

Личная конфигурация создается и управляется через интерфейс карточки агента. Эта функция доступна только для статических агентов.

Создание личной конфигурации
Для создания личной конфигурации выполните следующие действия:
1. Нажмите «Создать конфигурацию» в карточке агента
2. Заполните поля:
  - Название — должно быть уникальным в рамках агента
  - Содержимое файла конфигурации — YAML-скрипт определяет логику работы на стороне агента.
    Пользователю доступна опция «Проверить код»: она включает в себя базовую проверку структуры и синтаксиса правил написания кода на языке YAML, а также важные кастомные настройки:
    - Наличие единственного узла continuous-jobs.
      Использование jobs или комбинации jobs и continuous-jobs - недопустимо
    - Внутри continuous-jobs должен быть непустой список шагов init-step
    - Внутри каждого шага обязателен узел plugin
      При сохранении конфигурации проверка кода выполняется автоматически.
      При обнаружении ошибок отображается сообщение с указанием строк, где найдена проблема. Если скрипт корректен, выводится «OK».
3. Опция «Применить конфигурацию для агента после создания»:
  - Если у агента есть свободный слот, опция включена по умолчанию и может быть отключена вручную
  - Если свободных слотов нет, опция недоступна
4. Нажмите «Создать»
  Если опция применения была включена, конфигурация добавляется в секцию «Назначенные конфигурации» и агент начинает ее выполнение
  Если опция была отключена, конфигурация попадает в секцию «Неиспользуемые конфигурации»
Изменение личной конфигурации
1. Выберите конфигурацию для редактирования в карточке агента
2. Внесите изменения:
  - Изменение названия осуществляется кликом на название. Если оставить его пустым или нарушить правила валидации, оно автоматически вернется к исходному.
  - Изменение YAML-скрипта доступно в текстовом редакторе. При сохранении выполняется автоматическая проверка кода.
3. Сохраните изменения:
  - Если конфигурация уже выполнялась, изменения YAML-скрипта перезапустят выполнение конфигурации на агенте
  - Изменение названия не влияет на выполнение конфигурации
Удаление личной конфигурации
1. Выберите конфигурацию для удаления в карточке агента и нажмите кнопку «Удалить»
2. Подтвердите действие во всплывающем окне
3. После удаления конфигурации агент прекращает ее выполнение

Плагины

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

Подробнее об управлении плагинами можно прочитать в разделе Подключение плагинов.

Онлайн-логирование

При открытии карточки агента устанавливается WebSocket-соединение, через которое передаются логи агента в режиме реального времени.

Особенности работы:

Логи хранятся только временно в рамках текущей сессии и после закрытия карточки агента соединение разрывается, а все ранее полученные данные удаляются
Пользователь может выделять нужные строки и копировать их стандартным сочетанием клавиш (Ctrl+C или Cmd+C)
Отображается не более 1000 последних строк лога. При достижении этого лимита происходит ротация: более старые записи замещаются новыми.

Изоб�ражение

важно

Для возможности работы с онлайн-логированием и динамическим выполнением рабочих конфигураций после внесенных через интерфейс изменений, версия Monq Agent должна быть не ниже 2.2.0

Подключение агента

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

Загрузка агента

Агенты Monq доступны для загрузки по следующим ссылкам:

Агент для Windows

Агент для Linux

Для подключения агента необходимо иметь API-ключ координатора. Если координатор не создан вернитесь к его созданию.

Агент подключается к координатору Monq по протоколу HTTPS (SignalR) c указанием API-ключа и базового URL системы.

Установка в Linux

Создайте рабочую директорию для агента и перейдите в нее:
```
mkdir -p /opt/monq-agent && cd /opt/monq-agent
```

Загрузите актуальную версию monq-agent:

wget https://downloads.monq.ru/tools/monq-agent/latest/linux-x64/monq-agent.zip

Разархивируйте загруженный архив в текущую директорию:
```
unzip monq-agent.zip && rm -f monq-agent.zip
```
Сделайте двоичный файл monq-agent исполняемым:
```
chmod +x ./monq-agent
```

Установите зависимости libicu, совместимой с вашей версией Linux:

CentOS/RHEL
```
yum install libicu
```

Debian/Ubuntu

# найти актуальную версию
apt search '^libicu[0-9]*$'

# выполнить установку найденной версии, например 66
apt install libicu66

Далее произведите настройку конфигурационного файла

Установка в Windows

Загрузите актуальную версию monq-agent.
Извлеките содержимое архива в папку, например: C:\monq-agent\monq-agent.exe.
Далее произведите настройку конфигурационного файла

Конфигурация агента

Создайте в директории с исполняемым файлом файл конфигурации monitoring-agent.conf, следующего содержания:

# Базовый URI системы Monq
BaseUri="https://monq.domain.com"
# API-ключ координатора для авторизации агента
ApiKey="fc63b95b-0393-430a-b8d0-46a8c4813675"
FileStorage=""
Timeout=100
[Plugins]
CSharpPath="/opt/monq-agent/plugins"
[Connection]
Timeout=100
RetryCount=12
[Agent]
Description=""
SlotsCount=2

Полное описание параметров конфигурации агента смотрите в таблице:

Параметр	Описание	Обязательный	По умолчанию
BaseUri	Базовый URL системы (https://monq.domain.com)	+	-
ApiKey	API-ключ координатора	+	-
FileStorage	Путь к хранилищу файлов	-	-
Timeout	Таймаут выполнения заданий, в секундах	-	100
[Plugins]	Секция управления плагинами
CSharpPath	Путь к директории с плагинами агента	-	-
Autoload	Автозагрузка плагинов из хранилища	-	false
[Connection]	Секция управления настройками подключения
Timeout	Таймаут на установку соединения, в секундах	-	30
RetryCount	Количество попыток установки соединения	-	12
[Agent]	Секция настроек агента
Name	Название агента	-	-
Description	Описание	-	-
SlotsCount	Количество слотов для выполнения заданий	-	2
Labels:1 Labels:2	Персональные метки агента с порядковым номером от 1 до N	-	-
[WorkConfigs]	Секция настройки рабочих конфигураций
Path	Путь к рабочим конфигурациям	-	-
[Serilog:MinimumLevel]	Секция уровня логирования
Default	Уровень логирования	-	Information
[Buffer]	Секция настройки буфера *только при использовании рабочих конфигураций
BufferPath	Путь к директории хранения буфера приема	-	-
BufferTotalLimitSize	Максимальный размер выделяемой памяти на диске для хранения очереди, в байтах	-	134217728
FlushTime	Частота отправки файлов очереди	-	"00:00:01"
MaxChunksInMemory	Максимальное количество порций для отправки в систему за одну операцию	-	128
BacklogMemoryLimit	Лимит размера всех порций	-	5242880

Рабочие конфигурации агентов

Начиная с версии агента 2.1.0 появилась возможность настройки непрерывного выполнения заданий на агенте. Это удобно для прослушивания TCP/UDP портов, приема логов в формате syslog и других подобных задач.

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

Формат, используемый в файлах рабочих конфигураций - YAML.

Каталог хранения рабочих конфигураций задается в основном конфигурационном файле в секции [WorkConfigs], параметр Path.
При запуске агента считываются все конфигурационные файлы *.yaml и *.yml в указанном каталоге.

Для каждой рабочей конфигурации требуется выделение 1 слота агента. Если количество слотов на агенте будет меньше, чем количество конфигураций, часть конфигураций будет проигнорирована.

Пример файла рабочей конфигурации агента:

continuous-jobs:
  - init-step:
      plugin: tcp
      with:
        listen: 0.0.0.0
        port: 5170
        separator: \n
        bufferType: memory
        bufferInputName: tcp.job1
        bufferSize: 20
        chunkSize: 20
        format: none
        streamKey: "ключ потока"

На текущий момент имеются следующие встроенные плагины для настройки рабочих конфигураций: tcp, udp, syslog.

Справочную информацию о доступных параметрах этих плагинов можно найти в разделе Справочник - Плагины Monq Agent.

Персональные метки агентов

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

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

...
[Agent]
# Название
# Name="monq-agent-hostname"
# Описание
# Description=""
# Количество слотов для выполнения заданий
# SlotsCount=2
# Метки агента
Labels:1 = "Agent2"
Labels:2 = "GeneralLabel"
...

После подключения агента к координатору, все указанные метки будут доступны для выбора в поле «Агент» в задании потока данных.

Типы агентов

Агент может быть сконфигурирован как статический или динамический:

Статические агенты - это агенты, состояние которых контролирует координатор.
При подключении статического агента координатор регистрирует его в списке подключенных агентов и контролирует его состояние.
Динамические агенты - видны в системе до тех пор, пока они активны.
При отключении динамического агента, он пропадает из списка подключенных к координатору.

Для управления типом агента, служит параметр конфигурации Name - название агента:

Если параметр Name не задан - координатор устанавливает агенту тип динамический и присваивает автоматически сгенерированное название.
Если параметр Name задан - координатор устанавливает агенту тип статический и регистрирует его с заданным названием.

имя агента должно быть уникальным

Подключение нескольких агентов с одинаковыми названиями недопустимо.
Названия агентов при подключении проверяются в рамках пользовательского пространства.

Подключение плагинов

Плагины доступны для загрузки по ссылке.

Для подключения плагина к агенту, извлеките архив с плагином в директорию, указанную в конфигурационном файле агента (CSharpPath=/opt/monq-agent/plugins).

Информацию по настройке плагинов можно найти по ссылке.

Начиная с версии Monq 8.3.0 плагины на агенты могут загружаться автоматически. Для включения этой опции необходимо добавить параметр Autoload со значением True в секции "[Plugins]".

Автоматическая загрузка плагинов на агент работает следующим образом: При получении нового задания, агент проверяет наличие необходимого плагина в указанной в файле конфигурации директории CSharpPath (например, /opt/monq-agent/plugins). Если в директории нужный плагин есть - задание выполняется. Если нужного плагина в директории нет - агент запросит плагин из хранилища (при условии, что включен параметр Autoload=True), сохранит его в свою директорию CSharpPath и без перезапуска продолжит исполнение полученного задания.

Запуск

Поддерживаемые команды

start - Запуск агента.

Использование: monq-agent [options] start

Параметры запуска:

--config <config> - путь к конфигурационному файлу, по умолчанию конфигурационный файл monitoring-agent.conf.
--insecure - не использовать проверку SSL сертификата, по умолчанию выключено.
-?, -h, --help - показать справку.

Запуск агента в Linux
Запуск агента в Windows
Запуск агента в Kubernetes

Запуск в Linux

Для запуска агента в качестве сервиса необходимо в директории /etc/systemd/system/ разместить файл конфигурации monq-agent.service:

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

[Unit]
Description=Monqlab Agent Service
Documentation=https://docs.monq.ru/

[Service]
Type=notify
WorkingDirectory=/opt/monq-agent
ExecStart=/opt/monq-agent/monq-agent start --config /opt/monq-agent/monitoring-agent.conf
StandardOutput=syslog
User=root

[Install]
WantedBy=multi-user.target
Alias=monq-agent.service

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

Создание пользователя и назначение владельцем директории с monq-agent

useradd --no-create-home --shell /bin/false -d /opt/monq-agent monq
chown -R monq:monq /opt/monq-agent 

Пример конфигурации Unit Systemd:

[Unit]
Description=Monqlab Agent Service
Documentation=https://docs.monq.ru/
[Service]
Type=notify
WorkingDirectory=/opt/monq-agent
Environment="DOTNET_BUNDLE_EXTRACT_BASE_DIR=/opt"
ExecStart=/opt/monq-agent/monq-agent start --config /opt/monq-agent/monitoring-agent.conf
User=monq
[Install]
WantedBy=multi-user.target
Alias=monq-agent.service

Управление сервисом осуществляется через команды systemctl:

Загрузить новый файл конфигурации systemd (выполняется при изменении файла monq-agent.service)
```
sudo systemctl daemon-reload 
```
Проверить статус сервиса monq-agent.service
```
sudo systemctl status monq-agent.service 
```
Запустить сервис monq-agent.service
```
sudo systemctl start monq-agent.service 
```
Открыть логи сервиса monq-agent.service
```
sudo journalctl -u monq-agent.service -f 
```

Запуск в Windows

Для запуска monq-agent в качестве службы Windows необходимо от имени Администратора создать и зарегистрировать службу с помощью утилиты для командной строки Диспетчер управления службами Windows.

Пример:

# Создать службу
sc.exe create MonqAgent binPath= "C:\monq-agent\monq-agent.exe start --config C:\monq-agent\monitoring-agent.conf" 
# Запустить службу
sc.exe start MonqAgent 
# Остановить службу
sc.exe stop MonqAgent 
# Удалить службу
sc.exe delete MonqAgent

Запуск в Kubernetes

Репозиторий Monq agent в GitHub

Установка Monq agent через Helm

Должен быть установлен Helm для использования чартов.

Пожалуйста, обратитесь к документации по Helm, чтобы начать.

Когда Helm будет настроен правильно, установите последнюю версию чарта с именем релиза monq-agent следующей командой:

kubectl create namespace monq

helm upgrade --install monq-agent monq-agent --repo https://monqdl.github.io/monq-agent --namespace monq \
--set config.baseUri="https://monq.mydomain.com" --set config.apiKey="<my coordinator key>"

Удаление Monq agent через Helm

Для удаления monq-agent выполните следующую команду:

helm delete monq-agent -n monq

Данная команда удаляет все компоненты Kubernetes, связанные с чартом, и удаляет релиз.

Параметры конфигурация агента при установке через Helm

Ключ	Тип	Значение по умолчанию	Описание
`config.baseUri`	string	`nil`	Полностью определенное доменное имя (FQDN) экземпляра Monq
`config.apiKey`	string	`nil`	API ключ координатора Monq
`config.fileStorage`	string	`nil`	Путь к хранилищу файлов агента
`config.timeout`	int	`100`	Таймаут для подключения к экземпляру Monq
`config.pluginsPath`	string	`agent-plugins`	Путь к хранилищу плагинов агента
`config.retryCount`	int	`10`	Количество попыток повторного подключения к экземпляру Monq
`config.slotsCount`	int	`2`	Количество активных слотов агента
`replicas`	int	`1`	Количество реплик агента
`image.repository`	string	`ghcr.io/MONQDL`	Репозиторий образов контейнеров
`image.name`	string	`monq-agent`	Название образа
`image.pullPolicy`	string	`IfNotPresent`	Политика загрузки образа
`image.tag`	string	`nil`	Тэг образа, используется `AppVersion`, если не определено
`imagePullSecrets`	list	`[]`	Необязательный массив imagePullSecrets, содержащий учетные данные для доступа к закрытому реестру образов # Справка: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/
`resources.limits.cpu`	string	`nil`	Лимит использования ЦПУ
`resources.limits.memory`	string	`nil`	Лимит использования памяти
`resources.requests.cpu`	string	`250m`	Запрашиваемые ресурсы ЦПУ
`resources.requests.memory`	string	`256Mi`	Запрашиваемые ресурсы памяти
`nodeSelector`	object	`{"kubernetes.io/os":"linux"}`	Метки `nodeSelector` для распределения пода на ноде # Справка: https://kubernetes.io/docs/user-guide/node-selection/ #

Установка при помощи манифеста

Установите Monq-agent в качестве развертывания (Deployment) на ваш кластер Kubernetes, применив манифест:

export MONQ_URI="https://monq.mydomain.com"
export MONQ_KEY="<my coordinator key>"

curl https://raw.githubusercontent.com/MONQDL/monq-agent/master/manifests/monq-agent/monq-agent.yaml -o monq-agent.yaml 

envsubst < monq-agent.yaml | kubectl apply -f -

Этот манифест также создает ClusterRole, ClusterRoleBinding, ServiceAccount и Secret для работы с компонентами кластера.

Траблшутинг при подключении

Подключение в legacy-mode

В случае если необходимо подключить monq-agent, работающий на операционной системе:

Windows Server 2008
Windows 7
Windows Server 2012
Windows 8
Windows 8.1

Cистемному администратору инфраструктуры Monq необходимо разрешить в конфигурации ingress-nginx-controller использование cipher поддерживаемых устаревшими ОС.

Для этого в configMap ingress-nginx-controller необходимо добавить следующую опцию:

kubectl edit cm -n ingress-nginx ingress-nginx-controller
...
  ssl-ciphers: "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"
... 

При возникновении ошибок с загрузкой DLL при запуске monq-agent в данной ОС Windows необходимо дополнительно установить Microsoft Visual C++ 2015 Redistributable (x64)

Проверка подключения

Об успешном запуске и подключении агента к платформе, свидетельствует запись в лог-файле:

sudo journalctl -u monq-agent.service -f 
Nov 23 13:37:39 elk monq-agent[102088]: [2021-11-23 13:37:39 +03:00 INF]  Establishing connection.
Nov 23 13:37:44 elk monq-agent[102088]: [2021-11-23 13:37:44 +03:00 INF]  Connection established.

Перейдите в раздел Сбор данных - Агенты.
Откройте координатор к которому выполнялось подключение агента.
Перейдите на вкладку «Агенты» и убедитесь в том, что агент подключен.

⚠️ Если домен на котором работает Monq подписан self-signed сертификатом безопасности необходимо добавить параметр --insecure в строке запуска агента.

Внимание

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

Настройка логирования

Пример настройки логирования агента в файл:

...
[Serilog:WriteTo:0]
Name="File"

[Serilog:WriteTo:0:Args]
path="D:\\monq-log.txt"
rollingInterval="Day"

[Serilog:MinimumLevel]
Default="Debug"

[Serilog:MinimumLevel:Override]
Microsoft="Debug"
System="Debug"
...

Дополнительную информацию по конфигурации Serilog можно найти по ссылке.

Тонкая настройка соединения

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

Пример записи из лога:

[2024-02-08 13:10:59 +00:00 INF]  Establishing connection.
[2024-02-08 13:11:14 +00:00 ERR]  The server disconnected before the 
handshake could be started.System.IO.IOException: The server disconnected before the handshake could be 
started.
   at 
Microsoft.AspNetCore.SignalR.Client.HubConnection.HandshakeAsync(ConnectionState 
startingConnectionState, CancellationToken cancellationToken) 

Изменить параметры соединения можно с помощью клиента управления monqctl через команду monqctl registry apply применительно к сервису pl-agents-service (объект Hub).

Список свойств, доступных для настройки:

Свойство	Описание	Формат	Пример	По умолчанию
KeepAliveInterval	Интервал, используемый сервером для периодической проверки связи с клиентами. При изменении значения здесь, следует также изменить `ServerTimeout` в настройках клиентов	D.HH:mm:ss (string)	"0.00:00:10"	10 секунд
HandshakeTimeout	Интервал таймаута входящих запросов подтверждения от клиентов. Менять этот параметр стоит только в случае возникновения ошибок по таймауту из-за серьезной задержки в сети	D.HH:mm:ss (string)	"0.00:00:15"	15 секунд
ClientTimeoutInterval	Интервал, за который клиенты должны обработать сообщение, прежде чем сервер разорвет соединение. Рекомендуемое значение: как минимум х2 от KeepAliveInterval сервера	D.HH:mm:ss (string)	"0.00:00:30"	30 секунд
EnableDetailedErrors	Флаг отправки клиенту подробных сообщений об ошибках	boolean	true	false
MaximumReceiveMessageSize	Максимальный размер одного входящего сообщения в байтах	number	1048576	1МБ
StreamBufferCapacity	Максимальный размер буфера для клиентских потоков загрузки данных	number	10	10
MaximumParallelInvocationsPerClient	Количество параллельно выполняемых клиентами методов концентратора	number	2	1

Применяемая настройка обновляет все свойства!

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

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

Проверка текущей конфигурации:

monqctl registry get microservice-parameters pl-agents-service --output json | jq '.[] | select(.Name == "Hub") | .Value'

Пример ответа, выводимого в консоль:

{
  "MaximumReceiveMessageSize": 1048576
}

Применение новой конфигурации с обновленными свойствами:

monqctl registry apply microservice-parameter pl-agents-service \
--name=Hub \
--settingsKey="appsettings-scheduler.json" \
--value='
{
  "MaximumReceiveMessageSize": 9999999999,
  "EnableDetailedErrors": true,
  "MaximumParallelInvocationsPerClient": 2
}
'

Кроме того, расширена конфигурация самого агента, т.к. соединение по веб-сокетам двухстороннее и требует настройки как на клиенте, так и на сервере одновременно:

[Connection]
# Глобальный таймаут установки и регистрации соединения в секундах.
# Значение по умолчанию - 30 секунд.
Timeout=30
# Количество попыток установки соединения.
# Значение по умолчанию - 12.
RetryCount=12
# Таймаут активности сервера.
# Если сервер не отправил сообщение за этот интервал, клиент считает, что сервер отключен, и закрывает соединение.
# Это значение должно быть достаточно большим, чтобы ping-сообщение могло быть получено клиентом за данный интервал.
# Рекомендуемое значение — по меньшей мере удвоенное значение KeepAliveInterval сервера.
# Значение по умолчанию - 30 секунд.
ServerTimeout="00:00:30"
# Таймаут запросов подтверждения с сервера.
# Если сервер не отправил ответ на handshake-сообщение в течение этого интервала, то клиент закрывает соединение.
# Менять этот параметр стоит только в случае возникновения ошибок по таймауту из-за серьезной задержки в сети.
# Рекомендуемое значение - не меньше, чем значение Timeout.
# Значение по умолчанию - 15 секунд.
HandshakeTimeout="00:00:15"
# Интервал, с которым клиент отправляет ping-сообщения для проверки связи.
# Если клиент не отправил сообщение за ClientTimeoutInterval, установленном на сервере, то сервер считает, что клиент отключен.
# Значение по умолчанию - 10 секунд.
KeepAliveInterval="00:00:10"

Экран «Управление агентами»​

Координаторы​

Список координаторов​

Поиск координаторов​

Создание координаторов​

Настройка координаторов​

Основная информация​

Конфигурации агентов​

Создание новой конфигурации​

Изменение существующей конфигурации​

Запуск и остановка конфигурации​

Удаление конфигурации​

Запуск и остановка координаторов​

Перевыпуск API-ключа​

Удаление координаторов​

Агенты​

Список агентов​

Поиск агентов​

Настройка агентов​

Конфигурации​

Типы конфигураций​

Приоритет конфигураций​

Личная конфигурация​

Плагины​

Онлайн-логирование​

Подключение агента​

Установка в Linux​

Установка в Windows​

Конфигурация агента​

Рабочие конфигурации агентов​

Персональные метки агентов​

Типы агентов​

Подключение плагинов​

Запуск​

Запуск в Linux​

Запуск в Windows​

Запуск в Kubernetes​

Установка Monq agent через Helm​

Удаление Monq agent через Helm​

Параметры конфигурация агента при установке через Helm​

Установка при помощи манифеста​

Траблшутинг при подключении​

Подключение в legacy-mode​

Проверка подключения​

Настройка логирования​

Тонкая настройка соединения​

Экран «Управление агентами»

Координаторы

Список координаторов

Поиск координаторов

Создание координаторов

Настройка координаторов

Основная информация

Конфигурации агентов

Создание новой конфигурации

Изменение существующей конфигурации

Запуск и остановка конфигурации

Удаление конфигурации

Запуск и остановка координаторов

Перевыпуск API-ключа

Удаление координаторов

Агенты

Список агентов

Поиск агентов

Настройка агентов

Конфигурации

Типы конфигураций

Приоритет конфигураций

Личная конфигурация

Плагины

Онлайн-логирование

Подключение агента

Установка в Linux

Установка в Windows

Конфигурация агента

Рабочие конфигурации агентов

Персональные метки агентов

Типы агентов

Подключение плагинов

Запуск

Запуск в Linux

Запуск в Windows

Запуск в Kubernetes

Установка Monq agent через Helm

Удаление Monq agent через Helm

Параметры конфигурация агента при установке через Helm

Установка при помощи манифеста

Траблшутинг при подключении

Подключение в legacy-mode

Проверка подключения

Настройка логирования

Тонкая настройка соединения