pgBadger 13.2 中文文档

• 1: 下载与安装
• 2: 命令行参考
• 3: PostgreSQL 日志配置
• 4: 并行处理
• 5: 增量报告
• 6: 输出格式
• 7: 报告示例
• 8: 版本历史
  • 8.1: pgBadger 13.x 版本记录
  • 8.2: pgBadger 12.x 版本记录
  • 8.3: pgBadger 11.x 版本记录
  • 8.4: pgBadger 10.x 版本记录
  • 8.5: pgBadger 9.x 版本记录
• 9: 支持与贡献
• 10: 许可证与致谢

pgBadger 是一款使用 Perl 编写的高性能独立 PostgreSQL 日志分析器。它可以读取 PostgreSQL 或 PgBouncer 日志，并生成 HTML、文本、二进制、JSON 或原始 CSV 输出。HTML 报告自带全部资源，图表可交互、缩放并保存为 PNG，只需浏览器即可查看。

为什么使用 pgBadger

pgBadger 面向大规模日志与日常运维场景设计：

• 单个 Perl 程序，不强制依赖非核心 Perl 模块；
• 自动识别 stderr、syslog、csvlog、jsonlog、RDS、Cloud SQL、logplex、Redshift 与 PgBouncer 日志；
• 可读取本地文件、标准输入、SSH 远程文件，以及 HTTP、FTP 或 SFTP URL；
• 支持 gzip、bzip2、lz4、xz、zip 与 zstd 压缩输入；
• 可并行分析一个大文件，或同时处理多个小文件；
• 自动生成每日、每周报告，并按需生成月度累计报告；
• 可按时间、数据库、用户、客户端、应用、进程、会话和查询模式过滤。

报告包含什么

PostgreSQL 报告覆盖：

• 整体活动与查询统计；
• 最慢、最频繁、总耗时最高、等待与被取消的查询；
• 临时文件、检查点、锁、会话与连接；
• 按表统计的 autovacuum 与 autoanalyze 活动；
• 按严重级别和类别汇总的错误与事件；
• 按数据库、用户、客户端、应用与语句类型展示的分布。

分析 PgBouncer 日志时，还会生成吞吐量、平均查询耗时、并发会话、连接与会话分布、保留连接池使用情况，以及高频错误/事件报告。

文档阅读顺序

可以按以下顺序阅读，也可以从侧边栏直接进入所需主题：

1. 下载并安装 pgBadger 与可选模块。
2. 查阅完整的命令行参考 。
3. 配置带有可解析前缀的 PostgreSQL 日志 。
4. 为日志规模选择合适的并行处理 模式。
5. 安全构建增量报告 。
6. 选择输出格式 ，并查看本地示例 。
7. 跟踪版本历史 ，了解支持渠道 与许可证 。

上游链接

• 项目网站
• 源代码
• 版本发布
• 问题追踪

1 - 下载与安装

选择分发渠道

本站文档快照基于 13.2 源码树。下载前始终应查看发布页面：本地快照为了可复现而固定，上游版本仍会继续更新。

运行要求

生成与查看 HTML 报告只需要：

• 一套现代 Perl 发行版；
• 一个可运行内嵌 JavaScript 图表的浏览器。

下列可选功能需要额外依赖：

在 Debian 或 Ubuntu 上安装 JSON 支持：

$ sudo apt-get install libjson-xs-perl

在基于 RPM 的系统上：

$ sudo yum install perl-JSON-XS

可通过 --zcat 指定解压程序路径。显式指定一个自定义命令后，同一次调用将不能再混合处理多种压缩格式。

从官方归档安装

下载版本归档后，使用 Perl 的标准工具链构建并安装：

$ tar xzf pgbadger-13.2.tar.gz
$ cd pgbadger-13.2
$ perl Makefile.PL
$ make
$ sudo make install

默认的 site 布局会把程序安装为 /usr/local/bin/pgbadger，把手册页安装为 /usr/local/share/man/man1/pgbadger.1。

若要按 Linux 发行版惯例安装到 /usr，可这样生成 Makefile：

$ perl Makefile.PL INSTALLDIRS=vendor
$ make
$ sudo make install

上游也支持 INSTALLDIRS=perl 布局。向受包管理器管理的系统安装前，应先检查生成的目标路径。

安装开发版源码

$ git clone https://github.com/darold/pgbadger.git
$ cd pgbadger
$ perl Makefile.PL
$ make
$ make test
$ sudo make install

开发分支可能包含尚未进入正式版本说明的改动。生产打包应优先使用带标签的发布归档，以保证可复现性。

验证安装

$ pgbadger --version
$ pgbadger --help

接下来请阅读命令行参考 与 PostgreSQL 日志配置 。

2 - 命令行参考

本页保留固定上游源码生成的完整命令参考。为了能与 pgbadger --help 逐项核对，参数名、帮助文字和命令示例均保留英文原文。

用法与选项

Usage: pgbadger [options] logfile […]

PostgreSQL log analyzer with fully detailed reports and graphs.

Arguments:

logfile can be a single log file, a list of files, or a shell command
returning a list of files. If you want to pass log content from stdin
use - as filename. Note that input from stdin will not work with csvlog.

Options:

-a | --average minutes : number of minutes to build the average graphs of
                         queries and connections. Default 5 minutes.
-A | --histo-average min: number of minutes to build the histogram graphs
                         of queries. Default 60 minutes.
-b | --begin datetime  : start date/time for the data to be parsed in log
                         (either a timestamp or a time)
-c | --dbclient host   : only report on entries for the given client host.
-C | --nocomment       : remove comments like /* ... */ from queries.
-d | --dbname database : only report on entries for the given database.
-D | --dns-resolv      : client ip addresses are replaced by their DNS name.
                         Be warned that this can really slow down pgBadger.
-e | --end datetime    : end date/time for the data to be parsed in log
                         (either a timestamp or a time)
-E | --explode         : explode the main report by generating one report
                         per database. Global information not related to a
                         database is added to the postgres database report.
-f | --format logtype  : possible values: syslog, syslog2, stderr, jsonlog,
                         csv, pgbouncer, logplex, rds and redshift. Use this
                         option when pgBadger is not able to detect the log
                         format.
-G | --nograph         : disable graphs on HTML output. Enabled by default.
-h | --help            : show this message and exit.
-H | --html-outdir path: path to directory where HTML report must be written
                         in incremental mode, binary files stay on directory
                         defined with -O, --outdir option.
-i | --ident name      : programname used as syslog ident. Default: postgres
-I | --incremental     : use incremental mode, reports will be generated by
                         days in a separate directory, --outdir must be set.
-j | --jobs number     : number of jobs to run at same time for a single log
                         file. Run as single by default or when working with
                         csvlog format.
-J | --Jobs number     : number of log files to parse in parallel. Process
                         one file at a time by default.
-l | --last-parsed file: allow incremental log parsing by registering the
                         last datetime and line parsed. Useful if you want
                         to watch errors since last run or if you want one
                         report per day with a log rotated each week.
-L | --logfile-list file:file containing a list of log files to parse.
-m | --maxlength size  : maximum length of a query, it will be restricted to
                         the given size. Default truncate size is 100000.
-M | --no-multiline    : do not collect multiline statements to avoid garbage
                         especially on errors that generate a huge report.
-N | --appname name    : only report on entries for given application name
-o | --outfile filename: define the filename for the output. Default depends
                         on the output format: out.html, out.txt, out.bin,
                         or out.json. This option can be used multiple times
                         to output several formats. To use json output, the
                         Perl module JSON::XS must be installed, to dump
                         output to stdout, use - as filename.
-O | --outdir path     : directory where out files must be saved.
-p | --prefix string   : the value of your custom log_line_prefix as
                         defined in your postgresql.conf. Only use it if you
                         aren't using one of the standard prefixes specified
                         in the pgBadger documentation, such as if your
                         prefix includes additional variables like client IP
                         or application name. MUST contain escape sequences
                         for time (%t, %m or %n) and processes (%p or %c).
                         See examples below.
-P | --no-prettify     : disable SQL queries prettify formatter.
-q | --quiet           : don't print anything to stdout, not even a progress
                         bar.
-Q | --query-numbering : add numbering of queries to the output when using
                         options --dump-all-queries or --normalized-only.
-r | --remote-host ip  : set the host where to execute the cat command on
                         remote log file to parse the file locally.
-R | --retention N     : number of weeks to keep in incremental mode. Defaults
                         to 0, disabled. Used to set the number of weeks to
                         keep in output directory. Older weeks and days
                         directories are automatically removed.
-s | --sample number   : number of query samples to store. Default: 3.
-S | --select-only     : only report SELECT queries.
-t | --top number      : number of queries to store/display. Default: 20.
-T | --title string    : change title of the HTML page report.
-u | --dbuser username : only report on entries for the given user.
-U | --exclude-user username : exclude entries for the specified user from
                         report. Can be used multiple time.
-v | --verbose         : enable verbose or debug mode. Disabled by default.
-V | --version         : show pgBadger version and exit.
-w | --watch-mode      : only report errors just like logwatch could do.
-W | --wide-char       : encode html output of queries into UTF8 to avoid
                         Perl message "Wide character in print".
-x | --extension       : output format. Values: text, html, bin or json.
                         Default: html
-X | --extra-files     : in incremental mode allow pgBadger to write CSS and
                         JS files in the output directory as separate files.
-z | --zcat exec_path  : set the full path to the zcat program. Use it if
                         zcat, bzcat or unzip is not in your path.
-Z | --timezone +/-XX  : Set the number of hours from GMT of the timezone.
                         Use this to adjust date/time in JavaScript graphs.
                         The value can be an integer, ex.: 2, or a float,
                         ex.: 2.5.
--anonymize            : obscure all literals in queries, useful to hide
--charset              : used to set the HTML charset to be used.
                         Default: utf-8.
--command CMD          : command to execute to retrieve log entries on
                         stdin. pgBadger will open a pipe to the command
                         and parse log entries generated by the command.
--csv-separator        : used to set the CSV field separator, default: ,
--day-report YYYY-MM-DD: create an HTML report over the specified day.
                         Requires incremental output directories and the
                         presence of all necessary binary data files
--disable-autovacuum   : do not generate autovacuum report.
                         confidential data.
--disable-checkpoint   : do not generate checkpoint/restartpoint report.
--disable-connection   : do not generate connection report.
--disable-error        : do not generate error report.
--disable-hourly       : do not generate hourly report.
--disable-lock         : do not generate lock report.
--disable-query        : do not generate query reports (slowest, most
                         frequent, queries by users, by database, ...).
--disable-session      : do not generate session report.
--disable-temporary    : do not generate temporary report.
--disable-type         : do not generate report of queries by type, database
                         or user.
--dump-all-queries     : dump all queries found in the log file replacing
                         bind parameters included in the queries at their
                         respective placeholders positions.
--dump-raw-csv         : parse the log and dump the information into CSV
                         format. No further processing is done, no report.
--enable-checksum      : used to add an md5 sum under each query report.
--exclude-appname name : exclude entries for the specified application name
                         from report.  Example: "pg_dump".  Can be used
                         multiple times.
--exclude-client name  : exclude log entries for the specified client ip.
                         Can be used multiple times.
--exclude-db name      : exclude entries for the specified database from
                         report. Example: "postgres". Can be used multiple
                         times.
--exclude-file filename: path of the file that contains each regex to use
                         to exclude queries from the report. One regex per
                         line.
--exclude-line regex   : exclude any log entry that will match the given
                         regex. Can be used multiple times.
--exclude-query regex  : any query matching the given regex will be excluded
                         from the report. For example: "^(VACUUM|COMMIT)"
                         You can use this option multiple times.
