Python-скрипты — Макс Пастухов

Analytics Agent можно расширять своими скриптами на Python: они лежат обычными файлами рядом с настройками и подключаются к обработке данных. Дорабатывать само приложение не нужно — положили файл, и новая возможность уже работает, без сборки и перезапуска. Скрипт подходит там, где встроенных средств не хватает: подключить сервис, у которого нет готового источника, досчитать или переименовать результаты запроса, посчитать условие тревоги по-своему, отправить уведомление нестандартным способом.

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

Где лежат скрипты

Все скрипты живут в папке /project/apps/analytics/scripts/ — в том же постоянном томе, что документы и источники данных. Один скрипт — один JSON-файл с настройками:

{
  "title": "Заказы из вашей системы",
  "notes": "Что делает скрипт",
  "file": "orders.py",
  "timeoutSec": 120,
  "env": { "CRM_BASE_URL": "https://crm.example.com" },
  "args": { "pageSize": 100 }
}

код — либо прямо в файле настроек, либо отдельным файлом .py рядом с ним: как удобнее;
название и заметки — чтобы через полгода было понятно, что это и зачем;
таймаут — сколько секунд ждать ответа (по умолчанию 60, потолок — 10 минут);
переменные окружения — постоянные значения для запуска: адреса, ключи доступа. Можно также указать, какие переменные окружения сервера передавать скрипту;
аргументы — готовые значения на каждый запуск; их можно переопределить в конкретном месте подключения.

Библиотеки, которые нужны скриптам, перечисляются в одном общем файле scripts/requirements.txt. Окружение Python приложение готовит само при первом запуске — отдельно его настраивать не нужно.

Четыре точки подключения

Один и тот же скрипт подключается в четырёх местах конвейера аналитики:

Источник данных — запросы к скрипту вместо базы: подойдёт любой сервис, у которого есть клиент на Python. Такой источник работает везде, где работают обычные: в графиках, таблицах, проверках, правилах оповещений и выгрузке в PDF (подробнее — Источники данных);
Обработка результата запроса — скрипт получает готовую таблицу и возвращает её же, но переименованной, отфильтрованной, дополненной или досчитанной (подробнее — Запросы);
Условие тревоги — свой расчёт прямо в правиле оповещения: сложная формула, внешние данные, модель оценки (подробнее — Оповещения);
Доставка уведомления — канал, которого нет среди готовых: скрипт получает текст уведомления и сам решает, куда и как его отправить (подробнее — Оповещения).

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

Как проходит запуск

скрипту на вход приходит один документ JSON — точка подключения, данные запроса, аргументы; читается он привычным json.load(sys.stdin);
ответ — тоже JSON: последний цельный объект, который скрипт напечатал. Сообщения о ходе работы печатать можно — они не мешают;
у каждого скрипта есть своя рабочая папка, которая сохраняется между запусками: там удобно держать файлы, курсоры и промежуточные результаты;
размер данных ограничен: если данных много, передавайте не сами данные, а ссылку или файл в рабочей папке;
одновременных запусков ограниченное число — чтобы скрипты не перегружали сервер.

Раздел «Скрипты»

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

состояние среды сверху: готов ли Python, собран ли набор библиотек, сколько запусков и сбоев было за сутки, что случилось в прошлый раз;
карточки скриптов: название, откуда берётся код, когда запускался в последний раз;
журнал запусков: время, точка подключения, результат или понятная причина сбоя, фильтры по состоянию и точке;
тестовый запуск: задали аргументы и данные, нажали «Запустить» — результат тут же появился в журнале, как от обычного запуска;
журнал хранится заданный срок (по умолчанию 30 дней) и чистится сам.

Если скрипт сломался

Сбой скрипта никогда не подменяет данные: отчёт, график или тревога показывают понятную ошибку — что именно не получилось (скрипт не найден, превышено время ожидания, ответ не разобран) — и не показывают вместо этого что-то своё. Причина сбоя всегда видна в журнале запусков.

Запуски можно выключить одним переключателем — тогда все точки подключения честно сообщат, что скрипты отключены, а не сделают вид, что всё в порядке. Первый запуск бывает медленным: в этот момент собирается окружение и ставятся библиотеки.

Граница доверия

Скрипты — это ваш собственный код, и запускаются они с правами приложения: отдельной изоляции между скриптом и сервером нет. Поэтому держите их в Git вместе с проектом, а не запускайте чужие файлы. Если нужна полная изоляция — разворачивайте всё приложение в отдельном контейнере, что и делает стандартная установка.

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

← Оглавление документации