Агент

Агент СПП

Эксплуатация

Эксплуатация

Системные требования Windows

Для работы агента СПП необходима 64-битная операционная система windows 8/Windows Server 2012 или более новые версии.

Эксплуатация

Установка в windows

  1. Распакуйте файлы поставки
  2. Отредактируйте конфиг
  3. Запустите install.bat (понадобятся права администратора)
Эксплуатация

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

Конфигурация в Windows осуществляется через файл .env. Конфигуряция в Linux осуществляетв через файл .env ИЛИ через переменные среды (файл .env имеет больший приоритет).

Файл .env должен располагаться в одном каталоге с запускаемым файлом агента. В файле .env задаются параметры агента в формате ИМЯ_ПАРАМЕТРА=ЗНАЧЕНИЕ_ПАРАМЕТРА. Каждый параметр должен быть описан в отдельной строке (1 параметр - 1 строка).

Параметры агента:

 

При конфигурировании .env файла по дефолту будет использоваться СУБД sqlite, но есть возможность использовать Postgres

  • CFG_POSTGRES_DB - имя БД
  • CFG_POSTGRES_USER - имя пользователя БД
  • CFG_POSTGRES_PASSWORD - пароль от БД
  • CFG_POSTGRES_PORT - порт для подключения
  • CFG_POSTGRES_HOST - хост

Также дополнительные параметры настройки postgres описаны тут

При возникновении следующей ошибки следует проверить логин, пароль и имя самой БД
Screenshot from 2024-08-16 12-06-33.png

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

 

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

Для запуска конфигурации необходимо зайти на страницу http://127.0.0.1:CFG_API_PORT/config

Где CFG_API_PORT - это порт на котором запущен агент.

По умолчанию отображаются не все настройки. Для доступа ко всем настройкам:

http://127.0.0.1:CFG_API_PORT/config?full_config=true

Агент принимает запросы только локальные запросы (из той же системы на которой сам установлен)

 

Эксплуатация

Настройки датчиков для работы с агентом

Для приема метрик с устройств на самих устройствах нужно настроить HTTP выгрузку на агент.

Url для выгрузки с датчиков составляется по схеме:

http://IP:PORT/collector/metrics - для метрик
http://IP:PORT/collector/alarm - для лога

где IP - ip адрес устройства, на котором установлен агент

PORT - значение параметра CFG_API_PORT из конфига агента

Эксплуатация

Процесс работы автоматического обновления агента

Описание

Автоматические обновления работают только для собранных версий для windows и работающих в качестве службы windows. При CFG_AGENT_UPGRADE_AUTO=1 агент в соответствии с CRON-расписанием заданным в CFG_AGENT_UPGRADE_AUTO_CRON запускает процесс проверки обновлений.

  1. Подключение в FTP серверу.
    1. Адрес сервера: CFG_AGENT_UPGRADE_FTP_HOST:CFG_AGENT_UPGRADE_FTP_HOST
    2. Логин: CFG_AGENT_UPGRADE_FTP_USER
    3. Пароль: CFG_AGENT_UPGRADE_FTP_PASSWORD
  2. Получение списка файлов в папке CFG_AGENT_UPGRADE_FTP_PATH на сервере
  3. Определение наличия более новых версий агента по полученному списку
  4. Скачивание дистрибутивов всех новых версий
  5. Обновление

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

Сборка и публикация дистрибутива

Для сборки дистрибутива необходим python версии 3.11. В корне репозитория агента лежат скрипты для сборки агента

  1. Запускаем соответствующий скрипт для сборки дистрибутива 
  2. В случае успешной сборки ищем архив с дистрибутивом в папке build (например win_collector.agent_1.1.16.zip)
  3. Копируем архив с дистрибутивом на FTP сервер
Эксплуатация

Матрица команд

  3dh 3db 3dx 3dv 3hx 3dm 3dd 3dt cm

upload_data

 ✔ ✔ ✔ ✔ ✘ ✘[1] ✔ ✔ ✔