--exclude-time  regex  : any timestamp matching the given regex will be
                         excluded from the report. Example: "2013-04-12 .*"
                         You can use this option multiple times.
--explain-url URL      : use it to override the url of the graphical explain
                         tool. Default: https://explain.depesz.com/
--histogram-query VAL  : use custom inbound for query times histogram.
                        Default inbound in milliseconds:
                     0,1,5,10,25,50,100,500,1000,10000
--histogram-session VAL: use custom inbound for session times histogram.
                        Default inbound in milliseconds:
                     0,500,1000,30000,60000,600000,1800000,3600000,28800000
--include-file filename: path of the file that contains each regex to the
                         queries to include from the report. One regex per
                         line.
--include-query regex  : any query that does not match the given regex will
                         be excluded from the report. You can use this
                         option multiple times. For example: "(tbl1|tbl2)".
--include-pid PID      : only report events related to the session pid (%p).
                         Can be used multiple time.
--include-session ID   : only report events related to the session id (%c).
                         Can be used multiple time.
--include-time  regex  : only timestamps matching the given regex will be
                         included in the report. Example: "2013-04-12 .*"
                         You can use this option multiple times.
--iso-week-number      : in incremental mode, calendar weeks start on
                         Monday and respect the ISO 8601 week number, range
                         01 to 53, where week 1 is the first week that has
                         at least 4 days in the new year.
--keep-comments        : do not remove comments from normalized queries. It
                         can be useful if you want to distinguish between
                         same normalized queries.
--journalctl command   : command to use to replace PostgreSQL logfile by
                         a call to journalctl. Basically it might be:
                            journalctl -u postgresql-9.5
--log-duration         : force pgBadger to associate log entries generated
                         by both log_duration = on and log_statement = 'all'
--log-timezone +/-XX   : Set the number of hours from GMT of the timezone
                         that must be used to adjust date/time read from
                         log file before beeing parsed. Using this option
                         makes log search with a date/time more difficult.
                         The value can be an integer, ex.: 2, or a float,
                         ex.: 2.5.
--month-report YYYY-MM : create a cumulative HTML report over the specified
                         month. Requires incremental output directories and
                         the presence of all necessary binary data files
--noexplain            : do not process lines generated by auto_explain.
--no-fork              : do not fork any process, for debugging purpose.
--no-process-info      : disable changing process title to help identify
                         pgbadger process, some system do not support it.
--no-progressbar       : disable progressbar.
--noreport             : no reports will be created in incremental mode.
--no-week              : inform pgbadger to not build weekly reports in
                         incremental mode. Useful if it takes too much time.
--normalized-only      : only dump all normalized queries to out.txt
--pgbouncer-only       : only show PgBouncer-related menus in the header.
--pid-dir path         : set the path where the pid file must be stored.
                         Default /tmp
--pid-file file        : set the name of the pid file to manage concurrent
                         execution of pgBadger. Default: pgbadger.pid
--pie-limit num        : pie data lower than num% will show a sum instead.
--prettify-json        : use it if you want json output to be prettified.
--rebuild              : used to rebuild all html reports in incremental
                         output directories where there's binary data files.
--start-monday         : in incremental mode, calendar weeks start on
                         Sunday. Use this option to start on a Monday.
--tempdir DIR          : set directory where temporary files will be written
                         Default: File::Spec->tmpdir() || '/tmp'

pgBadger is able to parse a remote log file using a passwordless ssh connection. Use -r or –remote-host to set the host IP address or hostname. There are also some additional options to fully control the ssh connection.

--ssh-identity file      path to the identity file to use.
--ssh-option  options    list of -o options to use for the ssh connection.
                         Options always used:
                             -o ConnectTimeout=$ssh_timeout
                             -o PreferredAuthentications=hostbased,publickey
--ssh-port port          ssh port to use for the connection. Default: 22.
--ssh-program ssh        path to the ssh program to use. Default: ssh.
--ssh-timeout second     timeout to ssh connection failure. Default: 10 sec.
--ssh-user username      connection login name. Defaults to running user.

Log file to parse can also be specified using an URI, supported protocols are http[s] and [s]ftp. The curl command will be used to download the file, and the file will be parsed during download. The ssh protocol is also supported and will use the ssh command like with the remote host use. See examples bellow.

Return codes:

0: on success
1: die on error
2: if it has been interrupted using ctr+c for example
3: the pid file already exists or can not be created
4: no log file was given at command line

Examples:

pgbadger /var/log/postgresql.log
pgbadger /var/log/postgres.log.2.gz /var/log/postgres.log.1.gz /var/log/postgres.log
pgbadger /var/log/postgresql/postgresql-2012-05-*
pgbadger --exclude-query="^(COPY|COMMIT)" /var/log/postgresql.log
pgbadger -b "2012-06-25 10:56:11" -e "2012-06-25 10:59:11" /var/log/postgresql.log
cat /var/log/postgres.log | pgbadger -
# Log line prefix with stderr log output
pgbadger --prefix '%t [%p]: user=%u,db=%d,client=%h' /pglog/postgresql-2012-08-21*
pgbadger --prefix '%m %u@%d %p %r %a : ' /pglog/postgresql.log
# Log line prefix with syslog log output
pgbadger --prefix 'user=%u,db=%d,client=%h,appname=%a' /pglog/postgresql-2012-08-21*
# Use my 8 CPUs to parse my 10GB file faster, much faster
pgbadger -j 8 /pglog/postgresql-10.1-main.log

Use URI notation for remote log file:

pgbadger http://172.12.110.1//var/log/postgresql/postgresql-10.1-main.log
pgbadger ftp://username@172.12.110.14/postgresql-10.1-main.log
pgbadger ssh://username@172.12.110.14:2222//var/log/postgresql/postgresql-10.1-main.log*

You can use together a local PostgreSQL log and a remote pgbouncer log file to parse:

pgbadger /var/log/postgresql/postgresql-10.1-main.log ssh://username@172.12.110.14/pgbouncer.log

Reporting errors every week by cron job:

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

Generate report every week using incremental behavior:

0 4 * * 1 /usr/bin/pgbadger -q `find /var/log/ -mtime -7 -name "postgresql.log*"` -o /var/reports/pg_errors-`date +\%F`.html -l /var/reports/pgbadger_incremental_file.dat

This supposes that your log file and HTML report are also rotated every week.

Or better, use the auto-generated incremental reports:

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

will generate a report per day and per week.

In incremental mode, you can also specify the number of weeks to keep in the reports:

/usr/bin/pgbadger --retention 2 -I -q /var/log/postgresql/postgresql.log.1 -O /var/www/pg_reports/

If you have a pg_dump at 23:00 and 13:00 each day during half an hour, you can use pgBadger as follow to exclude these periods from the report:

pgbadger --exclude-time "2013-09-.* (23|13):.*" postgresql.log

This will help avoid having COPY statements, as generated by pg_dump, on top of the list of slowest queries. You can also use –exclude-appname “pg_dump” to solve this problem in a simpler way.

You can also parse journalctl output just as if it was a log file:

pgbadger --journalctl 'journalctl -u postgresql-9.5'

or worst, call it from a remote host:

pgbadger -r 192.168.1.159 --journalctl 'journalctl -u postgresql-9.5'

you don’t need to specify any log file at command line, but if you have other PostgreSQL log files to parse, you can add them as usual.

To rebuild all incremental html reports after, proceed as follow:

rm /path/to/reports/*.js
rm /path/to/reports/*.css
pgbadger -X -I -O /path/to/reports/ --rebuild

it will also update all resource files (JS and CSS). Use -E or –explode if the reports were built using this option.

pgBadger also supports Heroku PostgreSQL logs using logplex format:

heroku logs -p postgres | pgbadger -f logplex -o heroku.html -

this will stream Heroku PostgreSQL log to pgbadger through stdin.

pgBadger can auto detect RDS and cloudwatch PostgreSQL logs using rds format:

pgbadger -f rds -o rds_out.html rds.log

Each CloudSQL Postgresql log is a fairly normal PostgreSQL log, but encapsulated in JSON format. It is autodetected by pgBadger but in case you need to force the log format use `jsonlog`:

pgbadger -f jsonlog -o cloudsql_out.html cloudsql.log

This is the same as with the jsonlog extension, the json format is different but pgBadger can parse both formats.

pgBadger also supports logs produced by CloudNativePG Postgres operator for Kubernetes:

pgbadger -f jsonlog -o cnpg_out.html cnpg.log

To create a cumulative report over a month use command:

pgbadger --month-report 2919-05 /path/to/incremental/reports/

this will add a link to the month name into the calendar view in incremental reports to look at report for month 2019 May. Use -E or –explode if the reports were built using this option.

3 - PostgreSQL 日志配置

pgBadger 只能报告 PostgreSQL 实际写入日志的信息。应先确定可解析的日志前缀与清晰的语句记录策略，再按需要加入检查点、锁、临时文件和自动清理等运行事件。

最小查询日志配置

若报告需要查询文本与执行耗时，请启用按时长记录语句：

log_min_duration_statement = 0

0 会记录每一条执行完毕的语句。繁忙服务器应使用更高的毫秒阈值来控制日志量；在生产环境使用较低阈值前，应先评估开销与存储增长。

若只需要耗时与查询数量，不需要查询文本，可使用：

log_min_duration_statement = -1
log_duration = on

需要“最慢查询”和“查询总耗时”报告时，应优先使用 log_min_duration_statement。

日志前缀的必需字段

自定义 log_line_prefix 必须同时包含：

• 一个时间字段：%t、%m 或 %n；
• 一个进程或会话字段：%p 或 %c。

最小的 stderr 前缀如下：

log_line_prefix = '%t [%p]: '

更实用的前缀还会记录用户、数据库、应用与客户端：

log_line_prefix = '%t [%p]: user=%u,db=%d,app=%a,client=%h '

使用 syslog 作为目标时，时间与进程信息由 syslog 提供，对应前缀可写为：

log_line_prefix = 'user=%u,db=%d,app=%a,client=%h '

pgBadger 也支持另一种键顺序：

log_line_prefix = '%t [%p]: db=%d,user=%u,app=%a,client=%h '

如果前缀不属于 pgBadger 能自动识别的形式，请用 --prefix 传入与 postgresql.conf 完全一致的值，不要在命令行中自行简化或改写。

建议记录的运行事件

按报告需求启用相应事件：

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

这些设置可能产生大量日志。尤其是 log_temp_files = 0 与 log_autovacuum_min_duration = 0 会记录每一个符合条件的事件，应根据工作负载和日志保留预算调整阈值。

保持服务端消息为英文

上游解析器识别英文 PostgreSQL 服务端消息。可使用：

lc_messages = 'en_US.UTF-8'

或：

lc_messages = 'C'

上游解析器不支持 fr_FR.UTF-8 等其他消息语言。

避免互相冲突的语句设置

不要同时启用 log_min_duration_statement、log_duration 和 log_statement = 'all'。同一次执行可能被重复记录，既会放大 pgBadger 统计值，也会显著增加日志量。

重新加载 PostgreSQL 配置后，应先检查几条真实日志，再开始大规模分析。确认时间、进程/会话标识、用户、数据库、应用与客户端字段都符合选定格式。

4 - 并行处理

pgBadger 提供两种互补的多进程模式。选择时应关注输入日志的形态，而不只是 CPU 数量。

使用 -j 拆分单个大文件

$ pgbadger -j 8 /var/log/postgresql/postgresql.log

上游算法把每个文件分成 N 个字节区间，为每个区间 fork 一个解析进程，把统计结果写入临时二进制文件，最后合并生成报告。

对于每个日志文件：
    把文件划分为 N 个分块
    确定每个分块的起止偏移量
    在对应偏移量启动 N 个解析进程
    每个进程写入一份临时二进制统计文件
等待所有工作进程结束
合并二进制文件并生成报告

日志记录和多行语句不会恰好与字节偏移对齐，因此每个文件约有最多 N 条查询可能在边界处被截断、遗漏，或更常见地被重复计数。该模式适合大文件的聚合分析，不适合要求每条记录计数完全精确的取证流程。

使用 -J 并行处理多个文件

$ pgbadger -J 8 /var/log/postgresql/postgresql-*.log

每个工作进程独占一个完整文件，因此不会出现分块边界误差。它在有数百个小文件，并且 CPU 与 I/O 能力充足时最有效。上游文档也允许 -J 处理相互独立的压缩文件；使用 -j 对单文件分块则要求输入未压缩且可随机定位。

上游基准测试

上游手册给出了以下 8 CPU 主机测试。它适合用来比较两种算法，不应当作现代硬件的耗时预测。

单个 9.5 GB 文件：

两百个 10 MB 文件，共 2 GB：

实用默认值是：少量大文件使用 -j，大量小文件使用 -J。在输入和平台允许时可以组合两种模式，但仍需实测；日志解析很可能先受到存储吞吐量限制，而不是 CPU 限制。

限制与临时文件

• -j 不能用于压缩或 CSV 输入，并且依赖进程 fork，因此不适用于 Windows。
• 上游远程输入路径不支持远程 CSV 解析。
• 并行分析会在指定临时目录中创建形如 tmp_pgbadgerXXXX.bin 的文件；默认使用系统临时目录。
• pgBadger 运行期间不要清理这些文件。可用 --tempdir 把它们放到容量充足的存储上。
• 从较小的工作进程数开始，观察 CPU、读取吞吐量、临时空间占用与总耗时后再调大。

5 - 增量报告

增量模式先以二进制形式保存解析统计，再生成每日 HTML 报告、每周累计报告，以及把它们组织起来的日历式索引。它适合反复处理轮转日志，同时避免重复统计相同记录。

生成每日与每周报告

在每日轮转完成后运行 pgBadger，并指定一个持久化输出目录：

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

-I 启用增量模式，-O 指定保存二进制状态、日历索引和生成报告的目录。pgBadger 会在该目录自行维护增量状态；只有明确希望把状态文件放到其他位置时，才需要 --last-parsed。

也可以把 HTML 放到单独目录，同时在原目录保留二进制状态：

$ pgbadger -I -O /var/lib/pgbadger/data -H /var/www/pg_reports postgresql.log.1

二进制文件是未来重建报告的源数据。如果报告必须能够重新生成，应备份这些文件，或保留原始日志。

保留策略

只保留指定周数：

$ pgbadger --incremental --retention 8 \
    --outdir /var/www/pg_reports \
    /var/log/postgresql/postgresql.log.1

更早的周与日目录会被自动删除。不要直接在唯一一份报告历史上首次试用该策略，应先在非生产副本上验证。

把公共资源单独写出

默认情况下，每份 HTML 报告都内嵌 JavaScript 与 CSS。增量目录包含大量报告时，-X / --extra-files 会把公共资源单独写出，减少重复数据：

$ pgbadger -X -I -O /var/www/pg_reports postgresql.log.1

移动报告时，必须把所有 HTML 与对应版本的资源目录一起移动。

重建已有报告

升级 pgBadger 或应用报告生成修复后，可以从保留的二进制数据重建 HTML：

$ rm /var/www/pg_reports/*.js
$ rm /var/www/pg_reports/*.css
$ pgbadger -X -I -O /var/www/pg_reports --rebuild

如果原报告按数据库拆分生成，请在重建时再次加入 -E / --explode。

请使用长选项 --rebuild。当前命令参考中的 -R 表示 --retention；把 -R 当作重建缩写会执行错误的选项。

添加月度报告

每日与每周报告会自动生成。月度汇总需要显式执行，因为很长的历史可能使计算开销很大：

$ pgbadger -X --month-report 2026-07 /var/www/pg_reports/

生成的月份会加入日历索引。再次运行命令会从现有二进制数据重建该月份。按数据库拆分的历史需要继续使用 -E：

$ pgbadger -E -X --month-report 2026-07 /var/www/pg_reports/

完整命令参考还提供 --day-report YYYY-MM-DD、--no-week、--noreport、--start-monday 和 --iso-week-number，可用于更特殊的调度策略。

可以直接打开随站点打包的增量报告示例 ，离线查看日历、周链接与每日报告的目录层级。

6 - 输出格式

pgBadger 会根据输出文件扩展名，或 -x / --extension 选项选择格式。同一次解析可多次使用 -o / --outfile，同时生成多种格式。

HTML 与文本

默认输出为 out.html：

$ pgbadger postgresql.log -o report.html

HTML 通常会内嵌独立浏览所需的脚本、样式、字体与报告数据。-X / --extra-files 会把增量报告的公共 JavaScript 与 CSS 移到外部文件；移动 HTML 目录时必须保留这些资源。

显式生成文本：

$ pgbadger -x text -o report.txt postgresql.log

对于支持的格式，可用 - 作为输出文件名，把内容写到标准输出。

二进制中间数据

二进制输出把“解析日志”和“展示报告”分开。可以从一份持续增长的每日日志中生成逐小时增量：

$ pgbadger --last-parsed .pgbadger_last_state \
    -o sunday/hour01.bin \
    /var/log/pgsql/postgresql-Sun.log

把一个或多个二进制文件合并为新报告：

$ pgbadger -o sunday.html sunday/*.bin

如果服务器每小时生成一个日志，可为每次轮转生成一份二进制文件，并按需重建累计 HTML：

$ pgbadger -o day1/hour01.bin postgresql-2026-08-15_01.log
$ pgbadger -o day1/hour02.bin postgresql-2026-08-15_02.log
$ pgbadger -o day1/hour03.bin postgresql-2026-08-15_03.log
$ pgbadger -o day1.html day1/*.bin

同一个目录中应只混用彼此兼容的 pgBadger 版本生成的二进制文件。升级长期保留的增量目录前，应先查看版本说明中的格式兼容性信息。

JSON

JSON 输出面向监控或报告流水线等程序化消费者：

$ pgbadger -o report.json postgresql.log

需要先安装 JSON::XS。如果可读性比文件大小和生成速度更重要，可加入 --prettify-json。

原始数据与查询导出

命令参考还提供以下专用导出模式：

• --dump-raw-csv 解析日志并输出逐行 CSV，不再生成报告；
• --csv-separator 修改原始 CSV 分隔符；
• --dump-all-queries 在替换绑定参数后输出所有查询；
• --normalized-only 输出归一化查询；
• --query-numbering 为查询类文本输出编号。

这些输出可能包含应用 SQL、标识符、用户、客户端地址或字面量。共享前应先检查内容；如果分析不需要保留字面量，请使用 --anonymize。

7 - 报告示例

示例内容由 pgBadger 11.8 于 2022 年 5 月生成。原始示例已与本站一起保存，因此即使无法访问上游服务器，也能继续使用报告导航、图表、样式与脚本。

完整报告

完整报告是一份自包含 HTML 文档。可通过顶部导航查看全局统计、查询、会话、连接、临时文件、检查点、自动清理、锁，以及 PgBouncer 专用图表。

其中数据只是演示样本，不是当前基准测试。数值、PostgreSQL 版本与内嵌 pgBadger 界面都反映报告生成时的状态。

增量报告层级

增量示例保留了完整链接结构：

report/
├── index.html
├── 2012/
│   ├── week-49/index.html
│   ├── week-50/index.html
│   └── 12/06 … 12/index.html
└── 11/
    ├── pgbadger.min.css
    ├── pgbadger.min.js
    └── 图表与界面资源

顶层索引链接到两份周报和七份日报。所有相对链接均已保留，因此只移动 index.html 会破坏示例；应始终保持完整目录树。

安全与隐私

真实报告可能暴露 SQL 文本、绑定值、数据库名与用户名、应用名、客户端地址、错误细节和工作负载规律。发布报告前应：

• 不需要字面量时使用 --anonymize；
• 在生成报告前应用 include/exclude 过滤条件；
• 检查最终 HTML 或导出数据，而不只是生成命令；
• 像保护运行日志一样保护报告的访问位置。

8 - 版本历史

官网把版本新闻直接堆放在首页，内容停留在 12.4，并且误把 11.1–11.3 用互相冲突的日期重复渲染了一次。本站以固定上游 ChangeLog 为规范记录，只去除这些重复展示，同时补入后续 13.x 版本。每个系列均保留完整条目，并按从新到旧排序。

可下载归档与附件请访问 GitHub Releases 。本节日期描述的是上游源码历史，不是本站文档快照的下载时间。

8.1 - pgBadger 13.x 版本记录

本页按从新到旧的顺序保留 pgBadger 13.x 的完整上游变更记录。为确保版本、参数、提交者致谢和兼容性描述不被转述改变，正文保留英文原文。

v13.2 · 2025-12-29

This is a maintenance release of pgBadger that fixes issues and applied patches reported by users since last release.

• Fix normalization that was not handling properly balanced single-quoted strings along with escaped quotes inside. Thanks to Bertrand Bourgier for the report.
• Fix placeholder requirements in the doc.
• Fix case where no error sample log entries was reported. Thanks to john doe for the report.
• Fix possible precedence problem between ! and %s. Thanks to Luca Santarelli and Philipp Trulson for the report.
• Update pgFormatter code to v5.9
• Add github CI action for testing on commit push.
• Fix parsing of %r placeholder in log_line_prefix. Thanks to nike7o0 for the report.
• Fix uninitialized value warning. Thanks to Ales Zeleny for the report.
• Enhance docs of ssh-options for postgres log parsing with examples. Thanks to Ulrich Konrad for the patch.
• Add command –ssh-sudo to run commands over ssh as sudo. Thanks to Andrew Jackson for the patch.
• Fix possible precedence problem between ! and string eq. Thanks to Adrien Nayrat for the report.
• Fix parsing of pgbouncer stats. Thanks to mrgtt for the report.

v13.1 · 2025-03-16

This is a maintenance release of pgBadger that fixes issues reported by users since last release and adds some new features:

• Add new report about vacuum throughput with a graph about vacuum per table that consume the more CPU. The table output reports I/O timing read and write per table as well as the CPU time elapsed on the table. Thanks to Ales Zeleny for the feature request. This patch also adds frozen pages and tuples to the Vacuums per Table report.
• Add –no-fork option for debugging purpose to not fork processes at all. Thanks to Ales Zeleny for the feature request.
• Add millisecond to the raw csv output. Thanks to Henrietta Dombrovskaya for the feature request.
• Add log filename to sample reports when multiple file are processed. Thanks to Adrien Nayrat for the feature request.

Here is the complete list of changes and acknowledgments:

• Fix bind parameters parsing. Thanks to Thomas Kotzian for the patch
• Apply query filter on multi-lines queries. Thanks to Benjamin Jacobs for the patch
• Update test result for log filename storage changes
• Fix ERROR vs LOG message level in json output. Thanks to Philippe Viegas for the report.
• Remove import of tmpdir not exported method from File::Temp. Thanks to kmoradha for the report.

v13.0 · 2024-12-08

This is a major release of pgBadger that fixes issues reported by users since last release and adds some new features:

• Add two new option to be able to redefined inbound of query and session histogram. –histogram-query VAL : use custom inbound for query times histogram. Default inbound in milliseconds: 0,1,5,10,25,50,100,500,1000,10000 –histogram-session VAL : use custom inbound for session times histogram. Default inbound in milliseconds: 0,500,1000,30000,60000,600000,1800000,3600000,28800000 Thanks to JosefMachytkaNetApp for the feature request.
• Add support of auto_explain plan for csv and json log formats. Thanks to zxwsbg and to Alexander Rumyantsev for the report.
• Add three LOG message that was not reported as events: unexpected EOF, incomplete startup packet and detected deadlock while waiting for. Thanks to dottle for the report.

Backward compatibility issues:

• Change the way LOG level events reported in the Events reports are stored. Some of them was still reported and counted as errors instead as LOG level entries. The fix is to stored and report them as EVENTLOG to differentiate them from queries. This change introduce a backward compatibility break when pgbadger is used in incremental mode. You will just have the double behavior during the week of the upgrade. Thanks to Matti Linnanvuori for the report.

Bug fixes:

• Fix non reported queries generating the most cancellation due to statement_timeout.
• Update regression tests
• Fix formatting of explain plan when extracted from csv log format.
• Fix jsonlog missing autovacuum data reports: Average Autovacuum Duration, Tuples removed per table and vacuums by hour in autovacuum activity report. Thanks to Ales Zeleny for the patch.
• Fix orphan line not associated to the time consuming bind queries. Thanks to Henrietta Dombrovskaya for the report. Fix use of uninitialized value in pattern match. Thanks to Junior Dias for the patch.
• Apply option –csv-separator to raw export to CSV. Default separator is semicolon (;). Thanks to Henrietta Dombrovskaya for the feature request.
• Raw csv output: do not add double quote to parameters and application name if they are empty.
• Add double quotes when queries have a semi colon in raw csv output. Thanks to Henrietta Dombrovskaya for the report.

8.2 - pgBadger 12.x 版本记录

本页按从新到旧的顺序保留 pgBadger 12.x 的完整上游变更记录。为确保版本、参数、提交者致谢和兼容性描述不被转述改变，正文保留英文原文。

v12.4 · 2023-12-25

This is a maintenance release of pgBadger that fixes issues reported by users since last release.

• Fix pgbouncer report with version 1.21. Thanks to Ales Zeleny for the patch.
• Prevent parallelism perl file to be higher than the number of files. Thanks to maliangzhu for the report.
• Fix regression test broken since v12.3. Thanks to ieshin for the report.
• Fix cases where LOG entries where counted as ERROR log level entries. Thanks to Matti Linnanvuori for the report.

v12.3 · 2023-11-27

This is a maintenance release of pgBadger that fixes issues reported by users since last release. It also adds some new features:

• Add option –include-pid to only report events related to a session pid (%p). Can be used multiple time. Thanks to Henrietta Dombrovskaya for the feature request.
• Add option –include-session to only report events related to the session id (%c). Can be used multiple time. Thanks to Henrietta Dombrovskaya for the feature request.
• Add new option –dump-raw-csv to only parse the log and dump the information into CSV format. No further processing is done, no report is generated. Thanks to Henrietta Dombrovskaya for the feature request.

Here is the complete list of changes and acknowledgments:

• Update pgFormatter to version 5.5
• Fix end date of parsing with jsonlog format. Thanks to jw1u1 for the report.
• Fix typo in “Sessions per application”. Thanks to fairyfar for the patch.
• Fix “INSERT/UPDATE/DELETE Traffic” chart bug. Thanks to fairyfar for the patch.
• Fix parsing of orphan lines with bind queries. Thanks to youxq for the report.
• Fix Analyze per table report with new PG versions. Thanks to Jean-Christophe Arnu for the patch.
• Fix syslog entry parser when the syslog timestamp contains milliseconds. Thanks to Pavel Rabel for the report.

v12.2 · 2023-08-20

This is a maintenance release of pgBadger that fixes issues reported by users since last release. It also adds two new features:

• Add support for max, avg, min autovacuum duration. Thanks to Francisco Reinolds for the patch.
• Add support for pgbouncer’s average waiting time. Thanks to Francisco Reinolds for the patch.

Here is the complete list of changes and acknowledgments:

• Fix broken HTML output when application name contains <…>. Thanks to Fabio Geiss for the report.
• Fix incorrect association of orphan lines when a filter on database was applied. Thanks to jcasanov for the report.
• Fix logplex prefix parsing.
• Fix logplex orphan lines detection.
• Fix autovacuum’s system usage: CPU: ... line parsing. Thanks to Francisco Reinolds for the patch.
• Avoid prepending output directory if output is stdout.
• Standardise Average Query Duration label. Thanks to Francisco Reinolds for the patch
• Update documentation for new pgbadger options. Thanks to Francisco Reinolds for the patch.
• Fix case where parsing was not aborted when no file handle can be opened. Thanks to vp for the report.
• Fix help by adding %p/%t mandatory placeholder log information. Thanks to Christophe Courtois for the patch.
• Fix –retention parameter. Thanks to Bertrand Bourgier for the patch.
• Fix cleanup output directory removed by commit 0e5c7d5 when HTML output dir is set. Thanks to Bertrand Bourgier for the report.
• Fix output extension when destination directory contain a character that need to be escaped in regexp. Thanks to Bertrand Bourgier for the patch.
• Replace calls to POSIX::strftime("%s", ….) by a call to localtime for Windows port. Thanks to Bertrand Bourgier for the patch.
• Fix html output dir cleanup. Thanks to Bertrand Bourgier for the patch.
• Use https for explain URL by default. Thanks to Philipp Trulson for the patch.

v12.1 · 2023-03-20

This is a maintenance release of pgBadger that fixes issues reported by users since past six months.

Here is the complete list of changes and acknowledgments:

• Fix parsing of multiline parameters. Thanks to Bekir Niyaz for the report.
• Fix failure to normalize query with ::tsrange. Thanks to Philippe Griboval for the report.
• Add logical decoding consistent point and start for slot log entries to the events report.
• Handle other ns + timezone format in timestamp. Thanks to Ronan Dunklau for the report.
• Fix detection of %m when notation with T is used. Thanks to Ronan Dunklau for the report.
• Add parsing of CloudNativePG generated logs. Thanks to codrut panea for the patch.
• Fix unused option –outdir in report generation. Thanks to Frederic Guiet for the report.
• Update README with last documentation changes. Thanks to Manisankar for the report.
• Fix a typo in pgbadger examples. Thanks to Shinichi Hashiba for the patch.

v12.0 · 2022-09-13

This major release of pgBadger fixes some issues reported by users since past five months. As usual there is also new features and improvements:

• Remove support to Tsung output.
• Improve pgbadger performances when there are hundred of bind parameters to replace.
• Remove option -n | –nohighlight which is no more used since upgrade to pgFormatter 4.
• Use POST method to send auto_explain plan to explain.depesz.com to avoid GET length parameter limit.
• Apply –exclude-query and –include-query to bind/parse traces.
• Add link to pgBadger report examples to documentation.

Here is the complete list of changes and acknowledgments:

• Fix monthly reports that was failing on “log file … must exists”. Thanks to Jaume Sabater for the report.
• Fix pgbouncer start parsing debug message when input is stdin. Thanks to aleszeleny for the report.
• Remove support to Tsung output.
• Drastically improve pgbadger performances for bind parameters replacement that could make pgbadger run infinitely when there was hundred of parameters. Thanks to Monty Mobile for the report.
• Fix documentation about pgBadger return codes and also some wrong return code at some places. Thanks to Jaume Sabater for the report.
• Fix several typo. Thanks to David Gilman for the patch.
• Remove option -n | –nohighlight which is no more used since upgrade to pgFormatter 4. Thanks to Elena Indrupskaya for the report.
• Lot of pgbadger documentation fixes. Thanks to Elena Indrupskay from Postgres Pro for the patch.
• Allow half hour in –log-timezone and –timezone, value can be an integer, ex: 2 or a float, ex: 2.5. Thanks to Mujjamil-K for the feature request.
• Allow use of regexp for –exclude-app and –exclude-client. Thanks to rdnkrkmz for the feature request.
• Allow use of –explain-url with previous commit and restore the limitation to explain text format.
• Use POST method to send auto_explain plan to explain.depesz.com to avoid GET length parameter limit. Thanks to hvisage for the report.
• Apply –exclude-query and –include-query to bind/parse traces. Thanks to Alec Lazarescu for the report.
• Fix parsing of autovacuum stats from RDS logs. Thanks to David Gilman for the report.
• Fix passing of log format when parsing remote log. Thanks to spookypeanut the report.
• Add link to pgBadger report examples to documentation.
• Fix Session per user reports. Thanks to vitalca for the report.
• Fix jsonlog parsing from PG15 ouput
• Fix text-based error/events reporting. Thanks to Michael Banck for the patch
• Fix regexp typo in normalize_error(). Thanks to Michael Banck for the patch.

8.3 - pgBadger 11.x 版本记录

本页按从新到旧的顺序保留 pgBadger 11.x 的完整上游变更记录。为确保版本、参数、提交者致谢和兼容性描述不被转述改变，正文保留英文原文。

v11.8 · 2022-04-08

This release of pgBadger fix some issues reported by users since past three months and especially two fixes on new log entries detection in incremental mode.

• Fix detection of new log entries with timestamp when millisecond (%m) or epoch (%n) was used in log_line_prefix.
• Fix detection of new log entries in local file when multiprocess was not used.

Here is the complete list of changes and acknowledgments:

• Full review and simplification of the log file change detection.
• Reports messages “could not (receive|send) data (from|to) client” in the Events reports. Thanks to Adrien Nayrat for the report.
• Fix parsing issue when the name of a prepared query contain the ‘:’ character. Thanks to aleszeleny for the report.
• Fix detection of new log entries with timestamp when millisecond (%m) or epoch (%n). Thanks to aleszeleny for the report.
• Fix detection of new log entries in local file when multiprocess was not used. Thanks to aleszeleny for the report.
• Fix detection of new log entries in remote files through ssh. Thanks to Luca Ferrari for the report
• Fix garbage in username of “Connections per user” report. Thanks to caseyandgina for the report.
• Fix ssh command when using URI, the ssh options was missing. Thanks to Luca Ferrari for the report.
• Handle queryid %Q placeholder. Thanks to Adrien Nayrat for the patch.
• Fix typo in error sentence. Thanks to Luca Ferrari for the patch
• Report message: “server process was terminated by signal” in the Events report. Thanks to Avi Vallarapu for the report.
• doc: fix filename for incremental every week command. Thanks to Theophile Helleboid for the patch.
• t/04_advanced.t: Fix syslog test. Thanks to Christoph Berg for the patch.

v11.7 · 2022-01-23

This release of pgBadger fix some issues reported by users since past five months as well as some improvements:

• Add new option –no-progressbar option to not display it but keep the other outputs.
• Add new option –day-report that can be used to rebuild an HTML report over the specified day. Like option –month-report but only for a day. It requires the incremental output directories and the presence of all necessary binary data files. The value is date in format: YYYY-MM-DD
• Improve parsing of Heroku logplex and cloudsql json logs.

Here is the complete list of changes and acknowledgments:

• Update contribution guidelines and Makefile.PL to improve consistency, clarity, and dependencies. Thanks to diffuse for the patch.
• Fix use of last parse file (–last-parsed) with binary mode. Thanks to wibrt for the report.
• Add regression test for –last-parsed use and fix regression test on report for temporary files only.
• Fix title for session per host graph. Thanks to Norbert Bede for the report.
• Fix week number when computing weeks reports when –iso-week-number and –incremental options was enabled. Thanks to hansgv for the report.
• Add –no-progressbar option to not display it and keep the other outputs. Thanks to seidlmic for the feature request.
• Prevent too much unknown format line prints in debug mode for multi-line jsonlog.
• Fix parsing of single line cloudsql json log. Thanks to Thomas Leclaire for the report.
• Fix temporary files summary with log_temp_files only.
• Print debug message with -v even if -q or –quiet is used.
• Fix autodetection of jsonlog file.
• Fix parsing of cloudsql log file. Thanks to Luc Lamarle for the report.
• Fixes pid extraction in parse_json_input. Thanks to Francois Scala for the patch.
• Add new option –day-report with value as date in format: YYYY-MM-DD that can be used to rebuild an HTML report over the specified day. Thanks to Thomas Leclaire for the feature request.
• Fix query counter in progress bar. Thanks to Guillaume Lelarge for the report.
• Fix incomplete queries stored for top bind and prepare reports.
• Fix normalization of object identifier, in some case the numbers was replaced by a ?.
• Fix unformatted normalized queries when there is a comment at beginning.
• Fix multi-line in stderr format when –dbname is used. Thanks to Guillaume Lelarge for the report.
• Fix not generated reports in incremental mode when –dbname is used. Thanks to Dudley Perkins for the report.
• Do not die anymore if a binary file is not compatible, switch to next file. Thanks to Thomas Leclaire for the suggestion.
• Fix Heroku logplex format change in pgbadger parser. Thanks to François Pietka for the report.

v11.6 · 2021-09-04

This release of pgBadger fix some issues reported by users since past seven months as well as some improvements:

• Add detection of Query Id in log_line_prefix new in PG14. Thanks to Florent Jardin for the report.
• Add advanced regression tests with db exclusion and the explode feature. Thanks to MigOps Inc for the patch.
• Apply multiprocess to report generation when –explode is used. Thanks to MigOps Inc for the patch and Thomas Leclaire for the feature request.
• Add –iso-week-number in incremental mode, calendar’s weeks start on a Monday and respect the ISO 8601 week number, range 01 to 53, where week 1 is the first week that has at least 4 days in the new year. Thanks to Alex Muntada for the feature request.
• Add command line option –keep-comments to not remove comments from normalized queries. It can be useful if you want to distinguish between same normalized queries. Thanks to Stefan Corneliu Petrea for the feature request.
• Skip INFO lines introduced in PostgreSQL log file by third parties software. Thanks to David Piscitelli for the report.
• Add compatibility with PostgresPro log file including rows number and size in bytes following the statement duration. Thanks to panatamann for the report.
• Parse times with T’s to allow using the timestamps from journalctl. Thanks to Graham Christensen for the patch.
• Improve Windows port. Thanks to Bertrand Bourgier for the patches.

Important note:

• Expect that –iso-week-number will be the default in next major release and that –start-monday option will be removed as the week will always start a Monday. The possibility to have week reports start a Sunday will be removed to simplify the code.

Here is the complete list of changes and acknowledgments:

• Fix duplicate of warning message: “database … must be vacuumed within … transactions”. Thank to Christophe Courtois for the report.
• Fix use of uninitialized variable. Thanks to phiresky for the report.
• Improve query id detection, it can be negative, as well as read it from csvlog.
• Fix case where last file in incremental mode is always parsed even if it was already done. Thanks to Thomas Leclaire for the report.
• Update syslog format regex to handle where session line indicator only contains one int vs two ints separated by dash. Thanks to Timothy Alexander for the patch.
• Fix –exclude-db option to create anyway the related report with json log. Thanks to MigOps Inc for the patch and Thomas Leclaire for the report.
• Add regression test about Storable buggy version.
• Fix use of uninitialized value in substitution iterator in incremental mode during the week report generation. Thanks to Thomas Leclaire, Michael Vitale, Sumeet Shukla and Stefan Corneliu Petrea for the report.
• Add ‘g’ option to replace all bind parameters. Thanks to Nicolas Lutic and Sebastien Lardiere for the patch.
• Documentation improvements. Thanks to Stefan Petrea for the patch.
• Fixes change log time zone calculation. Thanks to Stefan Petrea for the patch.
• Fix log filter by begin/end time.
• Fix wrong association of orphan lines for multi-line queries with a filter on database. Thanks to Abhishek Mehta for the report.
• Fix reports in incremental mode when –dbname parameter is partially ignored with “explode” option (-E). Thanks to lrevest for the report.
• Update javascript resources.
• Fix display of menu before switching to hamburger mode when screen is reduced. Thanks to Guillaume Lelarge for the report.
• Fix bind parameters values over multiple lines in the log that were not well supported.
• Apply same fix for previous patch than in pgFormatter.
• Fix an other use of uninitialized value in substitution iterator from pgFormatter code. Thanks to Christophe Courtois for the report.
• Fix query normalization. Thanks to Jeffrey Beale for the patch.
• Be sure that all statements end with a semicolon when –dump-all-queries is used. Thanks to Christian for the report.
• Fix typo and init of EOL type with multiple log files.
• Add auto detection of EOL type to fix LAST_PARSED offset when OEL is on 2 bytes (Windows case). Thanks to Bertrand Bourgier for the patch.
• Fix get_day_of_week() port on Windows where strftime %u is not supported. Thanks to Bertrand Bourgier for the patch.
• Fix Windows port that call pl2bat.bat perl utility to create a corrupted pgbadger.bat du to the way DATA was read in pgbadger. Thanks to Bertrand Bourgier for the patch.
• Fix begin/end time filter and add regression test for timestamp filters. Thanks to Alexis Lahouze and plmayekar for the report.
• Fix use of uninitialized value in pattern match introduced by pgFormatter update. Thanks to arlt for the report.

v11.5 · 2021-02-18

This release of pgBadger fix some issues reported by users since past three months as well as some improvements:

• Add report about sessions idle time, computed using: “total sessions time - total queries time / number of sessions This require that log_connection and log disconnection have been enabled and that log_min_duration_statement = 0 (all queries logged) to have a reliable value. This can help to know how much idle time is lost, and if a pooler transaction mode would be useful. This report is available in the “Sessions” tab of “Global Stats” and in the “Sessions” tab of “General Activity” reports (per hour).
• Add anonymization of numeric values, replaced by 4 random digits.
• Update SQL beautifier based on pgFormatter 5.0.

Here is the complete list of changes and acknowledgments:

• Fix parsing of cloudsql multi-line statement. Thanks to Jon Young for the report.
• Add regression test for anonymization.
• Fix anonymization broken by maxlength truncate. Thanks to artl for the report.
• Add anonymization of parameter in time consuming prepare and bind reports. Thanks to arlt for the report.
• Add support to microseconds in logplex log line prefix. Thanks to Ross Gardiner for the report.
• Add report about sessions idle time. Thanks to Guillaume Lelarge for the feature request.
• Complete patch to support multi-line in jsonlog format.

v11.4 · 2020-11-24

This release of pgBadger fix some issues reported by users since past four months. Improve support for PostgreSQL 13 log information and adds some new features:

• Add full autovacuum information in “Vacuums per table” report for buffer usage (hits, missed, dirtied), skipped due to pins, skipped frozen and WAL usage (records, full page images, bytes). In report “Tuples removed per table” additional autovacuum information are tuples remaining, tuples not yet removable and pages remaining. These information are only available on the “Table” tab.
• Add new repartition report about checkpoint starting causes.
• Add detection of application name from connection authorized traces.

Here is the complete list of changes and acknowledgments:

• Fix typo in an error message. Thanks to Vidar Tyldum for the patch.
• Fix Windows port with error: “can not load incompatible binary data”. Thanks to Eric Brawner for the report.
• Fix typo on option –html-outdir in pgbadger usage and documentation. Thanks to Vidar Tyldum for the patch.
• Fix autodetection of jsonlog/cloudsql format. Thanks to Jon Young for the report.
• Fix CSV log parsing with PG v13. Thanks to Kanwei Li for the report and Kaarel Moppel for the patch.
• Fix sort of queries generating the most temporary files report. Thanks to Sebastien Lardiere for the report.
• Add pgbadger version trace in debug mode.

v11.3 · 2020-07-26

This release of pgBadger fix several issues reported by users since past four months. It also adds some new features and new command line options:

• Add autodetection of UTC timestamp to avoid applying timezone for graphs.
• Add support to GCP CloudSQL json log format.
• Add new option –dump-all-queries to use pgBadger to dump all queries to a text file, no report is generated just the full list of statements found in the PostgreSQL log. Bind parameters are inserted into the queries at their respective position.
• Add new option -Q | –query-numbering used to add numbering of queries to the output when using options –dump-all-queries or –normalized-only.
• Add new command line option –tempdir to set the directory where temporary files will be written. Can be useful on system that do not allow writing to /tmp.
• Add command line option –ssh-port used to set the ssh port if not default to 22. The URI notation also adds support to ssh port specification by using the form: ssh://192.168.1.100:2222//var/log/postgresql-11.log

Here is the complete list of changes and acknowledgments:

• Fix incremental reports for jsonlog/cloudsql log format. Thanks to Ryan DeShone for the report
• Add autodetection of UTC timestamp to avoid applying autodetected timezone for graphs. With UTC time the javascript will apply the local timezone. Thanks to Brett Stauner for the report.
• Fix incremental parsing of journalctl logs doesn’t work from the second run. Thanks to Paweł Koziol for the patch.
• Fix path to resources file when -X and -E are used. Thanks to Ryan DeShone for the report.
• Fix General Activity report about read/write queries. Thanks to alexandre-sk5 for the report.
• Add debug message when parallel mode is not use.
• Fix elsif logic in file size detection and extra space introduced in the journalctl command when the –since option is added. Thanks to Pawel Koziol for the patch.
• Fix “not a valid file descriptor” error. Thanks to Pawel Koziol for the report.
• Fix incremental mode with RDS files. Thanks to Ildefonso Camargo, nodje and John Walsh for the report.
• Add new option -Q | –query-numbering used to add numbering of queries to the output when using options –dump-all-queries or –normalized-only. This can be useful to extract multiline queries in the output file from an external script. Thanks to Shantanu Oak for the feature request.
• Fix parsing of cloudsql json logs when log_min_duration_statement is enabled. Thanks to alexandre-sk5 for the report.
• Fix wrong hash key for users in RDS log. Thanks to vosmax for the report.
• Fix error related to modification of non-creatable array value. Thanks to John Walsh and Mark Fletcher for the report.
• Add support to GCP CloudSQL json log format, log format (-f) is jsonlog. Thanks to Thomas Poindessous for the feature request.
• Add new option –dump-all-queries to use pgBadger to dump all queries to a text file, no report is generated just the full list of statements found in the PostgreSQL log. Bind parameters are inserted into the queries at their respective position. There is not sort on unique queries, all queries are logged. Thanks to Shantanu Oak for the feature request.
• Add documentation for –dump-all-queries option.
• Fix vacuum report for new PG version. Thanks to Alexey Timanovsky for the report.
• Add new command line option –no-process-info to disable change of process title to help identify pgbadger process, some system do not allow it. Thanks to Akshay2378 for the report.
• Add new command line option –tempdir to set the directory where temporary files will be written. Default: File::Spec->tmpdir() || ‘/tmp’ Can be useful on system that do not allow writing to /tmp. Thanks to Akshay2378 for the report.
• Fix unsupported compressed filenames with spaces and/or brackets. Thanks to Alexey Timanovsky for the report.
• Add command line option –ssh-port used to set the ssh port if not default to 22. The URI notation also adds support to ssh port specification by using the form: ssh://192.168.1.100:2222//var/log/postgresql-11.log Thanks to Augusto Murri for the feature request.

v11.2 · 2020-03-11

This release of pgBadger fix several issues reported by users since past six months. It also adds some new features:

• Add support and autodetection of AWS redshift log format.

• Add support to pgbouncer 1.11 new log format.

• Handle zstd and lz4 compression format

• Allow to fully separate statistics build and HTML report build in incremental mode without having to read a log file. For example it is possible to run pgbadger each hours as follow:

  pgbadger -I -O "/out-dir/data" --noreport /var/log/postgresql*.log
  

  It just creates the data binary files in “/out-dir/data” then for example you can make reports each night for the next day in a separate directory /out-dir/reports:

  pgbadger -I -l "/out-dir/data/LAST_PARSED" -H "/out-dir/reports" /out-dir/data/2020/02/19/*.bin
  

  This require to set the path to the last parsed information, the path where HTML reports will be written and the binary data file of the day.

There is also new command line options:

• Add new command line option –explain-url used to override the url of the graphical explain tool. Default URL is:

  http://explain.depesz.com/?is_public=0&is_anon=0&plan=
  

  If you want to use a local install of PgExplain or an other tool. pgBadger will add the plan in text format escaped at the end of the URL.

• Add new option –no-week to instruct pgbadger to not build weekly reports in incremental mode. Useful if it takes too much time and resources.

• Add new command line option –command to be able to set a command that pgBadger will execute to retrieve log entries on stdin. pgBadger will open a pipe to the command and parse log entries generated by the command. For example:

  pgbadger -f stderr –command ‘cat /var/log/postgresql.log’

  which is the same as executing pgbadger with the log file directly as argument. The interest of this option is obvious if you have to modify the log file on the fly or that log entries are extracted from a program or generated from a database. For example:

  pgbadger -f csv –command ‘psql dbname -c “COPY jrn_log TO STDOUT (FORMAT CSV)”’

• Add new command line option –noexplain to prevent pgBadger to parse and report explain plan written to log by auto_explain extension. This is useful if you have a PostgreSQL version < 9.0 where pgBadger generate broken reports when there is explain plan in log.

Backward compatibility:

• By default pgBadger will truncate queries up to 100000 characters. This arbitrary value and can be adjusted using option –maxlength. Previous behavior was to not truncate queries but this could lead in excessive resources usage. Limiting default size is safer and the size limit might allow no truncate in most cases. However queries will not be beautified if they exceed 25000 characters.

Here is the complete list of changes and acknowledgments:

• Fix non working –exclude-client option. Thanks to John Walsh for the report.
• Add regression test for RDS log parsing and –exclude-client.
• Fix progress bar for pgbouncer log file. The “queries” label is changed in “stats” for pgbouncer log files.
• Add command line option –explain-url used to override the url of the graphical explain tool. Thanks to Christophe Courtois for the feature request.
• Add support to pgbouncer 1.11 new log format. Thanks to Dan Aksenov for the report.
• Handle zstd and lz4 compression format. Thanks to Adrien Nayrat for the patch.
• Add support and autodetection of AWS redshift log format. Thanks to Bhuvanesh for the reature request.
• Update documentation about redshift log format.
• Add new option –no-week to instruct pgbadger to not build weekly reports in incremental mode. Thanks to cleverKermit17 for the feature request.
• Fix a pattern match on file path that breaks pgBadger on Windows.
• Fix #554 about cyrillic and other encoded statement parameters that was not reported properly in the HTML report even with custom charset. The regression was introduced with a fix to the well known Perl error message “Wide character in print”. The patch have been reverted and a new command line option: –wide-char is available to recover this behavior. Add this option to your pgbadger command if you have message “Wide character in print”. Add a regression test with Cyrillic and french encoding. Thanks to 4815162342lost and yethee for the report.
• Update documentation to inform that lc_messages = ’en_US.UTF-8’ is valid too. Thanks to nodje for the report.
• Update documentation about –maxlength which default truncate size is 100000 and no more default to no truncate. Thanks to nodje for the report.
• Fix retention calculation at year overlap. Thanks to Fabio Pereira for the patch.
• Fix parsing of rds log file format. Thanks to Kadaffy Talavera for the report.
• Prevent generating empty index file in incremental mode when there is no new log entries. Thanks to Kadaffy Talavera for the report.
• Fix non up to date documentation. Thanks to Eric Hanson for the patch.
• Fixes the command line parameter from -no-explain to -noexplain. Thanks to Indrek Toom for the patch.
• Fall back to default file size when totalsize can not be found. Thanks to Adrien Nayrat for the patch.
• Fix some dates in examples. Thanks to Greg Clough for the patch.
• Use compressed file extension regexp in remaining test and extract .bin extension in a separate condition.
• Handle zstd and lz4 compression format. Thanks to Adrien Nayrat for the patch.
• Fix remaining call of SIGUSR2 on Windows. Thanks to inrap for the report.
• Fix progress bar with log file of indetermined size.
• Add new command line option –command to be able to set a command that pgBadger will execute to retrieve log entries on stdin. Thanks to Justin Pryzby for the feature request.
• Add new command line option –noexplain to prevent pgBadger to parse and report explain plan written to log by auto_explain extension. This is useful if you have a PostgreSQL version < 9.0 where pgBadger generate broken reports when there is explain plan in log. Thanks to Massimo Sala for the feature request.
• Fix RDS log parsing when the prefix is set at command line. Thanks to Bing Zhao for the report.
• Fix incremental mode with rds log format. Thanks to Bing Zhao for the report.
• Fix possible rds log parsing. Thanks to James van Lommel and Simon Dobner for the report.
• Fix statement classification and add regression test. Thanks to alexanderlaw for the report.
• Fix anonymization of single characters in IN clause. Thanks to Massimo Sala for the report.
• Fix RDS log parsing for rows without client/user/db information. Thanks to Konrad for the report.

v11.1 · 2019-09-16

This release of pgBadger fix several issues reported by users since three months. It also adds some new features and reports:

• Add report of top N queries that consume the most time in the prepare or parse stage.
• Add report of top N queries that consume the most time in the bind stage.
• Add report of timing for prepare/bind/execute queries parts. Reported in a new “Duration” tab in Global Stats report. Example: Total query duration: 6m16s Prepare/parse total duration: 45s564ms Bind total duration: 4m46s Execute total duration: 44s71m This also fix previous report of “Total query duration” that was only reporting execute total duration.
• Add support to RDS and CloudWatch log format, they are detected automatically. You can use -f rds if pgbadger is not able to auto-detect the log format.
• Add new configuration option –month-report to be able to build monthly incremental reports.
• Restore support to Windows operating system.

There’s also some bugs fixes and features enhancements.

• Add auto-generated Markdown documentation in README.md using tool pod2markdown. If the command is not present the file will just not be generated. Thanks to Derek Yang for the patch.
• Translate action WITH into CTE, regression introduced in last release.
• Fix support of Windows Operating System
• Add support to RDS and CloudWatch log format, use -f rds if pgbadger is not able to auto-detect this log format. Thanks to peruuparkar for the feature request.
• Fix option -f | –format that was not applied on all files get from the parameter list where log format auto-detection was failing, the format was taken from the fist file parsed. Thanks to Levente Birta for the report.
• Update source documentation file to replace reference to pgBadger v7.x with v11. Thanks to Will Buckner for the patch.
• Limit height display size of top queries to avoid taking the whole page with huge queries. Thanks to ilias ilisepe1 for the patch.
• Fix overflow of queries and detail in Slowest individual queries.
• Fix SSH URIs for files, directories and wildcards. Thanks to tbussmann for the patch.
• Fix URI samples in documentation. Thanks to tbussmann for the patch.
• Hide message of use of default out file when –rebuild is used.
• Add extra newline to usage() output to not bread POD documentation at make time.
• Reapply –exclude-client option description in documentation. Thanks to Christoph Berg for the report.

v11.0 · 2019-06-25

This release of pgBadger adds some major new features and fixes some issues reported by users since the last four months. New features:

• Regroup cursor related query (DECLARE,CLOSE,FETCH,MOVE) into new query type CURSOR.

• Add top bind queries that generate the more temporary files. Require log_connection and log_disconnection be activated.

• Add –exclude-client command line option to be able to exclude log entries for the specified client ip. Can be used multiple time.

• Allow to use time only in –begin and –end filters.

• Add -H, –html-dir option to be able to set a different path where HTML report must be written in incremental mode. Binary files stay on directory defined with -O, –outdir option.

• Add -E | –explode option to explode the main report into one report per database. Global information not related to a database are added to the postgres database report.

• Add per database report to incremental mode. In this mode there will be a sub directory per database with dedicated incremental reports.

• Add support to Heroku’s PostgreSQL logplex format. Log can be parsed using:

  heroku logs -p postgres | pgbadger -f logplex -o heroku.html -

• When a query is > 10Kb we first limit size of all constant string parameters to 30 characters and then the query is truncated to 10Kb. This prevent pgbadger to waste time/hang with very long queries when inserting bytea for example. The 10Kb limit can be controlled with the –maxlength command line parameter. The query is normalized or truncated to maxlength value only after this first attempt to limit size.

This new release breaks backward compatibility with old binary or JSON files. This also mean that incremental mode will not be able to read old binary file. If you want to update pgBadger and keep you old reports take care to upgrade at start of a new week otherwise weekly report will be broken. pgBadger will print a warning and just skip the old binary file.

There’s also some bugs fixes and features enhancements.

• Add a warning about version and skip loading incompatible binary file.
• Update code formatter to pgFormatter 4.0.
• Fix pgbadger hang on Windows OS. Thanks to JMLessard for the report.
• Update tools/pgbadger_tools script to be compatible with new binary file format in pgBadger v11.
• Add top bind queries that generate the more temporary files. This collect is possible only if log_connection and log_disconnection are activated in postgresql.conf. Thanks to Ildefonso Camargo for the feature request.
• Fix auto detection of timezone. Thanks to massimosala for the fix.
• Remove some remaining graph when –nograph is used
• Force use of .txt extension when –normalized-only is used.
• Fix report of auto vacuum/analyze in logplex format. Thanks to Konrad zichul for the report.
• Fix use of progress bar on Windows operating system. Thanks to JMLessard for the report.
• Use a `$prefix_vars{’t_time’} to store the log time. Thanks to Luca Ferrari for the patch.
• Update usage and documentation to remove perl command from pgbadger invocations. Thanks to Luca Ferrari for the patch.
• Use begin and end with times without date. Thanks to Luca Ferrari for the patch.
• Added some very minor spelling and grammar fixes to the readme file. Thanks to ofni yratilim for the patch.
• Fix remote paths using SSH. Thanks to Luca Ferrari for the patch.
• Update regression test to works with new structure introduced with the per database report feature.
• Fix fractional seconds in all begin and end parameters. Thanks to Luca Ferrari for the patch.
• Fix documentation URL. Thanks to Kara Mansel for the report.
• Fix parsing of auto_explain. Add more information about -U option that can be used multiple time. Thanks to Douglas J Hunley for the report.
• Lot of HTML / CSS report improvements. Thanks to Pierre Giraud for the patches.
• Update resource file.
• Add regression test for logplex format.
• Add support to Heroku’s PostgreSQL logplex format. You should be able to parse these logs as follow: heroku logs -p postgres | pgbadger -f logplex -o heroku.html - or if you have already saved the output to a file: pgbadger heroku.log The logplex format is auto-dectected like any other supported format. pgBadger understand the following default log_line_prefix: database = %d connection_source = %r sql_error_code = %e or simply: sql_error_code = %e Let me know if there’s any other default log_line_prefix. The prefix can always be set using the -p | –prefix pgbadger option: pgbadger –p ‘base = %d source = %r sql_state = %e’ heroku.log for example. Thanks to Anthony Sosso for the feature request.
• Fix pgbadger help on URI use.
• Fix broken wildcard use in ssh URI introduced in previous patch. Thanks to Tobias Bussmann for the report.
• Allow URI with space in path to log file. Thanks to Tobias Bussmann for the report.
• Fix URI samples in documentation. Thanks to Tobias Bussmann for the patch.
• Fix t/02_basics.t to don’t fail if syslog test takes more than 10s. Thanks to Christoph Berg for the patch.

8.4 - pgBadger 10.x 版本记录

本页按从新到旧的顺序保留 pgBadger 10.x 的完整上游变更记录。为确保版本、参数、提交者致谢和兼容性描述不被转述改变，正文保留英文原文。

v10.3 · 2019-02-14

This release of pgBadger is a maintenance release that fixes some log format autodetection issues another pgBouncer log parsing issue reported by users. There is also a new feature:

The -o | --outfile option can now be used multiple time to dump
output in several format in a single command. For example:
    pgbadger -o out.html -o out.json /log/pgsql-11.log
will create two reports in html and json format saved in the
two corresponding files.

There’s also some bugs fixes and features enhancements.

• Fix statistics reports when there a filter on database, user, client or application is requested. Some queries was not reported.
• Fix autodetection of pg>=10 defauilt log line prefix.
• Fix autodetection of log file with “non standard” log line prefix. If –prefix specify %t, %m, %n and %p or %c, set format to stderr. Thanks to Alex Danvy for the report.
• Remove extra space at end of line.
• Add minimal test to syslog parser.
• Fix a call to autodetect_format().
• Truncate statement when maxlength is used. Thanks to Thibaud Madelaine for the patch.
• Add test for multiple output format.
• The -o | –outfile option can now be used multiple time to dump output in several format in a single command. For example: pgbadger -o out.txt -o out.html -o - -x json /log/pgsql-11.log Here pgbadger will create two reports in text and html format saved in the two corresponding file. It will also output a json report on standard output. Thanks to Nikolay for the feature request.
• Move detection of output format and setting of out filename into a dedicated function set_output_extension().
• Fix another pgBouncer log parsing issue. Thanks to Douglas J. Hunley for the report.

v10.2 · 2018-12-27

This release of pgBadger is a maintenance release that fixes issues reported by users during last three months. There is also some new features:

• Add support to pgbouncer 1.8 Stats log format.
• Auto adjust javascript graph timezone.

There is a new command line option:

• Add –exclude-db option to compute report about everything except the specified database.

• Add support to http or ftp remote PostgreSQL log file download. The log file is parsed during the download using curl command and never saved to disk. With ssh remote log parsing you can use uri as command line argument to specify the PostgreSQL log file.

      ssh://localhost/postgresql-10-main.log
      http://localhost/postgresql-10-main.log.gz
      ftp://localhost/postgresql-10-main.log
  

  with http and ftp protocol you need to specify the log file format at end of the uri:

      http://localhost/postgresql-10-main.log:stderr
  

  You can specify multiple uri for log files to be parsed. This is useful when you have pgbouncer log file on a remote host and PostgreSQL logs in the local host.

  With ssh protocol you can use wild card too like with remote mode, ex: ssh://localhost/postgresql-10-main.log*

  Old syntax to parse remote log file using -r option is still working but is obsolete and might be removed in future versions.

There’s also some bugs fixes and features enhancements.

• Adjust end of progress bar with files with estimate size (bz2 compressed files and remote compressed files.
• Update year in copyright.
• Add information about URI notation to parse remote log files.
• Force progress to reach 100% at end of parsing of compressed remote file.
• Extract information about PL/pgSQL function call in queries of temporary file reports. The information is append to the details display block.
• Fix progress bar with csv files.
• Fix reading binary file as input file instead of log file.
• Encode html output of queries into UTF8 to avoid message “Wide character in print”. Thanks to Colin ’t Hart for the report.
• Add Checkpoints distance key/value for distance peak.
• Fix pgbouncer parsing and request throughput reports. Thanks to Levente Birta for the report.
• Fix use of csvlog instead of csv for input format.
• Add support to pgbouncer 1.8 Stats log format. Thanks to Levente Birta for the report.
• Add warning about parallel processing disabled with csvlog. Thanks to cstdenis for the report.
• Add information in usage output about single process forcing with csvlog format in -j and -J options. Thanks to cstdenis for the report.
• Fix unknown line format error for multi line log while incremental analysis over ssh. Thanks to Wooyoung Cho for the report.
• Add -k (–insecure) option to curl command to be able to download logs from server using a self signed certificate.
• Auto adjust javascript graph timezone. Thanks to Massimino Sala for the feature request.
• Add support to HTTP logfile download by pgBadger, for example: /usr/bin/pgbadger http://www.mydom.com/postgresql-10.log
• Will parse the file during download using curl command.
• Fix documentation. Thanks to 0xflotus for the patch.
• Reapply fix on missing replacement of bind parameters after some extra code cleaning. Thanks to Bernhard J. M. Grun for the report.
• Add –exclude-db option to compute report about everything except the specified database. The option can be used multiple time.

v10.1 · 2018-09-12

This release of pgBadger is a maintenance release that fixes reports in incremental mode and multiprocess with -j option. Log parsing from standard input was also broken. If you are using v10.0 please upgrade now.

• Add test on pgbouncer log parser.
• Some little performances improvment.
• Fix not a valid file descriptor at pgbadger line 12314.
• Fix unwanted newline in progressbar at startup.
• Remove circleci files from the project.
• Remove dependency of bats and jq for the test suite, they are replaced with Test::Simple and JSON::XS.
• Add more tests especially for incremental mode and input from stdin that was broken in release 10.0.
• Sync pgbadger, pod, and README, and fix some syntax errors. Thanks to Christoph Berg for the patch.
• Add documentation on how to install Perl module JSON::XS from apt and yum repositories.
• Fix URI for CSS in incremental mode. Thanks to Floris van Nee for the report.
• Fix fatal error when looking for log from STDIN. Thanks to Jacek Szpot for the report.
• Fixes SED use for OSX builds. Thanks to Steve Newson for the patch.
• Fix illegal division by zero in incrental mode. Thanks to aleszeleny for the report.
• Replace SQL::Beautify with v3.1 of pgFormatter::Beautify.

v10.0 · 2018-09-09

This release of pgBadger is a major release that adds some new features and fix all issues reported by users since last release.

• Add support of pgbouncer syslog log file format.
• Add support to all auto_explain format (text, xml, json and yaml).
• Add support to %q placeholder in log_line_prefix.
• Add jsonlog format of Michael Paquier extension, with -f jsonlog pgbadger will be able to parse the log.
• Replace the SQL formatter/beautify with v3.0 of pgFormatter.

There is some new command line option:

• Add –prettify-json command line option to prettify JSON output.
• Add –log-timezone +/-XX command line option to set the number of hours from GMT of the timezone that must be used to adjust date/time read from log file before beeing parsed. Note that you might still need to adjust the graph timezone using -Z when the client has not the same timezone.
• Add –include-time option to add the ability to choose times that you want to see, instead of excluding all the times you do not want to see (–exclude-time).

The pgBadger project and copyrights has been transfered from Dalibo to the author and official maintainer of the project. Please update your links:

• Web site: http://pgbadger.darold.net/
• Source code: https://github.com/darold/pgbadger

I want to thanks the great guys at Dalibo for all their investments into pgBadger during these years and especially Damien Clochard and Jean-paul argudo for their help to promote pgBadger.

• Fix checkpoint distance and estimate not reported in incremental mode. Thanks to aleszeleny for the report.
• Fix title of pgbouncer simultaneous session report. Thansks to Jehan Guillaume De Rorthais for the report.
• Add support of pgbouncer syslog log file format. Thanks to djester for the feature request.
• Fix error when a remote log is empty. Thanks to Parasit Hendersson for the report.
• Fix test with binary format. Binary file must be generated as it is dependent of the plateform. Thanks to Michal Nowak for the report.
• Fix case where an empty explain plan is generated.
• Fix parsing of autodetected default format with a prefix in command line.
• Remove dependency of git command in Makefile.PL.
• Update documentation about options changes and remove of the [%l-1] part of the mandatory prefix.
• Fix parsing of vacuum / analyze system usage for PostgreSQL 10. Thanks to Achilleas Mantzios for the patch.
• Fix Temporary File Activity table.
• Remove dependency to git during install.
• Add –log-timezone +/-XX command line option to set the number of hours from GMT of the timezone that must be used to adjust date/time read from log file before beeing parsed. Using this option make more difficult log search with a date/time because the time will not be the same in the log. Note that you might still need to adjust the graph timezone using -Z when the client has not the same timezone. Thanks to xdexter for the feature request and Julien Tachoire for the patch.
• Add support to auto_explain json output format. Thanks to dmius for the report.
• Fix auto_explain parser and queries that was counted twice. Thanks to zam6ak for the report.
• Fix checkpoint regex to match PostgreSQL 10 log messages. Thanks to Edmund Horner for the patch.
• Update description of -f | –format option by adding information about jsonlog format.
• Fix query normalisation to not duplicate with bind queries. Normalisation of values are now tranformed into a single ? and no more 0 for numbers, two single quote for string. Thanks to vadv for the report.
• Fix log level count. Thanks to Jean-Christophe Arnu for the report
• Make pgbadger more compliant with B::Lint bare sub name.
• Made perlcritic happy.
• Add –prettify-json command line option to prettify JSON output. Default output is all in single line.
• Fix Events distribution report.
• Fix bug with –prefix when log_line_prefix contain multiple %%. Thanks to svb007 for the report.
• Add –log-timezone +/-XX command line option to set the number of hours from GMT of the timezone that must be used to adjust date/time read from log file before beeing parsed. Using this option make more difficult log search with a date/time because the time will not be the same in the log. Note that you might still need to adjust the graph timezone using -Z when the client has not the same timezone. Thanks to xdexter for the feature request.
• Remove INDEXES from the keyword list and add BUFFERS to this list.
• Fix normalization of query using cursors.
• Remove Dockerfile and documentation about docker run. pgBadger comes as a single Perl script without any dependence and it can be used on any plateform. It is a non sens to use docker to run pgbadger, if you don’t want to install anything, just copy the file pgbadger where you want and execute it.
• Fix broken grid when no temp files activity. Thanks to Pierre Giraud for the patch
• Add doc warning about log_in_duration_statement vs log_duration + log_statement. Thanks to Julien Tachoire for the patch.
• Apply timezone offset to bar charts. Thanks to Julien Tachoire for the patch.
• Delete current temp file info if we meet an error for the same PID Thanks to Julien Tachoire for the patch.
• Consistently use app= in examples, and support appname= Some of the usage examples used appname= in the prefix, but the code didn’t recognize that token. Use app= in all examples, and add appname= to the prefix parser. Thanks to Christoph Berg for the patch
• Fix wrong long name for option -J that should be –Jobs intead of –job_per_file. Thanks to Chad Trabant for the report and Etienne Bersac for the patch.
• Ignore blib files. Thanks to Etienne Bersac for the patch.
• Add consistency tests. Thanks to damien clochard for the patch.
• doc update : stderr is not a default for -f. Thanks to Christophe Courtois for the patch.
• Always update pod and README. Thanks to Etienne Bersac for the patch.
• Add some regression tests. Thanks to Etienne Bersac for the patch.
• Add editorconfig configuration. Thanks to Etienne Bersac for the patch.
• Drop vi temp files from gitignore. Thanks to Etienne Bersac for the patch.
• Add –include-time option to add the ability to choose times that you want to see, instead of excluding all the times you do not want to see. This is handy when wanting to view only one or two days from a week’s worth of logs (simplifies down from multiple –exlucde-time options to one –include-time). Thanks to Wesley Bowman for the patch.
• Check pod syntax. Thanks to Etienne Bersac for the patch.
• Add HACKING to document tests. Thanks to Etienne Bersac for the patch.
• Drop obsolete –bar-graph option. Thanks to Etienne Bersac for the patch.
• Drop misleading .perltidyrc. This file date from 2012 and pgbadger code is far from compliant. perltidy unified diff is 10k lines. Let’s drop this. Thanks to Etienne Bersac for the patch.
• Fix use of uninitialized value in SQL formatting. Thanks to John Krugger for the report and Jean-paul Argudo for the report.

8.5 - pgBadger 9.x 版本记录

本页按从新到旧的顺序保留 pgBadger 9.x 的完整上游变更记录。为确保版本、参数、提交者致谢和兼容性描述不被转述改变，正文保留英文原文。

v9.2 · 2017-07-27

This release of pgBadger is a maintenance release that adds some new features.

• Add report of checkpoint distance and estimate.
• Add support of AWS Redshift keywords to SQL code beautifier.
• Add autodetection of log format in remote mode to allow remote parsing of pgbouncer log file together with PostgreSQL log file.

There’s also some bugs fixes and features enhancements.

• Fix reports with histogram that was not showing data upper than the last range.
• Fix parsing of journalctl without the the log line number pattern ([%l-n]). Thanks to Christian Schmitt for the report.
• Add report of checkpoint distance and estimate. Thanks to jjsantam for the feature request.
• Append more information on what is done by script to update CSS and javascript files, tools/updt_embedded_rsc.pl.
• Do not warn when all log files are empty and exit with code 0.
• Fix build_log_line_prefix_regex() that does not include %n as a lookup in %regex_map. Thanks to ghosthound for the patch.
• Change error level of “FATAL: cannot use CSV” to WARNING. Thanks to kong1man for the report.
• Fix use of uninitialized value warning. Thanks to Payal for the report.
• Add permission denied to error normalization
• Update pgbadger to latest commit 5bdc018 of pgFormatter.
• Add support for AWS Redshift keywords. Thanks to cavanaug for the feature request.
• Fix missing query in temporary file report when the query was canceled. Thanks to Fabrizio de Royes Mello for the report.
• Normalize query with binded parameters, replaced with a ?.
• Sanity check to avoid end time before start time. Thanks to Christophe Courtois for the patch.
• Fix a lot of mystyped words and do some grammatical fixes. Use ‘pgBadger’ where it refers to the program and not the binary file. Also, use “official” expressions such as PgBouncer, GitHub, and CSS. POD file was synced with README. Thanks to Euler Taveira for the patch.
• Menu is broken when –disable-type top_cancelled_info test and closing list must be inside disable_type test. While in it, ident disable_lock test. Thanks to Euler Taveira for the patch.
• Fix use of uninitialized value. Thanks to johnkrugger for the report.
• Remove test to read log file during log format auto-detection when the file is hosted remotly. Thanks to clomdd for the report.
• Add autodetection of log format in remote mode to allow remote parsing of pgbouncer log file together with PostgreSQL log file.
• Fix number of sessions wrongly increased after log line validation Thanks to Achilleas Mantzios for the report.
• Minor reformatting of the pgBadger Description.
• Fix repeated info in documentation. Thanks to cscatolini for the patch.

v9.1 · 2017-01-24

This release of pgBadger is a maintenance release that adds some new features.

• Add report of error class distribution when SQLState is available in the log_line_prefix (see %e placeholder).
• Update SQL Beautifier to pgFormatter v1.6 code.
• Improve error message normalization.
• Add –normalized-only option to generate a text file containing all normalized queries found in a log with count.
• Allow %c (session id) to replace %p (pid) as unique session id.
• Add waiting for lock messages to event reports.
• Add –start-monday option to start calendar weeks in Monday instead of default to Sunday.

There’s also some bugs fixes and features enhancements.

• Add report of error class distribution when SQLState is available in the log line prefix. Thanks to jacks33 for the feature request.
• Fix incremental global index on resize. Thanks to clomdd for the report.
• Fix command tag log_line_prefix placeholder %i to allow space character.
• Fix –exclude-line options and removing of obsolete directory when retention is enabled and –noreport is used.
• Fix typo in “vacuum activity table”. Thanks to Nicolas Gollet for the patch.
• Fix autovacuum report. Thanks to Nicolas Gollet for the patch.
• Fix author of pgbadger’s logo - Damien Cazeils and English in comments. Thanks to Thibaut Madelaine for the patch.
• Add information about pgbouncer log format in the -f option. Thanks to clomdd for the report.
• Add –normalized-only information in documentation.
• Fix broken report of date-time introduced in previous patch.
• Fix duration/query association when log_duration=on and log_statement=all. Thanks to Eric Jensen for the report.
• Fix normalization of messages about advisory lock. Thanks to Thibaut Madelaine for the report.
• Fix report of auto_explain output. Thanks to fch77700 for the report.
• Fix unwanted log format auto detection with log entry from stdin. Thanks to Jesus Adolfo Parra for the report.
• Add left open parentheses to the “stop” chars of regex to look for db client in the prefix to handle the PostgreSQL client string format that includes source port. Thanks to Jon Nelson for the patch.
• Fix some spelling errors. Thanks to Jon Nelson for the patch.
• Allow %c (session id) to replace %p (pid) as unique session id. Thanks to Jerryliuk for the report.
• Allow pgbadger to parse default log_line_prefix that will be probably used in 10.0: ‘%m [%p] '
• Fix missing first line with interpreter call.
• Fix missing Avg values in CSV report. Thanks to Yosuke Tomita for the report.
• Fix error message in autodetect_format() method.
• Add –start-monday option to start calendar weeks in Monday instead of default to Sunday. Thanks to Joosep Mae for the feature request.
• Fix –histo-average option. Thanks to Yves Martin for the report.
• Remove plural form of –ssh-option in documentation. Thanks to mark-a-s for the report.
• Fix –exclude-time filter and rewrite code to skip unwanted line as well code to update the progress bar. Thanks to Michael Chesterton for the report.
• Fix support to %r placeholder in prefix instead of %h.

v9.0 · 2016-09-02

This major release of pgBadger is a port to bootstrap 3 and a version upgrade of all resources files (CSS and Javascript). There’s also some bugs fixes and features enhancements.

Backward compatibility with old incremental report might be preserved.

• Sources and licences of resources files are now on a dedicated subdirectory. A script to update their minified version embedded in pgbager script has been added. Thanks to Christoph Berg for the help and feature request.

• Try to detect user/database/host from connection strings if log_connection is enabled and log_line_prefix doesn’t include them.

  Extend the regex to autodetect database name, user name, client ip address and application name. The regex now are the following:

  db => qr/(?:db|database)=([^,]*)/;
  user => qr/(?:user|usr)=([^,]*)/;
  client => qr/(?:client|remote|ip|host)=([^,]*)/;
  appname => qr/(?:app|application)=([^,]*)/;
  

• Add backward compatibility with older version of pgbadger in incremental mode by creating a subdirectory for new CSS and Javascript files. This subdirectory is named with the major version number of pgbadger.

• Increase the size of the pgbadger logo that appears too small with the new font size.

• Normalize detailed information in all reports.

• Fix duplicate copy icon in locks report.

• Fix missing chart on histogram of session time. Thanks to Guillaume Lelarge for the report.

• Add LICENSE file noting the licenses used by the resource files. Thanks to Christoph Berg for the patch.

• Add patch to jqplot library to fix an infinite loop when trying to download some charts. Thanks to Julien Tachoires for the help to solve this issue.

• Script tools/updt_embedded_rsc.pl will apply the patch to resource file resources/jquery.jqplot.js and doesn’t complain if it has already been applied.

• Remove single last comma at end of pie chart dataset. Thanks to Julien Tachoires for the report.

• Change display of normalized error

• Remove unused or auto-generated files

• Update all resources files (js+css) and create a directory to include source of javascript libraries used in pgbadger. There is also a new script tools/updt_embedded_rsc.pl the can be used to generate the minified version of those files and embedded them into pgbadger. This script will also embedded the FontAwesome.otf open truetype font into the fontawesome.css file.

9 - 支持与贡献

pgBadger 是一个开放维护的项目。缺陷报告、功能建议、文档修复与代码补丁都通过上游 GitHub 仓库处理。

缺陷与功能需求

1. 升级到最新正式版本，确认问题仍然存在。
2. 搜索开放问题 与已关闭问题 ，查看是否已有答案。
3. 把问题缩减为仍能复现的最小安全日志样本与命令行。
4. 删除凭据、敏感 SQL、绑定值、主机名、地址与业务数据。
5. 创建新问题 ，写明 pgBadger 版本、操作系统、输入格式、完整选项、实际结果与预期结果。

对于崩溃或解析错误，只应附上复现边界所需的最少脱敏日志。完整生产日志或生成报告通常不适合放在公开问题中。

贡献补丁

项目提供 .editorconfig 以统一空格与缩进。若改动影响用户可见行为，应同时保持命令帮助、POD 与生成的 Markdown 文档一致。

上游文档生成流程为：

$ perl Makefile.PL
$ make README

doc/pgBadger.pod 是长篇文档的主要来源；pgbadger --help 提供 synopsis，README 文件则是生成视图。提交拉取请求前应运行相关测试。

• 源码仓库
• 拉取请求
• 贡献指南
• 开发说明

商业支持

pgBadger 的许可证不承诺维护或支持。如需 PostgreSQL 日志、性能分析或报告自动化方面的付费协助，请查看 PostgreSQL 专业服务目录 。

10 - 许可证与致谢

pgBadger 是以 PostgreSQL License 发布的自由开源软件。只要保留版权与许可证声明，就可以免费使用、复制、修改与分发。

PostgreSQL License 原文

Copyright (c) 2012-2026, Gilles Darold

Permission to use, copy, modify, and distribute this software and its documentation for any purpose, without fee, and without a written agreement is hereby granted, provided that the above copyright notice and this paragraph and the following two paragraphs appear in all copies.

IN NO EVENT SHALL Darold BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF Darold HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Darold SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN “AS IS” BASIS, AND Darold HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

以上保留英文许可证原文，以免翻译改变法律含义。

作者与设计致谢

• pgBadger 是 Gilles Darold 的原创作品。
• pgBadger 标志由 Damien Cazeils 原创设计。
• pgBadger v4.x 的视觉设计来自 “Art is code” 公司。
• 项目网站由 Gilles Darold 制作。
• 其他贡献者在上游 ChangeLog 的对应版本中逐项致谢。

内嵌代码与报告资源

pgBadger 内嵌了修改版 SQL::Beautify Perl 模块，版权 © 2009 Jonas Kramer，以 Artistic License 2.0 发布。

生成报告使用的资源保留各自许可证：

本地源码快照保留了完整上游 resources/LICENSE。随站点打包的报告示例是历史生成物，也保留原有的内嵌声明与资源版本。

文档快照说明

本站把上游文档重新组织成 Hugo 页面，增加了导航与中文阅读辅助；命令帮助和 ChangeLog 等需要逐字核对的内容仍保留原文。pgBadger 源码文档继续遵循 PostgreSQL License，项目名称、作者信息与上游链接均予以保留。