Мониторинг автоматизаций Pilot в Grafana
Сбор статистики применения сценариев автоматизации из automation.log в PostgreSQL
и визуализация в Grafana: три таблицы и два графика с выбором периода и сравнением дат.
1. Что именно считаем
В automation.log три принципиально разных исхода, и только два из них - проблемы.
| Запись в логе | Смысл | Как считаем |
|---|---|---|
STARTED '<триггер>' TRIGGER FROM '<сценарий>' SCRIPT |
триггер сработал, начата проверка условий | started - попытка |
ENDED '<триггер>' TRIGGER FROM '<сценарий>' SCRIPT |
сценарий отработал до конца | ended - применение |
Started activity - '<активность>'(...) |
внутри сценария выполнена активность | activity - справочно |
Failed to evaluate '<параметр>' parameter, expected=..., but was=... |
объект не подошёл под условие | skipped - норма, не ошибка |
Activity <X> from <сценарий> has not been found. |
сценарий ссылается на несуществующую активность | activity_not_found - ошибка |
ERROR [AutomationLog] '{...}' cannot be parsed because of error ... |
JSON сценария не разбирается | error - ошибка |
Два важных нюанса, которые определяют устройство парсера:
1. Failed to evaluate и Started activity не содержат имени сценария. Оно берётся
из последней строки STARTED в том же потоке ([21], [14] - число в квадратных
скобках). Парсер ведёт контекст по каждому потоку отдельно.
2. Блок ERROR не содержит имени сценария вообще - в нём только сам JSON и текст
ошибки десериализации, растянутые на несколько строк. Привязывать такую ошибку к
последнему STARTED нельзя: это дало бы заведомо неверную статистику. Поэтому ошибки
разбора группируются по триггеру (when), составу активностей и отпечатку JSON (fp),
а в поле «Сценарий» попадает <не определён: ошибка разбора JSON>. Найти виновника в
myAdmin можно по этим признакам.
Типичная причина cannot be parsed: определение сценария записано объектом {...},
тогда как Pilot ожидает массив [...]. В тексте ошибки это выглядит как
the type requires a JSON array (e.g. [1,2,3]) to deserialize correctly.
2. Включение логирования
Документация: Логирование скриптов автоматизации
Статистика собирается только с теста и стейджа. На проде логирование автоматизаций выключено: лог быстро растёт, а статистика прода не нужна.
| Контур | IsAutomationLoggingEnabled |
Сборщик |
|---|---|---|
| prod | false |
нет |
| test | true |
automation-metrics-test |
| stage | true |
automation-metrics-stage |
Параметр меняется в админке / «Серверы», а не правкой settings.xml руками. Админка пишет
C:\Ascon-Docker\<контур>\server-settings\server-settings.conf, обёртка запуска сервера (wait-for-postgres.sh)
переносит значение в settings.xml при старте контейнера. Чтобы настройка вступила в силу, перезапустите контейнер:
docker restart pilot-server-test
Файл появится в каталоге логов контура: C:\Ascon-Docker\<контур>\logs\automation.log
(внутри контейнера - /App/logs). Если его там нет, найти фактический путь:
docker exec pilot-server-test sh -c "find / -name 'automation.log' 2>/dev/null"
Логирование заметно увеличивает объём записи на диск: в примере за 50 минут работы набралось ~5000 строк - поэтому на проде оно выключено.
Клиентская часть логируется отдельно - клиент запускается с ключом logAutomation,
лог пишется в %appdata%\ASCON\<продукт>\Logs\automation.log. Для отладки самих
сценариев он часто информативнее серверного.
3. База данных для метрик
Все контуры пишут в одну базу pilot_metrics на postgres-prod, контур указан в колонке env. База и роли metrics_writer (сборщики пишут под ней и создают свои таблицы) и metrics_reader (Grafana, только чтение) создаются при первом старте контейнера на пустой папке данных (prod/init/postgres/02-metrics-roles.sh), схема и таблицы - парсером при первом запуске. Если контур создан раньше (база принадлежит pilotuser) или базы нет, приведите её (идемпотентно; пароли берутся из окружения контейнера - METRICS_WRITER_PASSWORD и METRICS_READER_PASSWORD в prod/.env):
docker exec postgres-prod bash /docker-entrypoint-initdb.d/02-metrics-roles.sh
Структура таблицы metrics.automation_events:
| Колонка | Смысл |
|---|---|
env |
контур: test / stage |
node |
метка узла кластера; пусто, если лог один (см. §4.4) |
ts |
время события |
kind |
started, ended, skipped, activity, activity_not_found, error |
script |
имя сценария |
trigger_name |
имя триггера (AttributeChanged, OrgUnitAttributeChanged, ...) |
detail |
подробности: несовпавший параметр, активность, отпечаток ошибки |
fingerprint |
отпечаток JSON для ошибок разбора |
is_error |
признак реальной ошибки (error или activity_not_found) |
event_key |
ключ дедупликации: хеш полей события, смещения его строки в файле и (если задан) узла - повторное чтение того же лога (в том числе --full) не задваивает данные |
4. Запуск парсера
Парсер читает лог инкрементально: смещение хранится в таблице metrics.automation_log_state (ключ env + node), поэтому повторные запуски обрабатывают только новые строки. Разбираются только полностью записанные строки: недописанный хвост лога и незавершённый многострочный блок ERROR в конце файла дочитываются следующим запуском (блок, уже подождавший один запуск, записывается как есть; если его хвост дописан позже, чем через INTERVAL, в БД останется обрезанная запись, а хвост будет пропущен: известное ограничение). Контекст потоков (последняя STARTED) хранится вместе со смещением, поэтому строки сразу после границы чтения получают имя сценария. Ротация определяется по размеру: файл стал меньше смещения - чтение с начала; если новый файл к следующему запуску уже длиннее смещения, ротация не замечается.
4.1. Контейнеры-сборщики
Постоянно работают контейнеры automation-metrics-test и automation-metrics-stage, они входят в compose-проект metrics. Каждые INTERVAL секунд (300) они дочитывают лог и пишут события в pilot_metrics. Сборщика для прода нет.
Контейнеру монтируется только каталог логов контура ${DATA_ROOT}/<контур>/logs как /App/logs:ro; других томов Pilot-Server (в них settings.xml с паролем PostgreSQL) сборщик не видит. Парсер только читает automation.log, больше ему ничего не нужно. Контейнер работает от непривилегированного пользователя (uid 10001), поэтому файл лога и каталог logs должны читаться «остальным» (o+r, каталог ещё и o+x). Какие права Pilot-Server выставляет на automation.log, на стенде не проверялось: проверьте ls -l ${DATA_ROOT}/<контур>/logs/automation.log. Если доступа нет, сборщик выведет «Нет прав на чтение» и завершится с кодом 3 (цикл напишет parser failed); исправьте права либо задайте user: root для сервиса в compose.
cd stack\metrics
docker compose up -d --build
docker logs -f automation-metrics-test
После правки automation_log_parser.py пересоберите образ той же командой.
4.2. Разово, с хоста
Нужно для отладки парсера. Понадобятся Python 3 и psycopg2. Параметры подключения посмотрите в automation_log_parser.py --help, роль metrics_writer и её пароль указаны в stack/metrics/.env (PG_USER, PG_PASSWORD):
pip install psycopg2-binary
python automation_log_parser.py --log "C:\Ascon-Docker\test\logs\automation.log" --env test --pg-host localhost --pg-port 5433
4.3. Полезные параметры
| Параметр | Назначение |
|---|---|
--log |
путь к логу или список через запятую: пути, маски * и метки метка=путь (см. §4.4) |
--full |
перечитать лог целиком, игнорируя сохранённое смещение |
--env |
имя контура, попадает в колонку env |
--pg-db |
база метрик, по умолчанию pilot_metrics |
Проверка, что данные загрузились:
docker exec -ti postgres-prod psql -U metrics_writer -d pilot_metrics -c "SELECT kind, count(*) FROM metrics.automation_events GROUP BY kind ORDER BY 2 DESC;"
4.4. Кластер: логи нескольких узлов
--log (в контейнере переменная LOG_PATH) принимает список через запятую. Элемент списка: путь, маска или метка=путь. Метка узла пишется в колонку node; смещение и контекст потоков хранятся отдельно для каждого узла, потому что номера потоков [N] у узлов пересекаются. Ключ event_key включает узел, поэтому одинаковые строки двух узлов не склеиваются. Для маски метка берётся из имени родительского каталога.
Раскладка логов кластера: каждый узел пишет в свой каталог ${DATA_ROOT}/<контур>/logs/<узел>/ (монолит: ${DATA_ROOT}/<контур>/logs/). Том сборщика остаётся прежним (${DATA_ROOT}/<контур>/logs:/App/logs:ro), меняется только LOG_PATH у сервиса automation-metrics-<контур>:
LOG_PATH: /App/logs/*/automation.log # узлы node1, node2, ... по именам каталогов
LOG_PATH: node1=/App/logs/n1/automation.log,node2=/App/logs/n2/automation.log # или явные метки
Правила:
- Одиночный путь без запятой, маски и метки работает как раньше:
nodeпустой, ключи и состояние прежние. Строки, собранные до появления колонки, остаются с пустым узлом; при первом запуске новой версии таблицаautomation_log_stateпереключается на ключ(env, node)сама, повторный запуск ничего не меняет. - Маска нужна только для каталогов узлов (
logs/*/automation.log): метка берётся из имени родительского каталога даже при единственном совпадении, и/App/logs/automation*.logдал бы узелlogs. Лог монолита задавайте путём. - Переход существующего контура с одиночного пути на метку или маску читает лог заново с начала: состояние
(env, узел)новое, а узел входит в ключ события, поэтому история задвоится относительно строк с пустымnode. Перед сменойLOG_PATHочистите события контура (DELETE FROM metrics.automation_events WHERE env = '<контур>') или оставьте одиночный путь. - Маска, не нашедшая ни одного файла, считается ошибкой (код 2): тихого «ноля» не будет. Так же ошибка, если два файла получили один узел (например, два пути без меток): задайте метки.
- Если часть файлов недоступна (нет файла, нет прав), остальные всё равно разбираются, а код возврата ненулевой: цикл пишет
parser failed, причина выводится строкой выше. - Каждый узел должен писать лог в отдельный файл. Если оба узла пишут в один общий
automation.log, различить их нельзя: в строках лога идентификатора узла нет. - Права
o+rнужны на каждом файле иo+xна каждом каталоге узла (см. §4.1). Время в логе читается без часового пояса, поэтому у узлов должен совпадать часовой пояс.
Проверено на стенде с двумя узлами: сборщик читает оба лога, метки узлов pilot-test-1 и pilot-test-2: запись в PostgreSQL проверена на двух файлах-образцах (см. §10). Фактическую раскладку каталогов и ротацию логов узлов проверьте на месте.
В дашборде отдельной переменной узла нет: сводка по сценариям суммирует все узлы. Разбивка по узлам - запрос с GROUP BY node к metrics.automation_events.
5. Grafana
Grafana и источник данных pilot-metrics-prod подключаются вместе со стеком metrics, отдельно ставить ничего не нужно.
Дашборд в автоматическую загрузку не входит. Импорт: Dashboards / New / Import / Upload dashboard JSON file / grafana_dashboard_pilot_automation.json / источник pilot-metrics-prod. В установочном комплекте он подключается сам.
6. Что в дашборде
| Панель | Тип | Содержание |
|---|---|---|
| Сводка по автоматизациям | таблица | срабатывания, ошибки, отфильтровано, доля ошибок, время последнего события - по каждому сценарию |
| Сравнение с предыдущим периодом | таблица | текущий и предыдущий периоды рядом, дельта срабатываний и ошибок, прирост в процентах |
| Количество применений | график | столбцы по интервалам, с разбивкой по сценариям |
| Количество ошибок | график | то же для ошибок, с разделением по типу |
| Детализация ошибок | таблица | текст ошибки, отпечаток, число повторов, первое и последнее появление |
Переменные вверху дашборда:
- Контур - фильтр по
env: test / stage (можно выбрать оба). Прод в дашборде не показывается - его статистика не собирается; - Сравнить с периодом назад - сдвиг для второй таблицы: 1, 7, 14 или 30 дней.
Период задаётся стандартным выбором времени Grafana в правом верхнем углу. Вторая таблица автоматически берёт тот же по длине интервал, сдвинутый назад на выбранную величину: выбрав «последние 7 дней» и сдвиг «7 days», получите сравнение этой недели с прошлой.
7. Примеры запросов для своих панелей
Топ сценариев по срабатываниям:
SELECT script, count(*) AS runs
FROM metrics.automation_events
WHERE $__timeFilter(ts) AND kind = 'ended' AND env IN ($env)
GROUP BY script ORDER BY runs DESC LIMIT 10;
Соотношение срабатываний и отфильтрованных вызовов - показывает, насколько «шумный» сценарий (много запусков триггера при малом числе реальных применений):
SELECT script,
count(*) FILTER (WHERE kind = 'ended') AS applied,
count(*) FILTER (WHERE kind = 'skipped') AS filtered
FROM metrics.automation_events
WHERE $__timeFilter(ts) AND env IN ($env)
GROUP BY script ORDER BY filtered DESC;
Активности, выполняемые внутри сценариев:
SELECT detail AS activity, count(*)
FROM metrics.automation_events
WHERE $__timeFilter(ts) AND kind = 'activity' AND env IN ($env)
GROUP BY detail ORDER BY 2 DESC;
Суточная динамика ошибок:
SELECT date_trunc('day', ts) AS day, count(*)
FROM metrics.automation_events
WHERE $__timeFilter(ts) AND is_error AND env IN ($env)
GROUP BY 1 ORDER BY 1;
8. Обслуживание
Старые события удаляет сам сборщик: при каждом запуске (раз в INTERVAL) он пачками по 5000 строк, по индексу ts, удаляет из metrics.automation_events события старше STATS_RETENTION_DAYS суток (по умолчанию 30; 0 - не удалять, при каждом запуске предупреждение в stderr; отрицательное или нечисловое значение - код возврата 2). Таблица состояния чтения не затрагивается. Ошибка удаления пишется предупреждением, разбор лога не прерывается. Старше срока хранения данных в таблице и на дашборде нет; если лог перечитывают с начала, его старые события снова попадают в таблицу и удаляются при следующем запуске.
Ручная очистка (нужна только при STATS_RETENTION_DAYS=0), например старше 90 дней:
docker exec -ti postgres-prod psql -U metrics_writer -d pilot_metrics -c "DELETE FROM metrics.automation_events WHERE ts < now() - INTERVAL '90 days';"
Сброс состояния чтения, если нужно перечитать лог заново (для одного узла кластера добавьте AND node = 'node1'):
docker exec -ti postgres-prod psql -U metrics_writer -d pilot_metrics -c "DELETE FROM metrics.automation_log_state WHERE env = 'test';"
Дубли не появятся: event_key не зависит от места, с которого читается лог. Исключение - события, записанные сборщиком старее этой версии: у них ключ другой (в него входило смещение чтения), поэтому первое перечитывание с --full или после сброса состояния задвоит именно их. Перед таким перечитыванием удалите события контура:
docker exec -ti postgres-prod psql -U metrics_writer -d pilot_metrics -c "DELETE FROM metrics.automation_events WHERE env = 'test';"
9. Типовые проблемы
| Симптом | Причина | Решение |
|---|---|---|
automation.log не создаётся |
IsAutomationLoggingEnabled = false |
Админка / «Серверы» / включить, затем docker restart pilot-server-<контур> |
| В «Серверах» висит «Ожидает перезапуска» | Контейнер не перезапускался или создан без тома /server-settings |
docker restart; если applied.conf не появился - docker compose up -d pilot-server-<контур> |
Парсер: Файл не найден |
Лог пишется не в /App/logs |
Найти через find / -name 'automation.log', добавить том |
Парсер: Маска не нашла файлов / Узлы повторяются |
Кластер: маска LOG_PATH не совпала с каталогами узлов или два файла без разных меток |
Сверить LOG_PATH с каталогами в ${DATA_ROOT}/<контур>/logs, задать метки метка=путь (§4.4) |
Парсер: could not translate host name |
Указано имя контейнера, но контейнер не в той сети | docker network connect ИМЯ_СЕТИ ИМЯ_КОНТЕЙНЕРА |
Парсер: Connection refused |
Указан внешний порт вместо внутреннего | С именем контейнера всегда 5432 |
| В Grafana пусто | Период не совпадает с датами в логе | Расширить диапазон времени; проверить SELECT min(ts), max(ts) FROM metrics.automation_events; |
| Повторный запуск не добавляет событий | Так и задумано - читается только новое; в выводе «новых: 0» | Для полного перечитывания --full |
Много skipped у сценария |
Триггер срабатывает часто, условие отсеивает | Это не ошибка; сузить условия сценария, если мешает |
| Ошибки без имени сценария | В блоке ERROR имени нет |
Искать в myAdmin по триггеру и составу активностей из колонки «Подробности» |
10. Тесты
Разбор лога проверяется без базы данных (драйвер psycopg2 в тестах не нужен). Из этого каталога:
python -m unittest discover -s tests -v
Тесты проверяют разбор tests/automation.sample.log (49 событий), совпадение ключей при чтении по частям и целиком, недописанную строку и блок ERROR на границе чтения, перенос контекста потока, BOM и CRLF, а также список логов (пути, маски, метки), совместимость ключей без узла, разные ключи одинаковых событий двух узлов и параметры состояния по узлу, срок хранения (разбор значения, пачки, ошибка удаления, ноль и неверное значение в main). Запись в PostgreSQL автотестами не покрыта; при изменении схемы или main её проверяют вручную одноразовым postgres:16 (две копии образца по узлам, два прогона, дублей нет). В GitLab те же тесты запускает .gitlab-ci.yml.
Срок хранения событий - STATS_RETENTION_DAYS / --retention-days (30; см. §8). Пользователь БД по умолчанию - metrics_writer, пароль - password (параметр --pg-password, переменная PG_PASSWORD); пока он не задан явно, парсер пишет об этом предупреждение при каждом запуске.