pgBadger 13.3 вышел 3 ноября 2026 года,[1] и это как раз тот тихий maintenance-релиз, на который стоит обратить внимание, если вы держите PostgreSQL на своём VPS. Почему именно сейчас? General availability PostgreSQL 19 запланирована на 19 ноября 2026 года,[4] и у вас есть окно в две недели, чтобы сделать то, что перед major-апгрейдом пропускают почти все: посмотреть, что ваш текущий инстанс реально делает. Логи, которые PostgreSQL и так пишет, - это самый ценный источник данных на вашей машине: никаких агентов, никаких лишних демонов, только правда о медленных запросах, ошибках и сбросах на диск. pgBadger превращает этот сырой поток логов в один самодостаточный HTML-отчёт, который открывается в браузере.

Этот гайд покрывает весь цикл на Debian или Ubuntu: что нового в 13.3, установка, настройка PostgreSQL на нужное логирование, запуск отчётов вручную и по cron, и чтение разделов, которые действительно важны.

Что такое pgBadger, в одном абзаце

pgBadger - это анализатор логов PostgreSQL, созданный для скорости и выдающий детальные HTML5-отчёты из лог-файлов PostgreSQL.[1] Практические детали, важные для маленькой машины:[3]

  • Это один отдельный Perl-скрипт. Никаких Perl-модулей, расширений базы или агентов. Графики рисует встроенная JavaScript-библиотека (flotr2), так что единственное требование к машине - современный Perl, а остальное делает браузер.[3]
  • Он сам определяет формат логов (stderr, syslog, csvlog, jsonlog) и читает сжатые файлы напрямую - gzip, bzip2, lz4, xz, zip и zstd, утилита для распаковки определяется по расширению файла.[3]
  • Он распараллеливает парсинг по ядрам через -j N - это важно, когда кормишь его месяцем логов с нагруженного инстанса.[3]
  • Отчёты приближаются и сохраняются в PNG прямо из браузера, так что график можно утащить в тикет или в пост-мортем.[3]

Автор - Gilles Darold, он же автор ora2pg, стандартного инструмента миграции PostgreSQL.[1] pgBadger существует с 2012 года и распространяется под лицензией PostgreSQL.[3]

Что нового в 13.3

13.3 - maintenance-релиз: исправления багов и принятые патчи с прошлого релиза, без новых заглавных фич.[1] Но список фиксов необычно релевантен продакшену, а именно тогда fix-релиз и стоит ставить:

  • Исправлен двойной подсчёт auto_explain. Исполнение, попавшее и в log_min_duration_statement, и в auto_explain, считалось дважды; в 13.3 оно дедуплицируется.[1][2] Если auto_explain включён хоть где-то, ваши «топ запросов» до этого релиза были завышены.
  • --explode (отчёт на каждую базу) получил пачку фиксов: retention (-R) теперь применяется и к per-database HTML-отчётам, имена баз санитизируются перед использованием в путях, а календарь в incremental-режиме больше не выходит пустым.[2]
  • Watch-режим фильтрует удалённые логи на удалённом хосте вместо перекачки всего, что делает -w по SSH заметно дешевле на больших установках.[1][2]
  • Починена работа с multiline-запросами в нескольких местах - переносы строк в prepared-запросах, запросы, «разъехавшиеся» между временными файлами и отчётами.[2]
  • Параллельные запуски теперь безопасны по умолчанию: временные файлы db-list и last-parsed получают уникальные имена на каждый запуск, так что два процесса pgBadger не прочитают одни и те же файлы, если cron-задачи пересекутся.[1][2]
  • Мелочи, но полезные: фильтрация через --dbuser и по пользователю больше не теряет валидные запросы, строки «Query Parameters: …» из планов auto_explain обрабатываются, добавлена копия explain-плана.[1][2]

Если хоть что-то из этого про вашу установку - а auto_explain плюс incremental-отчёты по cron это описание большинства продакшен-машин - то 13.3 это та версия, на которой нужно быть.

Установка pgBadger на Debian или Ubuntu