reboot ✔ ✔ ✔ ✔ ✘ ✔ ✘ ✔ ✘[2]
get_config ✔ ✔ ✔ ✔ ✘ ✔ ✔ ✔ ✘[2]
set_config ✔ ✔ ✔ ✔ ✘ ✔ ✔ ✔ ✘[2]
reset_auth ✔[3] ✔ ✔[3] ✔ ✘ ✔[3] ✘ ✔ ✘[2]
flash ✘ ✔ ✔ ✔ ✘ ✘ ✘ ✘ ✘[2]
screenshot ✔ ✔ ✔[4] ✔[4] ✘ ✔[5] ✘[7] ✘[7] ✘[2]
video_record ✔ ✔ ✔ ✔ ✘ ✘[6] ✘[7] ✔ ✘[2]
  1. Устройство не поддерживает выгрузку исторических данных
  2. Нет поддержки в текущей реализации (есть ли поддержка на самом устройстве не проверялось)
  3. Используется только пароль. Имя пользователя всегда 'admin'
  4. Поддержка мультисенсора
  5. Есть поддержка мультисенсора на устройстве, но пока не реализовано
  6. Нет поддержки выгрузки по расписанию (выгружается постоянно)
  7. Видео поток транслируется через веб сокет. документации по формату не нашел

 

Эксплуатация

Механизм восполнения пробелов в метриках

Проблема

Метрики поступают в агент неравномерно. Некоторые устройства не могут прислать метрики из-за проблем с сетью или по причине того что они выключены. Для исключения пробелов в метриках был реализован механизм восполнения пробелов в метриках

Реализация

Для реализации механизма понадобилось переработать хранение метрик в локальной базе агента - удаление метрик после отправки заменил на установку флага синхронизации. Сами метрики хранятся в локальной базе агента в течении N дней (задается в переменной CFG_AGENT_METRICS_AGE_MAX_DAYS).

В механизме используются следующие сущности метрики:

gap_checker производит анализ метрик в локальной базе

Промежуток времени не содержит метрики если истинно одно из условий

Механизм работает следующим образом:

  1. По расписанию (задается в переменной CFG_AGENT_METRICS_CHECK_GAPS_CRON) запускается функция выявления пробелов (далее gap_checker)
  2. При CFG_AGENT_METRICS_CHECK_GAPS_ENABLED != 1 выполнение завершается
  3. Для каждого зарегистрированного (is_new == False) устройства с выключенным пассивным режимом и поддерживающим команду upload_data gap_checker просматривает все метрики в локальной базе за промежуток с CHECKER_PERIOD_START до CHECKER_PERIOD_END.
  4. Если gap_checker находит промежутки времени, не содержащие ни одной метрики
    1. Скачивание исторических данных с устройства по каждому промежутку
Эксплуатация

Поддерживаемые типы метрик устройств

Тип датчика Форматы
3dx

xml - для версий старше 5.3

json - для версий новее 5.3
3dv xml
3dh xml
3db xml
3dt json
3dm json
3dd json
Эксплуатация

Кэширование метрик

В агенте реализовано сохранение метрик в кэш перед записью (Ранее часто встречалась ситуация что метрики в базу пишутся по одному, что замедляло общую работу агента), после включения кэша метрики перед отправкой в БД формируют чанки происходит массовая вставка.

Кэш устанавливается через env файл:

Важно!

Размер кэша не следует ставить больше чем 999 (В таком случае возможны ошибки, детальное тестирование с большим размером кэша не проводилось).

Кэш работает только с теми метриками у которых в момент записи включена опция ингорирования дубликатов, т.е. метрика не может перезаписываться. (Соответственно команда upload_data не использует кэширование)

Разработка

Разработка

Конфиг устройства

Обобщенный вид конфига

{
  	"network": NETWORK,
	"identification": IDENTIFICATION,
	"ntp": NTP,
	"sensors": SENSORS,
	"data_push": DATA_PUSH,
	"meta_info": META
}

 

NETWORK

Настройки сети на устройстве

{
	"ip": "IP",
	"gateway": "GATEWAY",
	"mask": "MASK",
	"dns": "DNS",
	"dns2": "DNS_2"
}

IDENTIFICATION

Параметры идентификации устройства

{
	"name": "NAME",
	"device_group": "DEVICE_GROUP",
	"model": "MODEL",
	"firmware": "FIRMWARE",
	"serial": "SERIAL",
	"mac": "MAC",
	"serial_as_name": SERIAL_AS_NAME
}

NTP

Настройки синхронизации времени

{
	"host": "HOST",
	"set_gateway_as_ntp": GATEWAY_AS_NTP,
	"timezone": TIMEZONE,
	"sync_protocol": "SYNC_PROTOCOL",
	"sync_period": "SYNC_PERIOD"
}

SENSORS

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

[
	...,
    
    {
    	"id": "SENSOR_ID",
  		"height_filter_max": HEIGHT_FILTER_MAX,
  		"height_filter_min": HEIGHT_FILTER_MIN,
  		"human": HUMAN
    },
    
    ...,
]

DATA_PUSH

Настройки выгрузок данных с устройства

