Мониторинг автоматизаций 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); пока он не задан явно, парсер пишет об этом предупреждение при каждом запуске.