Есть два пути. И Debian, и Ubuntu пакетируют pgBadger (apt install pgbadger),[6] и этого достаточно, если версия из репозитория вас устраивает. Для актуального релиза 13.3 документированный путь - tarball с GitHub:[3]

# 1. берём release-архив (текущий: v13.3)
wget https://github.com/darold/pgbadger/archive/refs/tags/v13.3.tar.gz
tar xzf v13.3.tar.gz
cd pgbadger-13.3/

# 2. собираем и ставим - по умолчанию pgbadger окажется в /usr/local/bin
perl Makefile.PL
make
sudo make install

По умолчанию скрипт ложится в /usr/local/bin/pgbadger, man-страница - в /usr/local/share/man/man1/pgbadger.1.[3] Если вы на дистрибутиве с RPM или хотите компоновку как в Debian, передайте INSTALLDIRS=vendor в Makefile.PL - именно так делает сам Debian.[3] Проверяем установку:

pgbadger -V
# pgBadger version 13.3

Настраиваем PostgreSQL на логи, которые pgBadger умеет есть

На Debian и Ubuntu PostgreSQL из коробки логирует в stderr, но без коллектора логов: обёртка pg_ctlcluster перенаправляет stderr сервера в один файл на кластер, /var/log/postgresql/postgresql-<версия>-<кластер>.log,[7] а дефолтный конфиг почти не пишет ничего полезного для анализа. log_destination по умолчанию равен stderr, а logging_collector - это фоновый процесс, который перехватывает эти stderr-сообщения и складывает их в ротируемые файлы; его log_directory по умолчанию - log внутри каталога данных, так что задайте его явно, если хотите, чтобы файлы остались в /var/log/postgresql/.[5] Дальше нужно сказать, что логировать. Ниже - ядро из рекомендаций pgBadger:[3]

# postgresql.conf - блок логирования, который нужен pgBadger
log_destination = 'stderr'
logging_collector = on
# держим файлы коллектора рядом с дефолтным логом Debian/Ubuntu
log_directory = '/var/log/postgresql'
log_filename = 'postgresql-%Y-%m-%d_%H%M%S.log'

# логирование медленных запросов: 0 логирует каждый запрос, 1000 - только >= 1s
log_min_duration_statement = 1000

# обязательны минимум time (%t, %m или %n) и процесс (%p или %c)
# расширенный вариант ниже даёт разбивки по пользователям/базам/приложениям/клиентам
log_line_prefix = '%t [%p]: user=%u,db=%d,app=%a,client=%h '

log_checkpoints = on
log_connections = on
log_disconnections = on
log_lock_waits = on
log_temp_files = 0
log_autovacuum_min_duration = 0
log_error_verbosity = default

Три ловушки, которые стоит проговорить явно:

  1. Не включайте log_statement = 'all'. pgBadger не парсит такой вывод, и хуже того: при log_statement = all через log_min_duration_statement не логируется вообще ничего.[3] Нужный вам регулятор - именно log_min_duration_statement; держите его на 0, чтобы логировать каждый запрос, или поднимите на нагруженном сервере, чтобы писать только медленные.[3]
  2. В log_line_prefix обязательно должны быть эскейпы времени и процесса. Точный формат дальше свободный - pgBadger поддерживает любой кастомный префикс, лишь бы в нём были %t/%m/%n и %p/%c.[3] Пример выше - документированный stderr-формат, открывающий в отчёте разбивки по пользователям, базам, приложениям и клиентам.
  3. Сообщения логов должны быть на английском. Парсер понимает только английский вывод, так что держите lc_messages на 'C' или 'en_US.UTF-8' - французская или русская локаль даст отчёт с пустыми или битыми текстами.[3] Если вы меняли это по другой причине - верните.

После правки перезагрузите конфиг (или перезапустите) и проверьте, что строки пошли:

sudo systemctl reload postgresql   # или: sudo systemctl restart postgresql

# в свежих строках лога должны быть длительности, подключения, checkpoints и т.д.
sudo tail -n 50 /var/log/postgresql/postgresql-*.log

log_temp_files = 0 важен: без него у pgBadger нет данных для отчёта о временных файлах - а это один из самых полезных разделов на VPS с ограниченной памятью (подробнее ниже).