[
  	...,

    {
        "type": "TYPE",
        "host": "HOST",
        "intervals": INTERVALS,
        "options": OPTIONS,
        "auth": AUTH,
        "path": PATH
    },
  
	...,
]
TYPE

Тип выгрузки

HOST

URL для выгрузки данных в формате SCHEME://HOST[:PORT][/PATH]. . Можно изменять в конфигурационном файле

В выгрузках с TYPE==passive_count валидация поля не происходит.

INTERVALS

Интервалы сбора/выгрузки данных

{
	"push": INTERVALS_PUSH,
  	"aggregation": INTERVALS_AGGREGATION
}

 

OPTIONS

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

{
	"format": "FORMAT",
	"upload_record": "UPLOAD_RECORD",
  	"device_localtime": "DEVICE_LOCALTIME",
  	"report_lite_mode": "REPORT_LITE_MODE"
}
AUTH

Параметры для авторизации на сервере выгрузок. Пока только для FTP выгрузок

{
	"user": "USER",
	"password": "PASSWD"
}
PATH

Параметры сохранения на FTP сервере

{
	"location": "LOCATION",
	"filename": "FILENAME"
}

META

Раздел с мета-информацией устройства при команде запросе конфига. При команде установки конфига игнорируется

{
	"timezone_name": "TIMEZONE",
    "time_offset": TIME_OFFSET,
    "time_sync_enabled": TIME_SYNC_ENABLED,
    "log_enabled": LOG_ENABLED,
    "multisensor": MULTISENSOR,
  	"slave_sensors": [
      	...,
		{
      		"ip": "SLAVE_SENSOR_IP"
      	},
		...
    ],
    "device_heigth": DEVICE_HEIHTH
}
Разработка

Команды от сервиса/1с

Процесс обработки команд

Механизм получения команд и отчета о выполнении команд

Шедулер агента по cron расписанию из параметра CFG_AGENT_CHECK_CRON запускает задачу запроса к сервису/1c для получения новых задач и отчета о выполнении более старых задач.

Есть возможность запуска задачи запроса к сервису/1c вне расписания. Для этого нужно сделать POST запрос (далее запрос-триггер) к агенту по адресу AGENT_HOST:CFG_API_PORT/agent/commands_check

При получении запроса-триггера агент проверит дату последнего запроса к сервису. Если с момента прошлого запроса прошло более CFG_AGENT_CHECK_UNCHEDULED_DELAY секунд, то запрос к сервису выполнится сразу. Иначе запрос к сервису будет выполнен, когда после последнего запроса к сервису пройдет CFG_AGENT_CHECK_UNCHEDULED_DELAY секунд.

Запрос к сервису/1с

Агент получает команды от сервиса/1с и отчитывается о выполнении команд путем POST запроса по адресу CFG_COLLECTOR_SERVICE_BASE/agent/check (CFG_COLLECTOR_SERVICE_BASE берется из конфига агента)

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

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

Данные запроса

{
	"health": {
		"last_report_at": LAST_REPORT_AT,
		"status": "STATUS",
		"activity": "ACTIVITY",
		"up_time": UPTIME
	},
	"executed_commands": [
    	...,
      	{
      		"command_id": "COMMAND_ID",
      		"device_id": [..., "DEVICE_ID", ...],
  			"command": "COMMAND",
    		"result": RESULT
      	},
		...
    ]
}

Ожидаемый ответ

{
    "commands":[
      	...,
      	{
            "command_id": "COMMAND_ID",
            "device_id": [..., "DEVICE_ID", ...],
            "command": "COMMAND",
            "params": PARAMS
        },
		...
    ]
}

Механизм выполнения команды

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

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

После завершения выполнения команды агент делает внеочередной запрос agent/check для отчета о выполнении команды.

 

Список команд

screenshot

получение скриншота с устройства.

params
{
    "host": "FTP_HOST",
    "user": "FTP_USERNAME",
    "password": "FTP_PASSWORD",
    "path": "FTP_PATH",
    "multisensor": "MULTISENSOR_FLAG"
}
success payload
{
	"screenshot_path": "REMOTE_PATH"
}

upload_data

выгрузка исторических данных с датчика

params
{
	"from": "FROM",
  	"to": "TO"
}
success payload
{}

reboot

перезагрузка устройства

params
{}
success payload
{}

get_config

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

params
{}
success payload
DEVICE_CONFIG

set_config

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

params
{
	"DEVICE_ID": DEVICE_CONFIG
}
success payload
DEVICE_CONFIG

reset_auth

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

params
{
	"user": "USERNAME",
  	"pass": "PASSWORD"
}
success payload
{
	"new_user": "USERNAME",
  	"new_pass": "PASSWORD"
}

