Collector editor: разработка нового сборщика. Документация по разработке

Описание Collector editor

Collector editor служит для создания нового или редактирования существующего сборщика. Для удобства в Collector Editor встроен редактор JavaScript и редактор шаблонов PUG. Collector editor имеет все необходимые средства для разработки сборщика и не требует установки дополнительных сред разработки.

Возвращаемое значение: Collector ID (имя папки, в которой расположен редактируемый сборщик)

Описание интерфейса

Вкладки

Settings - Настройки сборщика и его параметров
Collector code - Редактор JavaScript исполняемого кода сборщика. Код будет исполняться при вызове сборщика сервером для получения или генерации данных
Help page - редактор страниц помощи на различных языках. Для формирования страниц помощи так же используется шаблонизатор PUG, который в дальнейшем, используя препроцессор формирует страницы в HTML.

Settings

Основные настройки

Select collector

Позволяет выбрать сборщик для редактирования или создать новый (если выбрать New collector)

Collector ID

Collector ID для нового сборщика. Collector ID - это папка, в которой находятся файлы сборщика.

Collector name

Имя сборщика, которое отображается в списке Select collector и в действии Counter settings.

Start the collector as a separate thread

Для активных коллекторов (active collectors) и коллекторов, запущенных в выделенном процессе (separate collectors) позволяет запустить код коллектора в отдельном потоке. Это позволяет разделить код коллектора и код, который его обслуживает и уменьшить время обработки данных коллектором. Запустить коллектор в отдельном потоке можно только если коллектор использует модули, поддерживающие работу в отдельном потоке.

Active collector

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

Separate collector

Используется для пассивного типа сборщиков (когда сбор данных происходит по инициативе сервера ALEPIZ). Обычно код сборщика встраивается в дочерние процессы сервера и, при необходимости сбора данных, исполняется как код сервера. Если включить Run collector separately, сервер запустит отдельный процесс с кодом сборщика и дочерние процессы будут обращаться к нему. В случае встраивания одновременно может работать несколько копий сборщиков. При это они все будут частью сервера, что может привести к дополнительной нагрузке на сервер, если код сборщика требует каких-то ресурсов ресурсов. В случае выделения сборщика в отдельный процесс, будет выполняться только одна копия сборщика, при этом не занимая вычислительные и другие ресурсы сервера. Ресурсы сервера будут использоваться только для процесса обмена данными со сборщиком. Так же запуск пассивного сборщика в отдельном процессе может потребоваться, если сборщику необходимо хранить свои какие-то состояния.

Delete collector

Выбранный счетчик будет удален из системы.

Restart server

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

Collector description

Описание для счетчика, которое будет появляться в качестве подсказки при выборе счетчика в Counter settings

Timeout to start collector separately

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

Настройка параметров сборщика

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

Для того, чтобы добавить новый параметр, нужно нажать на кнопку "+" под параметрами.

Для удаления параметра нужно нажать на "x" слева сверху формы ввода свойств параметра

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

Parameter name

Имя параметра, которое, вместе со значением, передается в счетчик

Parameter description

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

Can be empty

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

Default value

Значение параметра по умолчанию. Если установлено то в поле значения параметра в Counter settings будет подставляться это значение

Check parameter as

Несколько шаблонов для проверки корректности ввода значения параметра в Counter settings. Если проверка установлена и значение параметра не соответствует шаблону, при сохранении счетчика будет выведена ошибка.

Могут использоваться следующие шаблоны для проверки:

Without checking - проверка значения не будет производится
Integer number - проверка соответствия целому числу
Unsigned Integer number - проверка соответствия положительному целому числу
Unsigned non-zero integer - проверка соответствия положительному не нулевому целому числу
0 or 1 - значение может быть или 0 или 1
Time interval (500, 10m, 10.5h, 2d etc) - проверка на интервал времени в миллисекундах или с суффиксами s(секунды) m(минуты), h(часы), d(дни), как в примере в скобках.
Bytes (10, 2Kb, 3Mb, 5.5Gb etc) - проверка на значение в байтах или производных с суффиксами Kb, Mb, Gb
24-hour clock (23:25, 21:45:30 etc) - проверка на 24 часовое обозначение времени в формате HH:MM[:SS]
12 or 24 hour clock (23:25, 21:45:30 1:32Am 10:40:30 pm etc) - проверка на 12 или 24 часовое обозначение времени в формате HH:MM[:SS][am|pm]
Date DD.MM.YYYY (20.07.20, 31/08/2020 14-06-2021 etc) - проверка на дату. Разделителем может быть любой не числовой символ. Год может быть указан в формате YYYY или YY
Float number - проверка соответствия числу с плавающей точкой
Internet host name or IPv6\4 address - проверка, что значение параметра - это стандартное доменное имя хоста или IP адрес v4 или v6
TCP port (number) - проверка, что значение параметра - это стандартный порт протокола TCP

Input type

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

Standard text input - поле ввода размером в 1/3 ширины формы
Password text input - поле ввода паролей (вводимая информация не будет отображаться)
Short text input - поле ввода размером в 1/6 ширины формы
Middle text input - поле ввода размером в 2/3 ширины формы
Long text input - поле ввода размером в ширину формы
Select (add "selectOptions" manually) - поле ввода Select. Необходимо вручную в файл настроек коллектора config.json добавить список опций для выбора в формате {: , : }. В качестве примера можно посмотреть файл настроек config.json коллектора event-generator, параметр "importance".
Checkbox - Элемент типа checkbox
Text area - Многострочное поле ввода размером в ширину формы
Javascript editor - Поле для ввода кода на языке JavaScript
JSON editor - Поле для ввода для JSON

Collector code

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

Формирование файла помощи во вкладке HELP PAGE

Help page language

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

Add new language

Если в это поле добавить новый язык и нажать на кнопку "+", он будет добавлен в список языков. Help page language. Затем можно создать страницу помощи на добавленном языке.

Разработка нового сборщика

Сборщик состоит из нескольких стандартных компонент:

config.json - файл с настройками сборщика
collector.js - исполняемый код сборщика
help\index.ru.pug - статическая страница помощи с описанием сборщика

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

Подключение дополнительных модулей nodejs

Если требуется подключить внешний модуль nodejs, необходимо установить его в каталог node_modules, который должен находится в корневом каталоге разрабатываемой компоненты. Для этого можно воспользоваться утилитой npm и в корневом каталоге компоненты выполнить следующие шаги:

создать файл package.json вручную либо запустить npm init и ответить на вопросы.
выполнить nmp i <имя модуля>. Появится каталог node_modules в который будет установлен требуемый модуль

Пассивные сборщики

Пассивные сборщики интегрируются в код сервера (если не установлен параметр "Separate collector"). Обычно счетчик, использующий пассивный сборщик, зависит от других счетчиков и начинает собирать данные на основе этих зависимостей, например по сигналу от счетчика, созданного на основе активного сборщика "timer". Простым примером пассивного счетчика является "constant" , который передает значение своего параметра серверу.

Активные сборщики

Активные сборщики запускаются как выделенный процесс на старте системы. Запуск и работу сборщика в выделенном процессе, получение параметров и отправку данных на сервер обеспечивает система. Разработчику необходимо только реализовать функцию, принимающую параметры сборщика и собирающую или генерирующую данные и вызывающую функцию callback для передачи данных на сервер. Чаще всего счетчик, использующий активный сборщик, не зависит от других счетчиков, инициализируется при старте системы и инициирует сбор данных автоматически по своему алгоритму, периодически вызывая функцию callback для передачи собранных данных серверу. Простым примером активного сборщика является "timer", который запускается и генерирует сигналы в определенное параметрами счетчика время.

config.json - файл с настройками сборщика

Файл с настройками для сборщика создается автоматически действием Collector editor на основе введенных разработчиком параметров. Создавать такой файл вручную не требуется. Ниже описаны параметры, используемые в файле:

name - имя сборщика, используется в различных элементах интерфейса для выбора сборщика
description - описание предназначения сборщика
active - ("on" или "") является ли сборщик активным
separate - ("on" или "") можно ли до окончания обработки данных сервером получать от сборщика еще данные каждой связки объект-счетчик
runCollectorSeparately - ("on" или "") нужно ли запускать пассивный сборщик в выделенном процессе. Это может потребоваться, если сборщик использует структуры данных, в которых хранит свои состояния от предыдущих запусков. В случае, если он интегрируется в дочерние процессы сервера, связи между каждым из процессом не будет и структуры данных для каждого процесса для сборщика будут отдельными. Например, event-generator хранит события, которые произошли в системе и их параметры, а так же кэш данных, для ускорения работы с базой данных.
runCollectorAsThread - ("on" или "") нужно ли запускать сборщик в выделенном потоке (если коллектор активный или запускается в выделенном процессе). Это позволяет разделить код коллектора и код, который его обслуживает и уменьшить время обработки данных коллектором. Запустить коллектор в отдельном потоке можно только если коллектор использует модули, поддерживающие работу в отдельном потоке.
returnedValuesProcessedLimit - если коллектор вернул массив данных, ALEPIZ запускает обработку результата по каждому элементу массива. Например, если процесс обнаружения вернул массив из списка сервисов, работающих на платформе, будет отдельно обработан каждый сервис. Для того, чтобы избежать повышенной загрузки ресурсов сервера, можно ограничить количество значений, которое будет обрабатываться одномоментно. Этот параметр также можно настроить для сервера. Перечитывается раз в 5 минут. Настройка параметра для коллектора имеет более высокий приоритет. По умолчанию 1000.
sleepTimeAfterValueProcessed - если коллектор вернул массив данных для дальнейшей обработки, можно установить паузу в миллисекундах между обработкой порций данных, установленных в параметре returnedValuesProcessedLimit. Этот параметр также можно настроить для сервера. Перечитывается раз в 5 минут. Настройка параметра для коллектора имеет более высокий приоритет. Это необходимо для уменьшения нагрузки на сервер. По умолчанию 0 - не ждать.
parameters - объект, состоящий из объектов - названий параметров для сборщика, каждый из которых содержит следующие настройки:

description - описание параметра
checkAs - тип проверки введенных данных
default - значение по умолчанию для параметра
type - тип элемента в интерфейсе Counter editor для ввода данных параметра
canBeEmpty - ("on" или "") - может ли значение параметра быть пустым

Пример файла с настройками для сборщика "Constant".

{
    "name": "Constant",
    "description": "The collector is used to return a predefined value in the collector",
    "active": "",
    "separate": "",
    "runCollectorSeparately": "",
    "parameters": {
        "constant": {
            "description": "This value will be returned by the collector.",
            "canBeEmpty": "on",
            "type": "textInputLong"
        }
    }
}

collector.js - исполняемый код сборщика

Сборщик должен экспортировать функцию get. При необходимости он так же может экспортировать функции removeCounters и destroy. Ниже приводится их описание:

get(param, callback)

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

param - это объект, состоящий и объектов параметр-значение, которые передаются сборщику от счетчика. Например для сборщика "Constant" это будет {constant: <Значение параметра>}. Некоторые параметры передаются в сборщик системой:

$id - идентификатор связанных объекта и счетчика
$counterID - идентификатор счетчика, который использует этот сборщик
$objectID - идентификатор объекта, который связан со счетчиком
$parentID - родительский идентификатор связанных объекта и счетчика, если счетчик зависит от другого счетчика и запустился по событию, сгенерированному в родительском счетчике
$variables - объект содержит все переменные и их значения, вычисленные во всех родительских счетчиках. Формат объекта: {<Имя переменной1>: <Значение переменной1>, <Имя переменной2>: <Значение переменной2>}

callback(err, result) - функция, которая вызывается для отправки собранных или сгенерированных сборщиком данных на сервер.

err - null или объект с ошибкой, например new Error('Error text')
result - результат в виде каких-то данных (время сбора данных генерируется сервером при получении данных от сборщика) или объект в формате {value: <value> timestamp: <timestamp>}

<value> - данные, собранные или сгенерированные сборщиком
<timestamp> - время в миллисекундах с 1.1.1970 для создания корректной метки времени сбора данных сборщиком

removeCounters(IDs, callback)

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

IDs - массив идентификаторов связанных объектов и счетчиков
callback(err) - функция, вызываемая после окончания выполнения всех операций по очистки данных. err - null или объект с ошибкой, например new Error('Error text')

destroy(callback)

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

callback(err) - функция, вызываемая после окончания выполнения всех операций по очистки данных. err - null или объект с ошибкой, например new Error('Error text')

Пример исполняемого кода для пассивного сборщика "Constant". Сборщик принимает параметр constant и возвращает его на сервер.

var collector = {};
module.exports = collector;

collector.get = function(prms, callback) {
    /* insert collector code here */
    callback(null, prms.constant);
};

Пример исполняемого кода для активного сборщика "Timer". Сборщик принимает параметр wakeupInterval и через определенный в нем интервал времени (в секундах) генерирует сигналы, возвращая текущее время

var log = require('../../lib/log')(module);

var collector = {};
module.exports = collector;

var timers = {},
    isServerRunning = false,
    timerID;

collector.get = function(prms, callback) {
    if(!prms || !prms.wakeupInterval) return callback(new Error('Parameter "wakeupInterval" is not specified'));

    if(Number(prms.wakeupInterval) !== parseInt(prms.wakeupInterval, 10)) {
        return callback(new Error('Parameter "wakeupInterval" is incorrect: "' + prms.wakeupInterval + '"'));
    }

    if(!isServerRunning) {
        isServerRunning = true;
        timerID = setInterval(function() {
            var counter = Math.round(Date.now() / 1000 );
            for(var OCID in timers) {
                if(!timers.hasOwnProperty(OCID)) continue;

                var timer = timers[OCID];

                if(timer.prevCounter !== counter &&
                    counter / timer.interval === Math.round(counter / timer.interval) ) {
                    log.debug('Starting ', OCID, '; time interval: ', timer.interval, '; counter: ', counter);
                    timer.prevCounter = counter;
                    timer.callback(null, counter*1000);
                }
            }
        }, 333); // 1000 or less for increase accuracy
    }

    log.info('Adding a new timer for objectCounterID: ', prms.$id, ' with interval ', prms.wakeupInterval);
    timers[prms.$id] = {
        interval: parseInt(prms.wakeupInterval, 10),
        callback: callback
    };
};

collector.removeCounters = function(OCIDs, callback) {
    if(!Object.keys(timers).length) return callback();

    var removedOCIDs = [];
    OCIDs.forEach(function(OCID) {
        if(timers[OCID] !== undefined) {
            removedOCIDs.push(OCID);
            delete timers[OCID];
        }
    });
    if(removedOCIDs.length) log.info('Complete removed timers for objectsCountersIDs: ',  removedOCIDs);
    callback();
};

collector.destroy = function (callback) {
    log.debug('Receiving signal for destroying collector');

    if(timerID !== undefined) {
        clearInterval(timerID);
        timerID = undefined;
    }

    timers = {};
    isServerRunning = false;

    log.info('Complete destroyed timer counter');
    callback();
};

help\index.ru.pug - страница помощи с описанием действия

Для формирования страниц помощи используется шаблонизатор PUG , который, используя препроцессор, формирует HTML страницу. Никаких специальных требований к странице помощи нет. Для того, чтобы все компоненты интерфейса ALEPIZ были созданы в одном стиле, желательно использовать готовый шаблон, предоставляемый Collector editor и элементы фреймворка materializecss.

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

Оглавление добавляется в первый элемент на странице с классом offset-m1
Нижний колонтитул будет добавлен в элемент с тегом body
copyright формируется из элемента meta("author"), например meta(name="author" content="Alexander Belov <asbel@alepiz.com>") добавит соответствующий copyright и ссылку для составления почтового сообщения. Год формируется из document.lastModified || document.lastModifiedDate
плавающий элемент слева для перехода к верхней части страницы будет добавлен в элемент с тегом main