Настройка пользовательских сенсоров мониторинга

В качестве сенсоров мониторинга можно использовать собственные скрипты и передавать им аргументы, настраиваемые через web-интерфейс.

Каждая проверка состоит из двух файлов:

  • исполняемый файл проверки (скрипт или бинарный файл);

  • файл конфигурации, описывающий web-интерфейс секции Мониторинг для передачи аргументов исполняемому файлу.

Файл конфигурации должен:

  • находиться в одной папке с исполняемым файлом;

  • иметь название исполняемого файла с дополнительным расширением .conf:

/opt/saymon-agent/custom_tasks/mytask.sh
/opt/saymon-agent/custom_tasks/mytask.sh.conf

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

/opt/saymon-agent/custom_tasks/cisco/task_1.sh
/opt/saymon-agent/custom_tasks/cisco/task_1.sh.conf
/opt/saymon-agent/custom_tasks/cisco/task_2.sh
/opt/saymon-agent/custom_tasks/cisco/task_2.sh.conf
/opt/saymon-agent/custom_tasks/hp/task_3.sh
/opt/saymon-agent/custom_tasks/hp/task_3.sh.conf
/opt/saymon-agent/custom_tasks/hp/task_4.sh
/opt/saymon-agent/custom_tasks/hp/task_4.sh.conf

В web-интерфейсе данные проверки будут группироваться и отображаться с учётом подпапок:

cisco - task_1
cisco - task_2
hp - task_3
hp - task_4

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

Идентификаторы сенсоров, которыми оперируют сервер и агенты, создаются автоматически и эквивалентны именам исполняемых файлов с частью пути от сконфигурированной папки. Например: cisco/task_1.

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

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

Идентификаторы сенсоров чувствительны к регистру символов.

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

Конфигурационные файлы достаточно разместить на хостах с сервером системы.

Каталог для пользовательских сенсоров

Каталог пользовательских сенсоров задается в конфигурационном файле сервера /etc/saymon/saymon-server.conf.

Необходимо:

  1. Добавить в файл секцию monitoring.

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

    ...
    "monitoring": {
        "custom_tasks_path": "/opt/saymon-agent/custom_tasks"
    },
    ...
  3. Перезапустить сервер:

    $ sudo service saymon-server restart

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

Параметры сенсора задаются в JSON-файле, именуемом как имя_исполняемого_файла.conf. Например, для сенсора mySensor.sh файл настроек параметров должен называться mySensor.sh.conf.

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

Сенсоры без конфигурационного файла игнорируются.

Файл настроек параметров может содержать следующий набор полей:

Поле Описание

title

Имя сенсора, отображаемое в web-интерфейсе в списке проверок.

Опциональное поле.

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

  • путь к файлу: <путь до папки с проверками>/cisco/task_1.sh

  • отображаемое имя: cisco - task_1

icon

Иконка из набора Font Awesome, отображаемая рядом с именем проверки.

Опциональное поле.

По умолчанию отображается image - 'fa fa-cubes fa-fw'

excludeForClasses

Список идентификаторов классов объектов, для которых сенсор скрывается.

Опциональное поле.

По умолчанию сенсор доступен для всех классов объектов.

args

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

args.id

Имя аргумента, передаваемое исполняемому файлу.

Опциональное поле.

args.default

Значение аргумента по умолчанию, подставляемое в соответствующее поле при создании проверки.

Опциональное поле.

args.description

Описание аргумента, отображаемое в web-интерфейсе.

Опциональное поле.

args.name

Название аргумента, отображаемое в web-интерфейсе.

args.options

Применимо только для типа select (args.type.select).

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

По умолчанию при создании проверки выбирается первая опция. Чтобы установить иную опцию значением по умолчанию, необходимо указать значение поля args.options.value в поле args.default.

Исполняемому файлу передаются:

Если args.id не задано, то исполняемому файлу передаётся только значение выбранного аргумента (args.options.value).

Если значение аргумента не задано (args.options.value), то исполняемому файлу также не передаётся имя аргумента (args.id).

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

args.options.description

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

Опциональное поле.

По умолчанию отображается значение аргумента (args.options.value).

args.options.value

Значение аргумента.

Опциональное поле.

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

args.required

Признак обязательности заполнения значения аргумента.

  • true - значение обязательно,

  • false - значение опционально.

Опциональное поле.

По умолчанию - false.

args.type

Тип значения аргумента.

Опциональное поле.

По умолчанию - text.

args.type.checkbox

Переключатель.

По умолчанию выключен.

При включении исполняемому файлу передаётся значение, указанное в поле args.id (имя аргумента). Если это поле отсутствует, то исполняемому файлу передаётся порядковый номер аргумента (отсчёт начинается с 0).

args.type.password

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

args.type.select

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

Список значений задается в поле args.options.

Для данного типа не отображается описание аргумента (поле args.description). Вместо этого необходимо использовать соответствующее поле для каждого значения аргумента (args.options.description).

args.type.text

Отображает текстовое поле для ввода значения аргумента.

args.type.textarea

Отображает текстовое поле для ввода значения аргумента.

Позволяет вводить многострочный текст.

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

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

Разместите их в каталоге пользовательских проверок, создайте объект с проверкой в web-интерфейсе и попробуйте поменять значения аргументов.

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

hello_world.sh
#!/bin/bash
#
# Use this script as the custom monitoring sensor
# to check or test arguments configuration file.

i=0
echo "Custom probe got the following args:"
for arg in $*
do
  i=$((i + 1))
  echo -ne $arg; echo -ne " "
done

if [ $i = 0 ]
then
  echo "(no args)"
  exit 2
fi

В этом конфигурационном файле приведены примеры для всех типов аргументов:

hello_world.sh.conf
{
    "title": "Custom probe example",
    "icon": "fa fa-folder fa-fw",
    "excludeForClasses": [1,2],
    "args": [
        {
            "name": "Unnamed (positional) arg"
        },
        {
            "name": "Named arg",
            "id": "--name"
        },
        {
            "name": "Behold the description on the right",
            "description": "Here I am!",
            "id": "--description"
        },
        {
            "name": "Arg with defaul value",
            "description": "and description",
            "id": "--defval",
            "default": "default_value"
        },
        {
            "name": "Required arg",
            "description": "This field is required to fill in",
            "id": "--required",
            "required": true
        },
        {
            "name": "Type - Text",
            "description": "This and all above fields have got text type",
            "id": "--text",
            "type": "text"
        },
        {
            "name": "Type - Text Area",
            "description": "This field is text area. \nIt is resizable in most browsers. \nAnd allows to enter multiline texts.",
            "id": "--textarea",
            "type": "textarea"
        },
        {
            "name": "Type - Checkbox",
            "description": "This is the checkbox type",
            "id": "--checkbox",
            "type": "checkbox"
        },
        {
            "name": "Type - Password",
            "description": "This is the password field",
            "id": "--pass",
            "default": "qwerty",
            "type": "password"
        },
        {
            "name": "Type - Select",
            "description": "This is the select type. This description is not displayed in the web interface. Use description for each option instead.",
            "id": "--select",
            "default": "option2",
            "type": "select",
            "options": [
                {
                    "description": "== Not selected =="
                },
                {
                    "value": "option1", "description": "OK"
                },
                {
                    "description": "== Divider =="
                },
                {
                    "value": "option2", "description": "Warning"
                },
                {
                    "value": "option3", "description": "Error"
                }
            ]
        },
        {
            "name": "Type – File",
            "description": "This argument allows you to upload a file up to 16 MBs",
            "id": "--file",
            "type": "file"
        }
    ]
}

Загрузка файла

Аргумент типа file позволяет загружать небольшой (до 16Мбайт) произвольный файл, привязав его к параметру свойства пользовательской проверки.

{
    ...
    "args": [
        {
            "name": "Type – File",
            "description": "This argument allows you to upload a file up to 16 MBs",
            "id": "--file",
            "type": "file"
        },
    ]
    ...
}

Загруженный файл будет храниться в отдельной коллекции в MongoDB (fileStorage). Доступ к этому файлу можно будет получить по следующей ссылке:

http://<server-hostname>/node/api/files/<file-id>
Для доступа к файлу по ссылке требуется авторизация. При этом, для доступа к файлу не требуется доступ к объекту, на котором настроен пользовательский сенсор мониторинга или особых прав пользователя.

В параметре объекта будет сохранён идентификатор файла.

Пример структуры сохраненного параметра
{
    "type_id": 8,
    "id": "6650b847742388c0efe0b687",
    "name": "file_1",
    "value": {
        "name": "test.png",
        "type": "file",
        "id": "6650bc84742388c0efe0b68b"
    }
}

Использование утилит операционной системы

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

Рассмотрим в качестве примера процесс добавления программы cURL.

Необходимо:

  1. Перейти в директорию с пользовательскими проверками:

    $ cd /opt/saymon-custom-monitoring
  2. Узнать путь до исполняемого файла программы cURL:

    $ which curl
    
    > /usr/bin/curl
  3. Создать ссылку с именем cURL и путём до исполняемого файла /usr/bin/curl:

    $ ln -s /usr/bin/curl cURL
  4. Создать конфигурационный файл для проверки:

    $ nano cURL.conf
    
    {
        "title": "cURL reuse",
         "args": [
            {
                "name": "URL to cURL",
                "description": "e.g. https://google.com",
                "required": true
            }
         ]
    }

После обновления страницы в web-интерфейсе в выпадающем списке проверок появится новый сенсор с именем cURL reuse. Данная проверка имеет всего один обязательный для заполнения аргумент.