executor_flash

обновление прошивки на устройстве

params
{
	"file_name": FILENAME,
  	"image": IMAGE,
  	"timeout": TIMEOUT
}
success payload
{
	"firmware": "FIRMWARE"
}

video_record

установка расписания записи видео. работает 

params
{
	"from": "FROM",
  	"to": "TO",
  	"sd_card_format": "FORMAT_FLAG",
  	"quality": "QUALITY"
}
success payload
{}
Разработка

Работа с API сервиса/1с

GET agent/device?{page}=1&{per_page}=20

Получает актуальный список устройств

{
  	"new_devices": NEW_DEVICES,
    "devices":[
     	...
      
    	{
            "id": DEVICE_ID,
            "is_new": DEVICE_IS_NEW,
            "serial": DEVICE_SERIAL,
            "mac"   : DEVICE_MAC,
            "host"  : DEVICE_HOST,
            "adapter_id" : DEVICE_ADAPTER,          
            "login": DEVICE_LOGIN, 
            "password": DEVICE_PASSWORD,
            "timezone": DEVICE_TIMEZONE,
            "sensors": [
                ...
                {
                    "sensor_id": SENSOR_ID,
                    "line_id": SENSOR_LINE_ID
                },
                ...
            ]  
     	},
              
       	...
	],
    "pagination":{
        "page": 1,
        "per_page": 20,
        "pages": 2,
        "total": 40
    }
}

При получении списка устройств агент проводит сверку полученного списка (блок devices) со своей локальной базой:

POST agent/device

регистрация нового устройства в сервисе

тело запроса - строка json:

{
    "id": DEVICE_ID,
    "is_new": DEVICE_IS_NEW,
    "serial": SERIAL,
    "mac": MAC,
    "adapter_id": ADAPTER_ID,
    "sensors": [
    	...
      	{
        	"sensor_id": SENSOR_ID,
          	"line_id": SENSOR_LINE_ID
        },
      	...
    ],
    "host": HOST,
    "login": LOGIN,
    "password": PASSWORD,
    "time_zone": TIMEZONE
}

POST agent/check

Запрос

отчет о состоянии агента, отчет о выполненных командах

Тело запроса - строка json:

{
  	'health': {
    	"last_report_at": 0.0,
    	"status": STATUS,
    	"activity": "working",
    	"up_time": UPTIME
	},
	'executed_commands': EXECUTED_COMMANDS
}

EXECUTED_COMMANDS:

{
    "command_id": COMMAND_ID
    "device_id": DEVICES
    "command": COMMAND
    "result": COMMAND_RESULT
}

COMMAND_RESULT:

{
	"error_flag": ERROR_FLAG,
  	"message": MESSAGE,
  	"payload": [
    	...
      	{
        	"error_flag": PAYLOAD_ERROR_FLAG,
          	"message": PAYLOAD_MESSAGE,
          	"payload": PAYLOAD_PAYLOAD,
          	"device_id": PAYLOAD_DEVICE_ID
        }
      
      	...
    ]
}
Ответ
{
	...
  	"payload": {
    	"commands": [
        	...
          	{
            	"command_id": COMMAND_ID,
              	"device_id": DEVICES,
              	"command": COMMAND,
              	"params": COMMAND_PARAMS
            }
          	...
        ]
    }
  	...
}

описание команд и их параметров

 

 

Разработка

Локальная база агента

Разработка

Поддержка пассивной выгрузки метрик

Датчик Поддержка пассивной выгрузки
3db ✘
3dd ✔
3dh ✔
3dm ✘
3dt ✘
3dv ✔
3dx ✔
cm* ✔[1]
  1. Только пассивная выгрузка
Разработка

Опциональное подключение и настройка PostgreSQL

Для корректной работы Postgres необходимо заполнить поля в .env:

CFG_POSTGRES_MODE=1 # При 0 - деактивируем мод
CFG_POSTGRES_DB=postgres
CFG_POSTGRES_USER=postgres
CFG_POSTGRES_PASSWORD=postgres
CFG_POSTGRES_PORT=5432
CFG_POSTGRES_HOST=localhost

Также был заложен функционал настройки одновременного количества подключений в файле database.py
Screenshot from 2024-08-07 18-42-45.png
Разработка

Настройка режима делегата

Делегат настраивается с двух сторон: в нашем контуре и в контуре клиента. Связываются агенты между собой по websocket и команды нужно направлять на агент который в нашем контуре

Конфигурация .env файла:

В нашем контуре:

CFG_PRODTESTING_DELEGATE_MODE - Активация принимающего вебсокет эндпоинта

В контуре клиента: