Статусы выполнения (module_sdk.status)

Модуль может отправлять статусы выполнения в реальном времени через StatusSender. Статусы отображаются в UI в карточке выполнения автоправила и позволяют отслеживать прогресс, предупреждения и ошибки модуля.

Импорт

from module_sdk import status_sender, StatusType

StatusType

from module_sdk import StatusType

Значение	Описание
StatusType.INFO	Информационные сообщения (прогресс, этапы выполнения)
StatusType.WARNING	Предупреждения (модуль продолжил работу)
StatusType.ERROR	Критические ошибки (модуль не может продолжить)

StatusSender

from module_sdk import status_sender

Синглтон status_sender -- глобальный экземпляр, используется для отправки статусов выполнения модуля на Keeper.

Метод send_status()

status_sender.send_status(
    status_type: StatusType,  # Тип статуса
    message: str,             # Сообщение (отображается в UI)
    code: str = "",           # Машиночитаемый код (опционально)
    data: dict = None         # Дополнительные данные (опционально)
) -> bool

Возвращает True при успешной отправке, False -- при ошибке (например, Keeper недоступен). Ошибка отправки логируется, но не прерывает работу модуля.

Параметр	Тип	Обязательный	Описание
status_type	StatusType	да	Тип статуса (INFO, WARNING, ERROR)
message	str	да	Текстовое сообщение для отображения в UI
code	str	нет	Машиночитаемый код ошибки (см. таблицу кодов ниже)
data	dict	нет	Произвольные дополнительные данные в формате словаря

Коды статусов

Рекомендуемые коды для использования в параметре code:

Код	Тип	Описание
CONNECTION_ERROR	ERROR	Ошибка подключения к внешней системе
CREDENTIALS_ERROR	ERROR	Ошибка аутентификации (неверные учетные данные)
TIMEOUT	ERROR	Превышено время ожидания при подключении или выполнении
EXECUTION_ERROR	ERROR	Ошибка выполнения операции
MODULE_ERROR	ERROR	Внутренняя ошибка модуля
MODULE_WARNING	WARNING	Предупреждение модуля (некритичная проблема)
PARTIAL_DATA	WARNING	Получены неполные данные из внешней системы
RATE_LIMIT	WARNING	Достигнут лимит запросов к внешней системе

Коды не являются обязательными, но упрощают машинную обработку статусов и фильтрацию в UI.

Примеры использования

Базовый пример

from module_sdk import status_sender, StatusType

def my_scan():
    status_sender.send_status(StatusType.INFO, "Запуск сканирования")

    try:
        # подключение
        status_sender.send_status(StatusType.INFO, "Подключение к серверу")
        connect()
        status_sender.send_status(StatusType.INFO, "Подключение установлено")

        # сканирование
        results = scan()
        status_sender.send_status(
            StatusType.INFO,
            f"Найдено {len(results)} объектов",
            data={"count": len(results)}
        )

    except AuthError as e:
        status_sender.send_status(StatusType.ERROR, str(e), code="CREDENTIALS_ERROR")
        raise
    except ConnectionError as e:
        status_sender.send_status(StatusType.ERROR, str(e), code="CONNECTION_ERROR")
        raise
    except Exception as e:
        status_sender.send_status(StatusType.ERROR, str(e), code="MODULE_ERROR")
        raise

Пример с предупреждениями

from module_sdk import status_sender, StatusType

def collect_with_retries():
    for page in range(total_pages):
        try:
            data = fetch_page(page)
            process(data)
        except TimeoutError:
            status_sender.send_status(
                StatusType.WARNING,
                f"Таймаут при загрузке страницы {page}, пропущена",
                code="TIMEOUT",
                data={"page": page}
            )
            continue

    status_sender.send_status(StatusType.INFO, "Сбор данных завершен")

Рекомендуемые точки вызова

Момент	Тип	Код	Пример сообщения
Старт модуля	INFO	--	"Запуск сканирования"
Подключение к внешней системе	INFO	--	"Подключение к серверу 192.168.1.1"
Подключение установлено	INFO	--	"Подключение установлено"
Начало этапа обработки	INFO	--	"Сканирование портов"
Промежуточный прогресс	INFO	--	"Обработано 150 из 500 хостов"
Некритичная проблема	WARNING	MODULE_WARNING	"Хост 10.0.0.5 не отвечает, пропущен"
Неполные данные	WARNING	PARTIAL_DATA	"API вернул неполный ответ"
Ошибка аутентификации	ERROR	CREDENTIALS_ERROR	"Неверный API-ключ"
Ошибка подключения	ERROR	CONNECTION_ERROR	"Не удалось подключиться к серверу"
Таймаут	ERROR	TIMEOUT	"Превышено время ожидания"
Необработанная ошибка	ERROR	MODULE_ERROR	"Внутренняя ошибка модуля"
Завершение работы	INFO	--	"Найдено 42 хоста"

Переменные окружения

Переменная	Описание	Устанавливается
KEEPER_CALLBACK_URL	URL Keeper для отправки статусов	автоматически
MODULE_RUN_ID	ID текущего запуска модуля	автоматически

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

Как статусы отображаются в UI

Статусы отправляются модулем на Keeper через HTTP callback и далее передаются в WAS. В интерфейсе Solar LightHouse они отображаются в карточке выполнения автоправила:

• Статусы INFO показываются как информационные записи в журнале выполнения

• Статусы WARNING выделяются визуально и увеличивают счетчик предупреждений

• Статусы ERROR выделяются как критические и отображаются в блоке ошибок

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