Генерируем первый отчёт

Направьте pgBadger на снятые логи. Он принимает файл, список файлов, glob или - для stdin:[3]

# последний лог-файл (или уже ротированные)
pgbadger /var/log/postgresql/postgresql-2026-11-07_000000.log -o /var/www/pg_reports/weekly.html

# целая ротация, включая сжатую историю
pgbadger /var/log/postgresql/postgresql-*.log* -o /var/www/pg_reports/monthly.html

# все ядра на большой файл
pgbadger -j 8 /var/log/postgresql/postgresql-*.log* -o report.html

# только ошибки, в watch-режиме
pgbadger -q -w /var/log/postgresql/postgresql-*.log* -o /var/www/pg_reports/errors.html

На выходе - один самодостаточный HTML-файл со всем встроенным внутрь: его можно скопировать куда угодно по scp или отдавать вашим существующим nginx (наш гайд по reverse-proxy на nginx подскажет, как раздать его безопасно, если хотите выложить в веб).

Первый запуск - заодно момент проверить определение формата: если отчёт пустой или битый, принудительно задайте формат через -f stderr (или -f syslog, csvlog, jsonlog) и перечитайте совет про log_line_prefix выше.[3]

Запускаем как скучную cron-задачу

Cron-примеры из README - канонический паттерн, и это две основные формы, которые вы будете использовать:[3] (/usr/bin/pgbadger - путь apt-пакета; после установки из tarball скрипт лежит в /usr/local/bin/pgbadger - впишите в crontab то, что выводит command -v pgbadger.)

Еженедельный дайджест ошибок - каждый понедельник в 23:30, «письмо» только с ошибками:

30 23 * * 1 /usr/bin/pgbadger -q -w /var/log/postgresql/postgresql-*.log* -o /var/www/pg_reports/pg_errors.html

Incremental-отчёты - каждый день в 04:00, отчёт за день плюс накопительный отчёт за неделю:

0 4 * * * /usr/bin/pgbadger -I -q /var/log/postgresql/postgresql-*.log* -O /var/www/pg_reports/

В incremental-режиме (-I) pgBadger сначала пишет бинарные файлы данных и пересобирает HTML на каждом запуске; --retention N держит последние N недель и автоматически удаляет старые day/week директории, так что место на диске остаётся ограниченным без вашего участия.[3] Заодно это режим, где важен фикс конкурентности из 13.3: если запуск длится дольше cron-интервала, наивное пересечение раньше означало гонку двух процессов за одни temp-файлы - переназначаемые имена в 13.3 превращают это в не-событие.[1][2]

Один gotcha именно для cron: % в cron имеет особое значение. Если в команде есть подстановки вида date +%F, экранируйте их или вынесите в небольшой скрипт-обёртку.[3]

Читаем отчёт: разделы, которые важны

pgBadger генерирует много графиков; на self-hosted машине почти всю ценность несут пять разделов.[3]

Overall statistics. Сводка задаёт окно анализа, а столбики запросов, подключений и ошибок по часам - форму дня с одного взгляда. Часовой всплеск ошибок в 03:14, совпавший с вашими бэкапами по cron, - часто и есть вся история.

Топ медленных запросов и самые времязатратные запросы. Центральный раздел отчёта: нормализованные запросы, отсортированные по суммарной длительности, с количеством, средним и гистограммой времени выполнения по каждому запросу.[3] Не судите по одному медленному выбросу - сортируйте по суммарному времени. На OLTP-VPS вредят запросы, которые вы дёргаете десять тысяч раз в день по 50 мс, а не разовый 5-секундный отчёт ночью.

Temporary files. С включённым log_temp_files = 0 вы получаете отчёты о запросах, породивших больше всего и самых крупных временных файлов.[3] Каждый сброс сверх work_mem пишется на диск, и на VPS с burstable-SSD именно отсюда берётся «в дэве норм, а в проде странно тормозит». Если запрос появился здесь - это повод поговорить про work_mem или план запроса.

Отчёт об ошибках, включая deadlock-и. Каждое событие panic, fatal, error и warning собирается и классифицируется с таймлайном по каждому виду ошибок.[3] Ошибки deadlock detected попадают сюда автоматически - PostgreSQL логирует deadlock в момент разрешения, а pgBadger показывает сообщение, так что повторяющаяся запись про deadlock в графике ошибок говорит о проблеме с порядком блокировок в приложении, а не о тюнинге сервера. Watch-режим (-w) - версия раздела только для ошибок, задуманная как ваше утреннее письмо понедельника.[3]

Autovacuum и autoanalyze. С log_autovacuum_min_duration = 0 видно каждый прогон autovacuum и autoanalyze по таблицам, включая то, сколько он шёл.[3] Таблица с огромным, повторяющимся вакуумом в логах - это растущая проблема блоута или конфигурации, а блоут - ровно то, что адресует релиз 19. PostgreSQL 19 вводит REPACK - преемника VACUUM FULL, и если ваш доапгрейдный отчёт уже показал проблемную таблицу, это та самая таблица, которую стоит репаковать после миграции (полный план - в нашем гайде по апгрейду PostgreSQL 19).

Угол PG19: бейзлайн сейчас, сравнение после

Вот конкретный workflow, который делает тайминг релиза полезным. GA PostgreSQL 19 запланирован на 19 ноября 2026 года.[4] За две недели до него:

  1. Включите блок конфигурации выше и дайте ему собрать данные минимум за один полный рабочий день; не сравнивайте отчёт за вторник с отчётом за воскресенье.
  2. Сгенерируйте полный incremental-отчёт через -I и сохраните выходную директорию.
  3. После апгрейда на 19 сгенерируйте такой же отчёт и сравните топ-20 медленных запросов, раздел временных файлов и таблицу autovacuum.

Апгрейд, сохранивший планы запросов, но вдвое урезавший время temp files, - это успех, на который можно показать пальцем; апгрейд, поднявший запрос с 10-го на 2-е место в списке медленных, - это регрессия, которую вы поймаете в первый же день, а не на следующем инциденте. В любом случае вы работаете со своими измерениями, а не с ощущениями.

Итог

pgBadger 13.3 - maintenance-релиз с очень продакшен-форменным списком фиксов: корректные суммы auto_explain, безопасные параллельные запуски и вычищенный путь --explode.[1][2] На VPS с Debian или Ubuntu вы проходите путь от нуля до читаемого еженедельного отчёта примерно за пятнадцать минут: ставите tarball, включаете блок логирования, добавляете одну cron-строку. А до 19 ноября запускаете бейзлайн, с которым будете сравнивать после апгрейда на PostgreSQL 19.[4] Ваше будущее «я», делающее этот апгрейд в 23:00, скажет спасибо.

Источники

  1. PostgreSQL News - pgbadger v13.3 has been released (2026-11-03). https://www.postgresql.org/about/news/pgbadger-v133-has-been-released-3435/ - checked 2026-11-07
  2. GitHub - darold/pgbadger releases: Version 13.3 (2026-11-03). https://github.com/darold/pgbadger/releases/tag/v13.3 - checked 2026-11-07
  3. GitHub - darold/pgbadger README (installation, PostgreSQL configuration, options, incremental reports). https://github.com/darold/pgbadger - checked 2026-11-07
  4. PostgreSQL News - PostgreSQL 19 RC 1 Released! (2026-10-15; GA запланирован на 2026-11-19). https://www.postgresql.org/about/news/postgresql-19-rc-1-released-3409/ - checked 2026-11-07
  5. PostgreSQL Documentation 18 - Error Reporting and Logging (log_destination, logging_collector, log_min_duration_statement). https://www.postgresql.org/docs/current/runtime-config-logging.html - checked 2026-11-07
  6. Debian Packages - package pgbadger. https://packages.debian.org/search?keywords=pgbadger - checked 2026-11-07
  7. Debian - pg_ctlcluster(1), postgresql-common (start: лог-файл на кластер, по умолчанию /var/log/postgresql/postgresql-<версия>-<кластер>.log). https://manpages.debian.org/testing/postgresql-common/pg_ctlcluster.1.en.html - проверено 2026-11-07