这是本节的多页打印视图。 .

pgBadger 13.2 中文文档

快速分析 PostgreSQL 与 PgBouncer 日志，生成完整且可独立浏览的报告

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 报告自成一体，支持交互与缩放，只需浏览器即可查看。

为什么使用 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 日志时，还会生成吞吐量、平均查询耗时、并发会话、连接与会话分布、备用连接池使用情况，以及高频错误/事件报告。

文档阅读顺序

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

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

上游链接

1 - 下载与安装

官方发布、系统软件包、运行要求与源码安装方法

选择分发渠道

渠道	适用场景	地址
官方发布	源码归档与版本说明	GitHub Releases
RPM 软件包	基于 RPM 的 Linux 发行版	PostgreSQL Yum 仓库
Debian/Ubuntu 软件包	基于 APT 的 Linux 发行版	PostgreSQL Apt 仓库
开发源码	尚未正式发布的最新代码	darold/pgbadger

安装示例使用 pgBadger 13.2。下载前请查看发布页面，选择所需版本。

运行要求

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

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

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

功能	依赖
解析 PostgreSQL CSV 日志	`Text::CSV_XS`
生成 JSON 输出	`JSON::XS`
读取 `.gz`、`.bz2`、`.lz4`、`.xz`、`.zip` 或 `.zst` 输入	对应的 `zcat`、`bzcat`、`lz4cat`、`xz`、`unzip` 或 `zstdcat` 工具

在 Debian 或 Ubuntu 上安装 JSON 支持：

$ sudo apt-get install libjson-xs-perl

在基于 RPM 的系统上：

$ sudo yum install perl-JSON-XS

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

xz 工具必须支持 --robot，以便 pgBadger 读取归档元数据。压缩 lz4 日志时请使用 --content-size，使 pgBadger 能确定解压后的文件大小。

从官方归档安装

下载版本归档后，使用 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 命令语法、选项、远程输入、返回码与示例

用法与选项

用法：pgbadger [options] logfile […]

PostgreSQL 日志分析器，生成详细报告和图表。

参数：

logfile 可以是单个日志文件、文件列表，或返回文件列表的 shell 命令。
若要从标准输入传入日志内容，请使用 - 作为文件名。
注意：csvlog 不支持从标准输入读取。

选项：

-a | --average minutes : 查询与连接平均值图表的时间粒度，单位为分钟。默认 5 分钟。
-A | --histo-average min: 查询直方图的时间粒度，单位为分钟。默认 60 分钟。
-b | --begin datetime  : 待解析日志的起始日期/时间，可以是完整时间戳或仅时间。
-c | --dbclient host   : 只报告指定客户端主机的记录。
-C | --nocomment       : 从查询中删除 /* ... */ 一类的注释。
-d | --dbname database : 只报告指定数据库的记录。
-D | --dns-resolv      : 将客户端 IP 地址替换为 DNS 名称；可能显著降低解析速度。
-e | --end datetime    : 待解析日志的结束日期/时间，可以是完整时间戳或仅时间。
-E | --explode         : 按数据库拆分主报告，每个数据库生成一份报告。
                         与数据库无关的全局信息放入 postgres 数据库的报告。
-f | --format logtype  : 可选值：syslog、syslog2、stderr、jsonlog、csv、pgbouncer、
                         logplex、rds、redshift。无法自动识别格式时使用此选项。
-G | --nograph         : 禁用 HTML 输出中的图表；默认会生成图表。
-h | --help            : 显示帮助信息并退出。
-H | --html-outdir path: 增量模式下 HTML 报告的输出目录；二进制文件仍保存在
                         -O / --outdir 指定的目录。
-i | --ident name      : 用作 syslog 标识的程序名称。默认：postgres。
-I | --incremental     : 启用增量模式，按天在独立目录中生成报告。必须设置 --outdir。
-j | --jobs number     : 单个日志文件同时运行的解析进程数。
                         默认使用单进程；csvlog 格式也使用单进程。
-J | --Jobs number     : 并行解析的日志文件数。默认一次处理一个文件。
-l | --last-parsed file: 记录最后解析的日期/时间与行位置，以支持增量解析。
                         适合只查看上次运行后的错误，或为按周轮转的日志生成日报。
-L | --logfile-list file:包含待解析日志文件列表的文件。
-m | --maxlength size  : 查询的最大长度，超过此长度会截断。默认截断长度为 100000。
-M | --no-multiline    : 不收集多行语句，避免混入无关内容，尤其是错误导致的巨大报告。
-N | --appname name    : 只报告指定应用名称的记录。
-o | --outfile filename: 输出文件名。默认名称取决于格式：out.html、out.txt、out.bin
                         或 out.json。可多次指定，生成多种格式。
                         JSON 输出需要 Perl 模块 JSON::XS。
                         使用 - 作为文件名可输出到标准输出。
-O | --outdir path     : 输出文件的保存目录。
-p | --prefix string   : postgresql.conf 中自定义 log_line_prefix 的原始值。
                         只在未使用文档列出的标准前缀时需要指定，例如前缀额外包含
                         客户端 IP 或应用名称。必须包含时间占位符（%t、%m 或 %n）
                         和进程/会话占位符（%p 或 %c）。参见下文示例。
-P | --no-prettify     : 禁用 SQL 查询格式化。
-q | --quiet           : 不向标准输出打印任何内容，包括进度条。
-Q | --query-numbering : 使用 --dump-all-queries 或 --normalized-only 时为查询编号。
-r | --remote-host ip  : 指定远程主机，在该主机上执行 cat 读取日志并在本地解析。
-R | --retention N     : 增量模式的保留周数。默认 0，表示禁用清理。
                         超出保留期限的周目录和日目录会自动删除。
-s | --sample number   : 保存的查询样本数量。默认：3。
-S | --select-only     : 只报告 SELECT 查询。
-t | --top number      : 保存/显示的查询数量。默认：20。
-T | --title string    : 修改 HTML 报告的页面标题。
-u | --dbuser username : 只报告指定用户的记录。
-U | --exclude-user username : 从报告中排除指定用户的记录，可多次指定。
-v | --verbose         : 启用详细输出或调试模式，默认禁用。
-V | --version         : 显示 pgBadger 版本并退出。
-w | --watch-mode      : 只报告错误，类似 logwatch。
-W | --wide-char       : 将查询的 HTML 输出编码为 UTF8，避免 Perl 的
                         "Wide character in print" 提示。
-x | --extension       : 输出格式。可选值：text、html、bin、json。默认：html。
-X | --extra-files     : 增量模式下，将 CSS 和 JS 作为独立文件写入输出目录。
-z | --zcat exec_path  : 解压程序的完整路径；zcat、bzcat 或 unzip 不在 PATH 中时使用。
-Z | --timezone +/-XX  : 以相对 GMT 的小时偏移调整 JavaScript 图表的日期/时间。
                         可以是整数（例如 2）或小数（例如 2.5）。
--anonymize            : 隐藏查询中的所有字面量，用于隐藏机密数据。
--charset              : HTML 使用的字符集。默认：utf-8。
--command CMD          : 执行此命令，从其标准输出获取日志记录。
                         pgBadger 打开通向该命令的管道并解析它生成的日志。
--csv-separator        : CSV 字段分隔符。默认：,
--day-report YYYY-MM-DD: 为指定日期生成 HTML 报告；需要增量输出目录及全部必要的
                         二进制数据文件。
--disable-autovacuum   : 不生成 autovacuum 报告。
--disable-checkpoint   : 不生成 checkpoint/restartpoint 报告。
--disable-connection   : 不生成连接报告。
--disable-error        : 不生成错误报告。
--disable-hourly       : 不生成逐小时报告。
--disable-lock         : 不生成锁报告。
--disable-query        : 不生成查询报告，例如最慢、最频繁、按用户或按数据库统计的查询。
--disable-session      : 不生成会话报告。
--disable-temporary    : 不生成临时文件报告。
--disable-type         : 不生成按类型、数据库或用户统计的查询报告。
--dump-all-queries     : 导出日志中的全部查询，将绑定参数替换到各自的占位符位置。
--dump-raw-csv         : 解析日志并以 CSV 格式导出数据，不再进一步处理或生成报告。
--enable-checksum      : 在每份查询报告下添加 MD5 校验值。
--exclude-appname name : 从报告中排除指定应用的记录，例如 "pg_dump"。可多次指定。
--exclude-client name  : 排除指定客户端 IP 的日志记录，可多次指定。
--exclude-db name      : 从报告中排除指定数据库的记录，例如 "postgres"。可多次指定。
--exclude-file filename: 包含查询排除规则的文件，每行一个正则表达式。
--exclude-line regex   : 排除匹配此正则表达式的日志记录，可多次指定。
--exclude-query regex  : 排除匹配此正则表达式的查询，例如 "^(VACUUM|COMMIT)"。
                         可多次指定。
--exclude-time  regex  : 排除时间戳匹配此正则表达式的记录，例如 "2013-04-12 .*"。
                         可多次指定。
--explain-url URL      : 覆盖图形化执行计划工具的 URL。
                         默认：https://explain.depesz.com/
--histogram-query VAL  : 自定义查询耗时直方图的分组边界，默认值（毫秒）：
                         0,1,5,10,25,50,100,500,1000,10000
--histogram-session VAL: 自定义会话耗时直方图的分组边界，默认值（毫秒）：
                         0,500,1000,30000,60000,600000,1800000,3600000,28800000
--include-file filename: 包含查询纳入规则的文件，每行一个正则表达式。
--include-query regex  : 不匹配此正则表达式的查询会被排除，例如 "(tbl1|tbl2)"。
                         可多次指定。
--include-pid PID      : 只报告指定会话进程 ID（%p）的事件，可多次指定。
--include-session ID   : 只报告指定会话 ID（%c）的事件，可多次指定。
--include-time  regex  : 只纳入时间戳匹配此正则表达式的记录，例如 "2013-04-12 .*"。
                         可多次指定。
--iso-week-number      : 增量模式下，每周从周一开始，并采用 ISO 8601 周编号。
                         编号范围为 01 至 53，第 1 周是新年中至少含 4 天的第一周。
--keep-comments        : 保留归一化查询中的注释，便于区分归一化结果相同的查询。
--journalctl command   : 调用 journalctl 替代 PostgreSQL 日志文件，例如：
                         journalctl -u postgresql-9.5
--log-duration         : 强制关联 log_duration = on 和 log_statement = 'all'
                         各自生成的日志记录。
--log-timezone +/-XX   : 以相对 GMT 的小时偏移调整从日志读取的日期/时间，再进行解析。
                         使用此选项会增加按日期/时间查找原始日志的难度。
                         可以是整数（例如 2）或小数（例如 2.5）。
--month-report YYYY-MM : 为指定月份生成累计 HTML 报告；需要增量输出目录及全部必要的
                         二进制数据文件。
--noexplain            : 不处理 auto_explain 生成的日志行。
--no-fork              : 不创建任何子进程，用于调试。
--no-process-info      : 不修改进程标题以标识 pgbadger 进程；部分系统不支持此操作。
--no-progressbar       : 禁用进度条。
--noreport             : 增量模式下不创建报告。
--no-week              : 增量模式下不生成周报，适合周报耗时过长的情况。
--normalized-only      : 只把全部归一化查询导出到 out.txt。
--pgbouncer-only       : 页头只显示与 PgBouncer 相关的菜单。
--pid-dir path         : PID 文件的存放目录。默认：/tmp。
--pid-file file        : 用于管理 pgBadger 并发执行的 PID 文件名。默认：pgbadger.pid。
--pie-limit num        : 饼图中低于 num% 的数据合并显示。
--prettify-json        : 对 JSON 输出进行排版，便于阅读。
--rebuild              : 根据增量输出目录中保留的二进制数据，重建全部 HTML 报告。
--start-monday         : 增量日历默认每周从周日开始；使用此选项改为周一。
--tempdir DIR          : 临时文件的写入目录。默认：File::Spec->tmpdir() || '/tmp'

pgBadger 可以通过免密 SSH 连接解析远程日志文件。使用 -r 或 –remote-host 指定主机 IP 地址或主机名。另有若干附加选项，可对 SSH 连接进行完整控制。

--ssh-identity file      使用的身份密钥文件路径。
--ssh-option  options    SSH 连接所使用的 -o 选项列表。
                         始终使用以下选项：
                             -o ConnectTimeout=$ssh_timeout
                             -o PreferredAuthentications=hostbased,publickey
--ssh-port port          SSH 连接端口。默认：22。
--ssh-program ssh        SSH 程序的路径。默认：ssh。
--ssh-timeout second     SSH 连接超时，单位为秒。默认：10 秒。
--ssh-user username      连接用户名，默认使用运行 pgBadger 的用户。

--ssh-sudo 在远程列出文件和读取日志的命令前加上 sudo。远程 SSH 用户必须能够通过 sudo 执行这些命令，且不需要交互提示。

待解析的日志文件也可以用 URI 指定，支持 http[s] 与 [s]ftp 协议。文件由 curl 命令下载，并在下载过程中同步解析。ssh 协议同样受支持，与远程主机模式一样使用 ssh 命令。参见下文示例。

返回码：

0: 成功
1: 出错并终止
2: 执行被中断，例如按下 Ctrl+C
3: PID 文件已存在或无法创建
4: 命令行未指定日志文件

示例：

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 -
# stderr 输出使用的日志行前缀
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
# syslog 输出使用的日志行前缀
pgbadger --prefix 'user=%u,db=%d,client=%h,appname=%a' /pglog/postgresql-2012-08-21*
# 使用 8 个 CPU 加快解析 10GB 日志文件
pgbadger -j 8 /pglog/postgresql-10.1-main.log

对远程日志文件使用 URI 写法：

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*

可以同时解析本地 PostgreSQL 日志与远程 pgbouncer 日志文件：

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

通过 cron 任务每周报告错误：

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

利用增量机制每周生成报告：

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

这要求日志文件和 HTML 报告同样按周轮转。

更好的做法是使用自动生成的增量报告：

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

上述命令会按天和按周分别生成报告。

在增量模式下，还可以指定报告中保留的周数：

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

如果 pg_dump 每天 23:00 和 13:00 各运行半小时，可以按下面的方式把这两个时段从报告中排除：

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

上面的表达式会排除这两个完整小时；可以按备份的实际运行时段进一步限定分钟部分。

这样可以避免 pg_dump 生成的 COPY 语句占据最慢查询列表的顶部。也可以用更简单的 –exclude-appname “pg_dump” 解决该问题。

journalctl 的输出也可以像日志文件一样直接解析：

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

也可以从远程主机调用它：

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

此时命令行无需指定日志文件；若还有其他 PostgreSQL 日志需要解析，照常追加即可。

之后若要重建全部增量 HTML 报告，步骤如下：

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

该命令同时会更新全部资源文件（JS 与 CSS）。若报告当初使用该选项生成，此处也应加上 -E 或 –explode。

pgBadger 还支持 logplex 格式的 Heroku PostgreSQL 日志：

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

该命令通过标准输入把 Heroku PostgreSQL 日志流式传给 pgbadger。

pgBadger 可以按 rds 格式自动识别 RDS 与 CloudWatch PostgreSQL 日志：

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

每份 CloudSQL PostgreSQL 日志本质上是封装成 JSON 格式的普通 PostgreSQL 日志。 pgBadger 会自动识别；若需强制指定日志格式，使用 jsonlog：

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

这与 jsonlog 扩展的情形相同：JSON 格式有所不同，但 pgBadger 都能解析。

pgBadger 还支持 Kubernetes 上 CloudNativePG Postgres Operator 生成的日志：

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

使用以下命令创建月度累计报告：

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

该命令会在增量报告的日历视图中为月份名称添加链接，用于查看 2019 年 5 月的报告。若报告当初使用该选项生成，此处也应加上 -E 或 –explode。

3 - PostgreSQL 日志配置

为 pgBadger 配置查询日志、log_line_prefix、消息语言与运行统计

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 统计值，也会显著增加日志量。

目标	建议设置
查询文本与耗时	`log_min_duration_statement = 0` 或选定的阈值
仅统计耗时与次数	`log_min_duration_statement = -1`，`log_duration = on`
广泛记录全部语句	将 `log_statement` 视为独立的日志策略；用于 pgBadger 统计时不要把三项全部同时打开

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

4 - 并行处理

在单个日志分块并行与多个日志并行之间做出选择

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

选项	并行单位	最适合	主要限制
`-j N` / `--jobs N`	一个日志文件的多个分块	单个可定位的大日志	分块边界可能重复或漏掉少量查询
`-J N` / `--Jobs N`	完整日志文件	大量相互独立的日志	只有文件数量足以填满工作进程时才有明显收益

使用 `-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 文件：

选项	1 CPU	2 CPU	4 CPU	8 CPU
`-j`	1h41m18	50m25	25m39	15m58
`-J`	1h41m18	54m28	41m16	34m45

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

选项	1 CPU	2 CPU	4 CPU	8 CPU
`-j`	20m15	9m56	5m20	4m20
`-J`	20m15	9m49	5m00	2m40

实用默认值是：少量大文件使用 -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 - 输出格式

选择 HTML、文本、二进制、JSON 或原始 CSV 输出，并合并中间数据文件

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

格式	常用扩展名	最适合
HTML	`.html`	带图表的交互式人类可读报告
文本	`.txt`	终端查看与纯文本归档
二进制	`.bin`	可合并的中间统计数据与报告重建
JSON	`.json`	与其他软件集成；需要 `JSON::XS`
原始 CSV	自选输出文件	使用 `--dump-raw-csv` 导出逐行数据

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 分隔符；13.2 默认使用逗号（,）；
--dump-all-queries 在替换绑定参数后输出所有查询；
--normalized-only 输出归一化查询；
--query-numbering 为查询类文本输出编号。

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

7 - 报告示例

打开完整、仅错误与增量 pgBadger 报告

示例内容由 pgBadger 11.8 于 2022 年 5 月生成。报告导航、图表、样式与脚本均可离线使用。

示例	展示内容	本地副本
完整报告	PostgreSQL 活动与 PgBouncer 统计	打开完整报告
增量报告	日历索引、每周累计与每日页面	打开增量索引
错误与事件	仅包含错误和运行事件的报告	打开错误报告

完整报告

完整报告是一份自包含 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 - 版本历史

pgBadger 9.x 至 13.x 的版本历史

pgBadger 9.x–13.x 的版本历史，按主要版本系列分组，每个系列按从新到旧排序。

这些条目描述的是各版本发布时的行为。历史默认值、配置名称和升级指引可能与 13.2 不同；实际运行设置请以当前命令行参考和 PostgreSQL 日志配置指南为准。

系列	收录版本	首末发布日期	页面
13.x	13.0–13.2	2024-12-08 – 2025-12-29	阅读 13.x
12.x	12.0–12.4	2022-09-13 – 2023-12-25	阅读 12.x
11.x	11.0–11.8	2019-06-25 – 2022-04-08	阅读 11.x
10.x	10.0–10.3	2018-09-09 – 2019-02-14	阅读 10.x
9.x	9.0–9.2	2016-09-02 – 2017-07-27	阅读 9.x

发行归档与附件请访问 GitHub Releases 。

8.1 - pgBadger 13.x 版本记录

pgBadger 13.x 系列的完整上游版本记录

v13.2 · 2025-12-29

这是维护版本，修复了上一版本发布后用户报告的问题，并合入了相关补丁。

修复查询归一化无法正确处理配对单引号字符串及其中转义引号的问题。感谢 Bertrand Bourgier 报告。
修正文档中的占位符要求。
修复未显示错误日志样本的情况。感谢 john doe 报告。
修复 ! 与 %s 之间可能存在的优先级问题。感谢 Luca Santarelli 和 Philipp Trulson 报告。
将 pgFormatter 代码更新到 v5.9。
添加 GitHub CI 工作流，在推送提交时运行测试。
修复 log_line_prefix 中 %r 占位符的解析。感谢 nike7o0 报告。
修复未初始化值的警告。感谢 Ales Zeleny 报告。
完善解析 PostgreSQL 日志所用 SSH 选项的文档，并加入示例。感谢 Ulrich Konrad 提供补丁。
添加 --ssh-sudo 选项，以 sudo 身份执行 SSH 远程命令。感谢 Andrew Jackson 提供补丁。
修复 ! 与字符串 eq 比较之间可能存在的优先级问题。感谢 Adrien Nayrat 报告。
修复 PgBouncer 统计信息的解析。感谢 mrgtt 报告。

v13.1 · 2025-03-16

这是维护版本，修复了上一版本发布后用户报告的问题，并增加了以下功能：

添加 vacuum 吞吐量报告，以及按表显示 CPU 耗时最高的 vacuum 的图表。表格报告各表的读取与写入 I/O 耗时，以及 CPU 耗时。感谢 Ales Zeleny 提出需求。此补丁还在“按表统计 vacuum”报告中加入冻结页和冻结元组的信息。
添加用于调试的 --no-fork 选项，使程序完全不创建子进程。感谢 Ales Zeleny 提出需求。
在原始 CSV 输出中加入毫秒。感谢 Henrietta Dombrovskaya 提出需求。
处理多个文件时，在样本报告中加入日志文件名。感谢 Adrien Nayrat 提出需求。

完整变更与致谢如下：

修复绑定参数的解析。感谢 Thomas Kotzian 提供补丁。
对多行查询应用查询过滤条件。感谢 Benjamin Jacobs 提供补丁。
更新日志文件名存储方式改变后的测试结果。
修复 JSON 输出中的 ERROR 与 LOG 消息级别。感谢 Philippe Viegas 报告。
移除从 File::Temp 导入其未导出的 tmpdir 方法的代码。感谢 kmoradha 报告。

v13.0 · 2024-12-08

这是主要版本，修复了上一版本发布后用户报告的问题，并增加了以下功能：

添加两个选项，用于自定义查询和会话直方图的分组边界： --histogram-query VAL：查询耗时直方图的边界，默认值（毫秒）为 0,1,5,10,25,50,100,500,1000,10000。 --histogram-session VAL：会话耗时直方图的边界，默认值（毫秒）为 0,500,1000,30000,60000,600000,1800000,3600000,28800000。感谢 JosefMachytkaNetApp 提出需求。
支持 CSV 和 JSON 日志格式中的 auto_explain 执行计划。感谢 zxwsbg 和 Alexander Rumyantsev 报告。
将此前未作为事件报告的三类 LOG 消息加入事件报告：unexpected EOF、incomplete startup packet 和 detected deadlock while waiting for。感谢 dottle 报告。

向后兼容性问题：

改变“事件”报告中 LOG 级别事件的存储方式。此前其中一些事件仍作为错误报告和计数，而未作为 LOG 级别记录处理。现在将它们存储并报告为 EVENTLOG，以区别于查询。这项改动会破坏增量模式的向后兼容性；升级当周的报告会同时包含新旧两种处理方式。感谢 Matti Linnanvuori 报告。

缺陷修复：

修复未报告因 statement_timeout 导致最多取消的查询的问题。
更新回归测试。
修复从 CSV 日志提取执行计划后的格式化。
修复 jsonlog 缺失的 autovacuum 数据报告：平均 autovacuum 耗时、各表移除的元组数，以及 autovacuum 活动报告中按小时统计的 vacuum 次数。感谢 Ales Zeleny 提供补丁。
修复孤立日志行未关联到耗时 bind 查询的问题。感谢 Henrietta Dombrovskaya 报告。修复模式匹配中使用未初始化值的问题。感谢 Junior Dias 提供补丁。
将 --csv-separator 选项应用到原始 CSV 导出。此版本记录中的默认分隔符为分号（;）。感谢 Henrietta Dombrovskaya 提出需求。
原始 CSV 输出中，参数和应用名称为空时不再添加双引号。
原始 CSV 输出中，查询包含分号时添加双引号。感谢 Henrietta Dombrovskaya 报告。

8.2 - pgBadger 12.x 版本记录

pgBadger 12.x 系列的完整上游版本记录

v12.4 · 2023-12-25

这是维护版本，修复了上一版本发布后用户报告的问题。

修复 PgBouncer 1.21 的报告。感谢 Ales Zeleny 提供补丁。
防止按文件并行处理的进程数超过文件数。感谢 maliangzhu 报告。
修复自 v12.3 起损坏的回归测试。感谢 ieshin 报告。
修复 LOG 记录被计入 ERROR 级别记录的情况。感谢 Matti Linnanvuori 报告。

v12.3 · 2023-11-27

这是维护版本，修复了上一版本发布后用户报告的问题，并增加了以下功能：

添加 --include-pid 选项，只报告指定会话 PID（%p）的事件，可多次指定。感谢 Henrietta Dombrovskaya 提出需求。
添加 --include-session 选项，只报告指定会话 ID（%c）的事件，可多次指定。感谢 Henrietta Dombrovskaya 提出需求。
添加 --dump-raw-csv 选项，只解析日志并将信息导出为 CSV，不再进一步处理，也不生成报告。感谢 Henrietta Dombrovskaya 提出需求。

完整变更与致谢如下：

将 pgFormatter 更新到 5.5。
修复 jsonlog 格式的解析结束日期。感谢 jw1u1 报告。
修正“按应用统计会话”标签中的拼写错误。感谢 fairyfar 提供补丁。
修复 INSERT/UPDATE/DELETE 流量图表的缺陷。感谢 fairyfar 提供补丁。
修复 bind 查询中孤立日志行的解析。感谢 youxq 报告。
修复新版 PostgreSQL 的按表统计 analyze 报告。感谢 Jean-Christophe Arnu 提供补丁。
修复 syslog 时间戳包含毫秒时的记录解析。感谢 Pavel Rabel 报告。

v12.2 · 2023-08-20

这是维护版本，修复了上一版本发布后用户报告的问题，并增加了两个功能：

支持 autovacuum 耗时的最大值、平均值和最小值。感谢 Francisco Reinolds 提供补丁。
支持 PgBouncer 的平均等待时间。感谢 Francisco Reinolds 提供补丁。

完整变更与致谢如下：

修复应用名称包含 <...> 时损坏的 HTML 输出。感谢 Fabio Geiss 报告。
修复按数据库过滤时孤立日志行关联错误的问题。感谢 jcasanov 报告。
修复 logplex 前缀的解析。
修复 logplex 孤立日志行的检测。
修复 autovacuum 的 system usage: CPU: ... 行解析。感谢 Francisco Reinolds 提供补丁。
输出到标准输出时，不再添加输出目录前缀。
统一“平均查询耗时”标签。感谢 Francisco Reinolds 提供补丁。
更新新增 pgBadger 选项的文档。感谢 Francisco Reinolds 提供补丁。
修复无法打开任何文件句柄时未中止解析的情况。感谢 vp 报告。
在帮助中补入 %p / %t 必需占位符的日志要求。感谢 Christophe Courtois 提供补丁。
修复 --retention 参数。感谢 Bertrand Bourgier 提供补丁。
修复设置 HTML 输出目录时，提交 0e5c7d5 移除的输出目录清理功能。感谢 Bertrand Bourgier 报告。
修复目标目录包含需要在正则表达式中转义的字符时的输出扩展名。感谢 Bertrand Bourgier 提供补丁。
在 Windows 移植版中，用 localtime 调用替换 POSIX::strftime("%s", ....)。感谢 Bertrand Bourgier 提供补丁。
修复 HTML 输出目录的清理。感谢 Bertrand Bourgier 提供补丁。
默认使用 HTTPS 执行计划 URL。感谢 Philipp Trulson 提供补丁。

v12.1 · 2023-03-20

这是维护版本，修复了过去六个月用户报告的问题。

完整变更与致谢如下：

修复多行参数的解析。感谢 Bekir Niyaz 报告。
修复包含 ::tsrange 的查询无法归一化的问题。感谢 Philippe Griboval 报告。
在事件报告中加入逻辑解码一致性点与复制槽启动的日志记录。
处理时间戳中其他纳秒加时区的格式。感谢 Ronan Dunklau 报告。
修复使用 T 分隔日期和时间时的 %m 检测。感谢 Ronan Dunklau 报告。
添加对 CloudNativePG 生成日志的解析。感谢 codrut panea 提供补丁。
修复生成报告时 --outdir 选项未生效的问题。感谢 Frederic Guiet 报告。
根据最近的文档改动更新 README。感谢 Manisankar 报告。
修正 pgBadger 示例中的拼写错误。感谢 Shinichi Hashiba 提供补丁。

v12.0 · 2022-09-13

这个主要版本修复了过去五个月用户报告的一些问题，并增加了新功能和改进：

移除 Tsung 输出支持。
改善需要替换数百个绑定参数时的性能。
移除 -n | --nohighlight 选项；升级到 pgFormatter 4 后已不再使用该选项。
使用 POST 方法向 explain.depesz.com 提交 auto_explain 执行计划，避免 GET 参数长度限制。
将 --exclude-query 和 --include-query 应用于 bind/parse 记录。
在文档中添加 pgBadger 报告示例的链接。

完整变更与致谢如下：

修复月报因 log file ... must exists 报错而生成失败的问题。感谢 Jaume Sabater 报告。
修复从标准输入读取 PgBouncer 日志时的解析启动调试消息。感谢 aleszeleny 报告。
移除 Tsung 输出支持。
大幅改善绑定参数替换的性能；数百个参数曾可能导致程序无限运行。感谢 Monty Mobile 报告。
修正返回码文档，并修复部分位置的错误返回码。感谢 Jaume Sabater 报告。
修正多处拼写错误。感谢 David Gilman 提供补丁。
移除升级到 pgFormatter 4 后不再使用的 -n | --nohighlight 选项。感谢 Elena Indrupskaya 报告。
修复多处文档问题。感谢 Postgres Pro 的 Elena Indrupskay 提供补丁。
允许 --log-timezone 和 --timezone 使用半小时时差，值可以是整数（例如 2）或小数（例如 2.5）。感谢 Mujjamil-K 提出需求。
允许 --exclude-app 和 --exclude-client 使用正则表达式。感谢 rdnkrkmz 提出需求。
配合上一项相关提交允许使用 --explain-url，并恢复只支持文本格式执行计划的限制。
使用 POST 方法向 explain.depesz.com 提交 auto_explain 执行计划，避免 GET 参数长度限制。感谢 hvisage 报告。
将 --exclude-query 和 --include-query 应用于 bind/parse 记录。感谢 Alec Lazarescu 报告。
修复 RDS 日志中 autovacuum 统计信息的解析。感谢 David Gilman 报告。
修复解析远程日志时日志格式的传递。感谢 spookypeanut 报告。
在文档中添加 pgBadger 报告示例的链接。
修复按用户统计会话的报告。感谢 vitalca 报告。
修复 PostgreSQL 15 输出的 jsonlog 解析。
修复文本格式的错误/事件报告。感谢 Michael Banck 提供补丁。
修正 normalize_error() 中正则表达式的拼写错误。感谢 Michael Banck 提供补丁。

8.3 - pgBadger 11.x 版本记录

pgBadger 11.x 系列的完整上游版本记录

v11.8 · 2022-04-08

本版本修复了过去三个月用户报告的问题，尤其包括增量模式中检测新日志记录的两项修复：

修复 log_line_prefix 使用毫秒时间戳（%m）或纪元时间戳（%n）时的新记录检测。
修复未使用多进程时本地文件的新记录检测。

完整变更与致谢如下：

全面审查并简化日志文件变化的检测。
在事件报告中加入 could not (receive|send) data (from|to) client 消息。感谢 Adrien Nayrat 报告。
修复预备查询名称包含 : 时的解析问题。感谢 aleszeleny 报告。
修复使用毫秒（%m）或纪元（%n）时间戳时的新记录检测。感谢 aleszeleny 报告。
修复未使用多进程时本地文件的新记录检测。感谢 aleszeleny 报告。
修复通过 SSH 读取远程文件时的新记录检测。感谢 Luca Ferrari 报告。
修复“按用户统计连接”报告中用户名混入无关内容的问题。感谢 caseyandgina 报告。
修复使用 URI 时 SSH 命令缺少连接选项的问题。感谢 Luca Ferrari 报告。
处理查询 ID 占位符 %Q。感谢 Adrien Nayrat 提供补丁。
修正错误消息中的拼写错误。感谢 Luca Ferrari 提供补丁。
在事件报告中加入 server process was terminated by signal 消息。感谢 Avi Vallarapu 报告。
文档：修正每周增量命令中的文件名。感谢 Theophile Helleboid 提供补丁。
t/04_advanced.t：修复 syslog 测试。感谢 Christoph Berg 提供补丁。

v11.7 · 2022-01-23

本版本修复了过去五个月用户报告的问题，并作出以下改进：

添加 --no-progressbar 选项，隐藏进度条，同时保留其他输出。
添加 --day-report 选项，重建指定日期的 HTML 报告。它与 --month-report 类似，但仅处理一天；需要增量输出目录及全部必要的二进制数据文件，日期格式为 YYYY-MM-DD。
改善 Heroku logplex 和 Cloud SQL JSON 日志的解析。

完整变更与致谢如下：

更新贡献指南和 Makefile.PL，改善一致性、说明清晰度与依赖管理。感谢 diffuse 提供补丁。
修复二进制模式下最后解析状态文件（--last-parsed）的使用。感谢 wibrt 报告。
为 --last-parsed 添加回归测试，并修复仅报告临时文件时的回归测试。
修正按主机统计会话图表的标题。感谢 Norbert Bede 报告。
修复同时启用 --iso-week-number 和 --incremental 时生成周报的周编号。感谢 hansgv 报告。
添加 --no-progressbar 选项，隐藏进度条，同时保留其他输出。感谢 seidlmic 提出需求。
防止调试模式对多行 jsonlog 打印过多格式未知的日志行。
修复单行 Cloud SQL JSON 日志的解析。感谢 Thomas Leclaire 报告。
修复只启用 log_temp_files 时的临时文件汇总。
即使使用 -q 或 --quiet，指定 -v 后仍打印调试消息。
修复 jsonlog 文件的自动识别。
修复 Cloud SQL 日志文件的解析。感谢 Luc Lamarle 报告。
修复 parse_json_input 中的 PID 提取。感谢 Francois Scala 提供补丁。
添加 --day-report 选项，接受 YYYY-MM-DD 日期并重建该日的 HTML 报告。感谢 Thomas Leclaire 提出需求。
修复进度条中的查询计数。感谢 Guillaume Lelarge 报告。
修复耗时最高的 bind 和 prepare 报告存储了不完整查询的问题。
修复对象标识符的归一化，避免某些情况下把其中数字替换成 ?。
修复以注释开头的归一化查询未格式化的问题。
修复使用 --dbname 时 stderr 格式的多行处理。感谢 Guillaume Lelarge 报告。
修复增量模式使用 --dbname 时未生成报告的问题。感谢 Dudley Perkins 报告。
二进制文件不兼容时不再终止程序，而是继续下一个文件。感谢 Thomas Leclaire 建议。
修复解析器对 Heroku logplex 格式变化的处理。感谢 François Pietka 报告。

v11.6 · 2021-09-04

本版本修复了过去七个月用户报告的问题，并作出以下改进：

检测 PostgreSQL 14 新增的 log_line_prefix 查询 ID。感谢 Florent Jardin 报告。
添加覆盖数据库排除和按数据库拆分报告的高级回归测试。感谢 MigOps Inc 提供补丁。
使用 --explode 时，以多进程生成报告。感谢 MigOps Inc 提供补丁，以及 Thomas Leclaire 提出需求。
添加 --iso-week-number：增量日历每周从周一开始，遵循 ISO 8601，周编号范围为 01 至 53，第 1 周是新年中至少含 4 天的第一周。感谢 Alex Muntada 提出需求。
添加 --keep-comments 选项，保留归一化查询中的注释，以区分归一化结果相同的查询。感谢 Stefan Corneliu Petrea 提出需求。
跳过第三方软件写入 PostgreSQL 日志的 INFO 行。感谢 David Piscitelli 报告。
兼容 PostgresPro 日志，其语句耗时后附有行数与字节大小。感谢 panatamann 报告。
解析包含 T 的时间表示，以支持 journalctl 时间戳。感谢 Graham Christensen 提供补丁。
改善 Windows 移植版。感谢 Bertrand Bourgier 提供补丁。

重要说明：

当时计划在下一个主要版本中默认启用 --iso-week-number，并移除 --start-monday，使每周始终从周一开始；为简化代码，也计划移除以周日作为每周起始日的选项。此条记录的是当时的计划，当前选项请以命令行参考为准。

完整变更与致谢如下：

修复重复的警告消息 database ... must be vacuumed within ... transactions。感谢 Christophe Courtois 报告。
修复使用未初始化变量的问题。感谢 phiresky 报告。
改善查询 ID 的检测，支持负值，并从 csvlog 中读取。
修复增量模式总是再次解析已经处理过的最后一个文件的问题。感谢 Thomas Leclaire 报告。
更新 syslog 格式的正则表达式，支持会话行标记只含一个整数的情况，而不要求两个以连字符分隔的整数。感谢 Timothy Alexander 提供补丁。
修复 JSON 日志使用 --exclude-db 后仍生成被排除数据库报告的问题。感谢 MigOps Inc 提供补丁，以及 Thomas Leclaire 报告。
针对有缺陷的 Storable 版本添加回归测试。
修复增量模式生成周报时替换迭代器使用未初始化值的问题。感谢 Thomas Leclaire、Michael Vitale、Sumeet Shukla 和 Stefan Corneliu Petrea 报告。
添加 g 标志，以替换全部绑定参数。感谢 Nicolas Lutic 和 Sebastien Lardiere 提供补丁。
改善文档。感谢 Stefan Petrea 提供补丁。
修复日志时区变换的计算。感谢 Stefan Petrea 提供补丁。
修复按起止时间过滤日志。
修复按数据库过滤多行查询时孤立日志行关联错误的问题。感谢 Abhishek Mehta 报告。
修复增量模式同时使用 --dbname 与拆分选项 -E 时数据库参数被部分忽略的问题。感谢 lrevest 报告。
更新 JavaScript 资源。
修复缩小屏幕后切换为折叠菜单前的菜单显示。感谢 Guillaume Lelarge 报告。
修复未正确支持跨多行绑定参数值的问题。
将上一补丁对应的修复同步到 pgFormatter。
修复 pgFormatter 代码中替换迭代器使用未初始化值的另一处问题。感谢 Christophe Courtois 报告。
修复查询归一化。感谢 Jeffrey Beale 提供补丁。
使用 --dump-all-queries 时，确保每条语句都以分号结尾。感谢 Christian 报告。
修正拼写，并修复多个日志文件的行结束符类型初始化。
自动检测行结束符类型，修复 Windows 双字节行结束符导致的 LAST_PARSED 偏移问题。感谢 Bertrand Bourgier 提供补丁。
修复 Windows 不支持 strftime %u 时的 get_day_of_week() 移植问题。感谢 Bertrand Bourgier 提供补丁。
修复 Windows 调用 Perl 工具 pl2bat.bat 时，因 pgBadger 读取 __DATA__ 的方式导致生成损坏的 pgbadger.bat。感谢 Bertrand Bourgier 提供补丁。
修复起止时间过滤，并添加时间戳过滤的回归测试。感谢 Alexis Lahouze 和 plmayekar 报告。
修复 pgFormatter 更新引入的模式匹配使用未初始化值问题。感谢 arlt 报告。

v11.5 · 2021-02-18

本版本修复了过去三个月用户报告的问题，并作出以下改进：

添加会话闲置时间报告，计算方式为： “(total sessions time - total queries time) / number of sessions” 要得到可靠结果，需启用 log_connections 与 log_disconnections，并设置 log_min_duration_statement = 0 以记录全部查询。该报告可帮助了解闲置时间，并评估事务模式连接池的价值。报告位于“全局统计”的“会话”标签页，以及“总体活动”的“会话”标签页（按小时统计）。
添加数值匿名化，将数字替换为四位随机数。
将 SQL 格式化器更新为基于 pgFormatter 5.0 的版本。

完整变更与致谢如下：

修复 Cloud SQL 多行语句的解析。感谢 Jon Young 报告。
为匿名化添加回归测试。
修复 maxlength 截断导致匿名化失效的问题。感谢 artl 报告。
在耗时最高的 prepare 和 bind 报告中匿名化参数。感谢 arlt 报告。
支持 logplex 日志前缀中的微秒。感谢 Ross Gardiner 报告。
添加会话闲置时间报告。感谢 Guillaume Lelarge 提出需求。
完成支持 jsonlog 多行内容的补丁。

v11.4 · 2020-11-24

本版本修复了过去四个月用户报告的问题，改善 PostgreSQL 13 日志信息的支持，并增加以下功能：

在“按表统计 vacuum”报告中添加完整的 autovacuum 信息：缓冲区使用（命中、未命中、弄脏）、因页被固定而跳过、跳过的冻结页，以及 WAL 使用（记录数、全页镜像、字节数）。“各表移除的元组”报告加入剩余元组、尚不能移除的元组和剩余页数。这些信息只在“表”标签页提供。
添加检查点启动原因的分布报告。
从连接授权日志中检测应用名称。

完整变更与致谢如下：

修正错误消息中的拼写错误。感谢 Vidar Tyldum 提供补丁。
修复 Windows 上的 can not load incompatible binary data 错误。感谢 Eric Brawner 报告。
修正用法说明和文档中 --html-outdir 的拼写错误。感谢 Vidar Tyldum 提供补丁。
修复 jsonlog/Cloud SQL 格式的自动识别。感谢 Jon Young 报告。
修复 PostgreSQL v13 的 CSV 日志解析。感谢 Kanwei Li 报告，以及 Kaarel Moppel 提供补丁。
修复产生最多临时文件的查询报告的排序。感谢 Sebastien Lardiere 报告。
在调试模式中显示 pgBadger 版本。

v11.3 · 2020-07-26

本版本修复了过去四个月用户报告的问题，并增加了以下功能和命令行选项：

自动检测 UTC 时间戳，避免向图表再次应用时区偏移。
支持 GCP Cloud SQL JSON 日志格式。
添加 --dump-all-queries，将全部查询导出到文本文件，不生成报告，只列出 PostgreSQL 日志中的完整语句列表。绑定参数会填入查询中相应位置。
添加 -Q | --query-numbering，在使用 --dump-all-queries 或 --normalized-only 时为输出查询编号。
添加 --tempdir，指定临时文件目录，适合不允许写入 /tmp 的系统。
添加 --ssh-port，指定非默认 22 的 SSH 端口。URI 写法也支持指定端口，例如： ssh://192.168.1.100:2222//var/log/postgresql-11.log

完整变更与致谢如下：

修复 jsonlog/Cloud SQL 格式的增量报告。感谢 Ryan DeShone 报告。
自动检测 UTC 时间戳，避免应用自动检测的时区偏移；UTC 时间由 JavaScript 转换为本地时区。感谢 Brett Stauner 报告。
修复 journalctl 日志从第二次运行起增量解析失效的问题。感谢 Paweł Koziol 提供补丁。
修复同时使用 -X 与 -E 时的资源文件路径。感谢 Ryan DeShone 报告。
修复“总体活动”报告的读写查询。感谢 alexandre-sk5 报告。
未使用并行模式时添加调试消息。
修复文件大小检测中的 elsif 逻辑，以及添加 --since 后 journalctl 命令多余的空格。感谢 Pawel Koziol 提供补丁。
修复 not a valid file descriptor 错误。感谢 Pawel Koziol 报告。
修复 RDS 文件的增量模式。感谢 Ildefonso Camargo、nodje 和 John Walsh 报告。
添加 -Q | --query-numbering，在使用 --dump-all-queries 或 --normalized-only 时为查询编号，便于外部脚本从输出文件提取多行查询。感谢 Shantanu Oak 提出需求。
修复启用 log_min_duration_statement 时 Cloud SQL JSON 日志的解析。感谢 alexandre-sk5 报告。
修复 RDS 日志中用户的错误哈希键。感谢 vosmax 报告。
修复修改不可创建数组值导致的错误。感谢 John Walsh 和 Mark Fletcher 报告。
支持 GCP Cloud SQL JSON 日志，日志格式（-f）为 jsonlog。感谢 Thomas Poindessous 提出需求。
添加 --dump-all-queries，将全部查询导出到文本文件，不生成报告；绑定参数填入相应位置，不对查询去重或排序，记录全部查询。感谢 Shantanu Oak 提出需求。
添加 --dump-all-queries 文档。
修复新版 PostgreSQL 的 vacuum 报告。感谢 Alexey Timanovsky 报告。
添加 --no-process-info，不再修改进程标题以标识 pgBadger 进程，适用于不支持该操作的系统。感谢 Akshay2378 报告。
添加 --tempdir，指定临时文件目录，默认： File::Spec->tmpdir() || ‘/tmp’ 适合不允许写入 /tmp 的系统。感谢 Akshay2378 报告。
修复压缩文件名含空格或方括号时不受支持的问题。感谢 Alexey Timanovsky 报告。
添加 --ssh-port，指定非默认 22 的 SSH 端口。URI 写法也支持指定端口，例如： ssh://192.168.1.100:2222//var/log/postgresql-11.log 感谢 Augusto Murri 提出需求。

v11.2 · 2020-03-11

本版本修复了过去六个月用户报告的问题，并增加以下功能：

支持并自动识别 AWS Redshift 日志格式。
支持 PgBouncer 1.11 的新日志格式。
支持 zstd 与 lz4 压缩格式。
增量模式下可完全分离统计数据生成与 HTML 报告生成，生成报告时无需重新读取日志。例如，可以每小时运行：
```
pgbadger -I -O "/out-dir/data" --noreport /var/log/postgresql*.log
```
这只在 /out-dir/data 创建二进制数据文件。随后可每晚在独立目录 /out-dir/reports 生成当天的报告，供次日查看：
```
pgbadger -I -l "/out-dir/data/LAST_PARSED" -H "/out-dir/reports" /out-dir/data/2020/02/19/*.bin
```
需要指定最后解析状态的路径、HTML 输出目录，以及当天的二进制数据文件。

新增命令行选项：

添加 --explain-url，覆盖图形化执行计划工具的 URL。当时的默认 URL 为：
```
http://explain.depesz.com/?is_public=0&is_anon=0&plan=
```
可用于本地安装的 PgExplain 或其他工具。pgBadger 将转义后的文本格式执行计划追加到 URL 末尾。
添加 --no-week，增量模式下不生成周报，适合周报消耗过多时间和资源的情况。
添加 --command，指定获取日志记录的命令。pgBadger 打开通向该命令的管道，并解析其输出的日志，例如：

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

这与直接将日志文件作为参数传入等效。需要实时改写日志、从程序提取日志或从数据库生成日志时，此选项尤为有用。例如：

pgbadger -f csv –command ‘psql dbname -c “COPY jrn_log TO STDOUT (FORMAT CSV)”’
添加 --noexplain，不解析或报告 auto_explain 扩展写入日志的执行计划。在 PostgreSQL < 9.0 中，日志包含执行计划时 pgBadger 会生成损坏的报告，此选项可避免该问题。

向后兼容性：

默认将查询截断至 100000 字符；可通过 --maxlength 调整这个人为设定的值。此前默认不截断，可能造成过量资源消耗。限定默认长度更安全，且多数查询不会触及此限制。不过，超过 25000 字符的查询不会进行格式化。

完整变更与致谢如下：

修复 --exclude-client 不生效的问题。感谢 John Walsh 报告。
添加 RDS 日志解析与 --exclude-client 的回归测试。
修复 PgBouncer 日志的进度条，将“查询”标签改为“统计”。
添加 --explain-url，覆盖图形化执行计划工具的 URL。感谢 Christophe Courtois 提出需求。
支持 PgBouncer 1.11 新日志格式。感谢 Dan Aksenov 报告。
支持 zstd 和 lz4 压缩格式。感谢 Adrien Nayrat 提供补丁。
支持并自动识别 AWS Redshift 日志格式。感谢 Bhuvanesh 提出需求。
更新 Redshift 日志格式文档。
添加 --no-week，增量模式下不生成周报。感谢 cleverKermit17 提出需求。
修复 Windows 上文件路径模式匹配导致 pgBadger 失败的问题。
修复 #554：即使指定字符集，西里尔字符及其他编码的语句参数也未在 HTML 中正确显示。该回归由修复 Perl 的 Wide character in print 消息引入；现已撤销原补丁，添加 --wide-char 以恢复所需行为。遇到此消息时请加入该选项。添加西里尔字符和法语编码的回归测试。感谢 4815162342lost 和 yethee 报告。
更新文档，说明 lc_messages = 'en_US.UTF-8' 同样有效。感谢 nodje 报告。
更新 --maxlength 文档，默认截断长度改为 100000，不再默认不截断。感谢 nodje 报告。
修复跨年时的保留期计算。感谢 Fabio Pereira 提供补丁。
修复 RDS 日志格式的解析。感谢 Kadaffy Talavera 报告。
增量模式下没有新日志记录时，不再生成空索引文件。感谢 Kadaffy Talavera 报告。
修复未及时更新的文档。感谢 Eric Hanson 提供补丁。
将文档中的命令行参数从 -no-explain 改为 -noexplain。感谢 Indrek Toom 提供补丁。
无法取得 totalsize 时，回退到默认文件大小。感谢 Adrien Nayrat 提供补丁。
修正示例中的日期。感谢 Greg Clough 提供补丁。
在其余测试中使用压缩文件扩展名的正则表达式，并将 .bin 扩展名的判断独立处理。
支持 zstd 和 lz4 压缩格式。感谢 Adrien Nayrat 提供补丁。
修复 Windows 上剩余的 SIGUSR2 调用。感谢 inrap 报告。
修复大小不确定的日志文件的进度条。
添加 --command，执行命令并从其标准输出获取日志记录。感谢 Justin Pryzby 提出需求。
添加 --noexplain，不解析或报告 auto_explain 写入日志的执行计划，以避免 PostgreSQL < 9.0 中日志包含执行计划时报告损坏。感谢 Massimo Sala 提出需求。
修复命令行指定前缀时的 RDS 日志解析。感谢 Bing Zhao 报告。
修复 RDS 日志格式的增量模式。感谢 Bing Zhao 报告。
修复 RDS 日志解析中的潜在问题。感谢 James van Lommel 和 Simon Dobner 报告。
修复语句分类，并添加回归测试。感谢 alexanderlaw 报告。
修复 IN 子句中单个字符的匿名化。感谢 Massimo Sala 报告。
修复缺少客户端/用户/数据库信息的 RDS 日志行解析。感谢 Konrad 报告。

v11.1 · 2019-09-16

本版本修复了过去三个月用户报告的问题，并增加以下功能和报告：

添加 prepare 或 parse 阶段耗时最高的前 N 条查询报告。
添加 bind 阶段耗时最高的前 N 条查询报告。
添加 prepare/bind/execute 各阶段耗时报告，位于“全局统计”新增的“耗时”标签页。例如： Total query duration: 6m16s Prepare/parse total duration: 45s564ms Bind total duration: 4m46s Execute total duration: 44s71m 这也修复了原“查询总耗时”只报告 execute 总耗时的问题。
支持并自动识别 RDS 与 CloudWatch 日志格式；无法自动识别时可使用 -f rds。
添加 --month-report，生成月度增量报告。
恢复 Windows 操作系统支持。

其他缺陷修复与功能改进：

使用 pod2markdown 自动生成 README.md；命令不存在时不生成该文件。感谢 Derek Yang 提供补丁。
将 WITH 语句归类为 CTE，修复上一版本引入的回归。
修复 Windows 操作系统支持。
支持 RDS 和 CloudWatch 日志；无法自动识别时使用 -f rds。感谢 peruuparkar 提出需求。
修复 -f | --format 未应用于全部参数文件的问题：当自动识别失败时，曾错误沿用第一个文件的格式。感谢 Levente Birta 报告。
更新源码文档，将 pgBadger v7.x 引用改为 v11。感谢 Will Buckner 提供补丁。
限制高频/耗时查询的显示高度，避免巨大查询占满页面。感谢 ilias ilisepe1 提供补丁。
修复“最慢的单次查询”中查询与详细信息溢出的问题。
修复文件、目录与通配符的 SSH URI。感谢 tbussmann 提供补丁。
修正文档中的 URI 示例。感谢 tbussmann 提供补丁。
使用 --rebuild 时隐藏默认输出文件的提示。
在 usage() 输出中添加额外换行，避免构建时破坏 POD 文档。
在文档中恢复 --exclude-client 的说明。感谢 Christoph Berg 报告。

v11.0 · 2019-06-25

本版本加入重要新功能，并修复了过去四个月用户报告的问题。新增功能：

将游标相关查询（DECLARE、CLOSE、FETCH、MOVE）归入新查询类型 CURSOR。
添加生成最多临时文件的 bind 查询报告；需要启用连接与断开连接日志。
添加 --exclude-client，排除指定客户端 IP 的日志记录，可多次指定。
允许 --begin 与 --end 只使用时间。
添加 -H, --html-dir，在增量模式下指定独立的 HTML 输出路径；二进制文件仍保存在 -O, --outdir 指定的目录。
添加 -E | --explode，将主报告拆分为每个数据库一份；与数据库无关的全局信息放入 postgres 数据库报告。
增量模式支持按数据库报告，每个数据库有独立子目录与增量报告。
支持 Heroku PostgreSQL 的 logplex 格式，可这样解析：

heroku logs -p postgres | pgbadger -f logplex -o heroku.html -
查询超过 10Kb 时，先将所有常量字符串参数限制为 30 字符，再将查询截断为 10Kb，避免插入 bytea 等超长查询造成耗时过多或挂起。10Kb 限制可通过 --maxlength 控制；先尝试缩短参数，再归一化查询或按 maxlength 截断。

此版本与旧二进制或 JSON 文件不兼容，增量模式也无法读取旧二进制文件。若升级后仍需保留历史报告，请在新的一周开始时升级，否则周报会损坏。pgBadger 将打印警告并跳过旧二进制文件。

其他缺陷修复与功能改进：

加入版本警告，并跳过不兼容的二进制文件。
将代码格式化器更新至 pgFormatter 4.0。
修复 pgBadger 在 Windows 上挂起的问题。感谢 JMLessard 报告。
更新 tools/pgbadger_tools，兼容 v11 的新二进制文件格式。
添加生成最多临时文件的 bind 查询报告；只有在 postgresql.conf 中启用连接与断开连接日志时才能收集。感谢 Ildefonso Camargo 提出需求。
修复时区自动检测。感谢 massimosala 修复。
使用 --nograph 时移除剩余图表。
使用 --normalized-only 时强制使用 .txt 扩展名。
修复 logplex 格式的 autovacuum/autoanalyze 报告。感谢 Konrad zichul 报告。
修复 Windows 的进度条。感谢 JMLessard 报告。
使用 $prefix_vars{'t_time'} 存储日志时间。感谢 Luca Ferrari 提供补丁。
更新用法与文档，移除 pgBadger 调用前的 perl 命令。感谢 Luca Ferrari 提供补丁。
允许起止条件使用不含日期的时间。感谢 Luca Ferrari 提供补丁。
修正 README 的少量拼写与语法错误。感谢 ofni yratilim 提供补丁。
修复通过 SSH 使用的远程路径。感谢 Luca Ferrari 提供补丁。
更新回归测试，适应按数据库报告功能引入的新结构。
修复全部起止参数中的小数秒。感谢 Luca Ferrari 提供补丁。
修正文档 URL。感谢 Kara Mansel 报告。
修复 auto_explain 解析，并补充 -U 可多次指定的说明。感谢 Douglas J Hunley 报告。
改进多处 HTML/CSS 报告界面。感谢 Pierre Giraud 提供补丁。
更新资源文件。
添加 logplex 格式的回归测试。
支持 Heroku PostgreSQL 的 logplex 格式，可解析日志流： heroku logs -p postgres | pgbadger -f logplex -o heroku.html - 或已保存的日志文件： pgbadger heroku.log logplex 与其他支持的格式一样可自动识别。pgBadger 支持以下默认 log_line_prefix： database = %d connection_source = %r sql_error_code = %e 或简化形式： sql_error_code = %e 如有其他默认前缀，可向上游反馈。也可以始终用 -p | --prefix 指定，例如： pgbadger –p ‘base = %d source = %r sql_state = %e’ heroku.log 感谢 Anthony Sosso 提出需求。
修复关于 URI 使用的帮助信息。
修复上一补丁导致 SSH URI 通配符失效的问题。感谢 Tobias Bussmann 报告。
允许日志路径含空格的 URI。感谢 Tobias Bussmann 报告。
修正文档中的 URI 示例。感谢 Tobias Bussmann 提供补丁。
修复 t/02_basics.t，避免 syslog 测试耗时超过 10s 时失败。感谢 Christoph Berg 提供补丁。

8.4 - pgBadger 10.x 版本记录

pgBadger 10.x 系列的完整上游版本记录

v10.3 · 2019-02-14

这是维护版本，修复了用户报告的日志格式自动识别问题，以及另一处 PgBouncer 日志解析问题。同时添加一项功能：

-o | --outfile 现在可多次指定，使单条命令输出多种格式。例如：
    pgbadger -o out.html -o out.json /log/pgsql-11.log
将生成 HTML 与 JSON 两份报告，分别保存到对应文件。

其他缺陷修复与功能改进：

修复指定数据库、用户、客户端或应用过滤条件时，部分查询未出现在统计报告中的问题。
修复 PostgreSQL >= 10 默认日志行前缀的自动识别。
修复非标准日志行前缀的格式自动识别；--prefix 包含 %t、%m 或 %n，以及 %p 或 %c 时，将格式设为 stderr。感谢 Alex Danvy 报告。
移除行尾多余空格。
为 syslog 解析器添加最小测试。
修复 autodetect_format() 的调用。
使用 maxlength 时截断语句。感谢 Thibaud Madelaine 提供补丁。
添加多种输出格式的测试。
-o | --outfile 可多次指定，使单条命令输出多种格式。例如： pgbadger -o out.txt -o out.html -o - -x json /log/pgsql-11.log 此命令生成文本和 HTML 报告，保存到对应文件，同时向标准输出写出 JSON 报告。感谢 Nikolay 提出需求。
将输出格式检测与输出文件名设置移入专用函数 set_output_extension()。
修复另一处 PgBouncer 日志解析问题。感谢 Douglas J. Hunley 报告。

v10.2 · 2018-12-27

这是维护版本，修复了过去三个月用户报告的问题，并增加以下功能：

支持 PgBouncer 1.8 的 Stats 日志格式。
自动调整 JavaScript 图表的时区。

新增命令行选项与远程读取功能：

添加 --exclude-db，生成指定数据库以外的所有报告。
支持通过 HTTP 或 FTP 下载远程 PostgreSQL 日志。使用 curl 在下载过程中解析，日志不会保存到磁盘。SSH 远程解析也可在命令行以 URI 指定日志文件：
```
    ssh://localhost/postgresql-10-main.log
    http://localhost/postgresql-10-main.log.gz
    ftp://localhost/postgresql-10-main.log
```
当时 HTTP 和 FTP 需要在 URI 末尾指定日志格式：
```
    http://localhost/postgresql-10-main.log:stderr
```
可以指定多个日志 URI，适合同时解析远程 PgBouncer 日志和本地 PostgreSQL 日志。

SSH 协议也支持与远程模式相同的通配符，例如 ssh://localhost/postgresql-10-main.log*。

使用 -r 解析远程文件的旧写法仍可用，但当时已标为过时，并可能在未来版本移除。

其他缺陷修复与功能改进：

调整估算文件大小时的进度条结束处理，例如 bz2 文件与远程压缩文件。
更新版权年份。
补充使用 URI 解析远程日志的说明。
远程压缩文件解析完成后强制进度达到 100%。
在临时文件报告的查询中提取 PL/pgSQL 函数调用信息，并追加到详细信息区域。
修复 CSV 文件的进度条。
修复将二进制文件作为输入时误当日志文件读取的问题。
将查询的 HTML 输出编码为 UTF8，避免 Wide character in print 消息。感谢 Colin ’t Hart 报告。
为检查点距离峰值添加键值信息。
修复 PgBouncer 解析和请求吞吐量报告。感谢 Levente Birta 报告。
修复输入格式使用 csvlog 而非 csv 的问题。
支持 PgBouncer 1.8 Stats 日志格式。感谢 Levente Birta 报告。
CSV 日志禁用并行处理时添加警告。感谢 cstdenis 报告。
在用法中补充 csvlog 强制单进程的说明，涉及 -j 和 -J。感谢 cstdenis 报告。
修复通过 SSH 增量解析多行日志时的未知行格式错误。感谢 Wooyoung Cho 报告。
在 curl 命令中添加 -k（--insecure），允许从使用自签名证书的服务器下载日志。
自动调整 JavaScript 图表时区。感谢 Massimino Sala 提出需求。
支持 HTTP 日志下载，例如： /usr/bin/pgbadger http://www.mydom.com/postgresql-10.log
使用 curl 在下载过程中解析文件。
修复文档。感谢 0xflotus 提供补丁。
代码清理后重新应用绑定参数未替换的修复。感谢 Bernhard J. M. Grun 报告。
添加 --exclude-db，生成指定数据库以外的所有报告，可多次指定。

v10.1 · 2018-09-12

这是维护版本，修复了增量报告、使用 -j 的多进程模式，以及从标准输入解析日志的问题。使用 v10.0 的用户应升级。

添加 PgBouncer 日志解析器的测试。
进行小幅性能改进。
修复 pgBadger 第 12314 行的无效文件描述符错误。
修复启动时进度条中多余的换行。
从项目中移除 CircleCI 文件。
移除测试套件对 bats 和 jq 的依赖，改用 Test::Simple 和 JSON::XS。
增加测试，尤其覆盖 10.0 中损坏的增量模式和标准输入。
同步 pgbadger、POD 和 README，并修正语法错误。感谢 Christoph Berg 提供补丁。
添加通过 APT 和 Yum 安装 Perl 模块 JSON::XS 的文档。
修复增量模式中的 CSS URI。感谢 Floris van Nee 报告。
修复从标准输入查找日志时的致命错误。感谢 Jacek Szpot 报告。
修复 OSX 构建中的 sed 使用。感谢 Steve Newson 提供补丁。
修复增量模式的除零错误。感谢 aleszeleny 报告。
将 SQL::Beautify 替换为 pgFormatter::Beautify v3.1。

v10.0 · 2018-09-09

这是主要版本，增加新功能，并修复上一版本发布后用户报告的全部问题。

支持 PgBouncer 的 syslog 日志格式。
支持全部 auto_explain 格式：text、xml、json 和 yaml。
支持 log_line_prefix 中的 %q 占位符。
支持 Michael Paquier 扩展的 jsonlog 格式，使用 -f jsonlog 解析。
将 SQL 格式化器替换为 pgFormatter v3.0。

新增命令行选项：

添加 --prettify-json，对 JSON 输出进行排版。
添加 --log-timezone +/-XX，按相对 GMT 的小时偏移调整日志中的日期/时间后再解析。如果客户端时区不同，仍可能需要通过 -Z 调整图表时区。
添加 --include-time，直接选择需要展示的时间范围，避免用 --exclude-time 逐一排除不需要的范围。

pgBadger 项目与版权已从 Dalibo 转移给项目作者和官方维护者。请更新链接：

网站：http://pgbadger.darold.net/
源码：https://github.com/darold/pgbadger

作者感谢 Dalibo 团队这些年对 pgBadger 的投入，尤其是 Damien Clochard 和 Jean-paul argudo 对项目推广的帮助。

修复增量模式未报告检查点距离和估计值的问题。感谢 aleszeleny 报告。
修正 PgBouncer 并发会话报告的标题。感谢 Jehan Guillaume De Rorthais 报告。
支持 PgBouncer syslog 日志格式。感谢 djester 提出需求。
修复远程日志为空时的错误。感谢 Parasit Hendersson 报告。
修复二进制格式测试；二进制文件与平台相关，必须现场生成。感谢 Michal Nowak 报告。
修复生成空执行计划的情况。
修复命令行指定前缀时自动识别默认格式的解析。
移除 Makefile.PL 对 git 命令的依赖。
更新选项变更文档，并移除必需前缀中的 [%l-1] 部分。
修复 PostgreSQL 10 的 vacuum/analyze 系统使用信息解析。感谢 Achilleas Mantzios 提供补丁。
修复临时文件活动表格。
移除安装过程对 git 的依赖。
添加 --log-timezone +/-XX，按相对 GMT 的小时偏移调整日志中的日期/时间后再解析。这会使报告时间与原始日志不同，增加按时间搜索的难度。客户端时区不同仍可能需要通过 -Z 调整图表。感谢 xdexter 提出需求，以及 Julien Tachoire 提供补丁。
支持 auto_explain 的 JSON 输出格式。感谢 dmius 报告。
修复 auto_explain 解析器及查询被计数两次的问题。感谢 zam6ak 报告。
修复检查点正则表达式，使其匹配 PostgreSQL 10 日志消息。感谢 Edmund Horner 提供补丁。
在 -f | --format 说明中补入 jsonlog 信息。
修复查询归一化，避免与 bind 查询重复；现在值统一替换为 ?，不再将数字替换为 0、字符串替换为两个单引号。感谢 vadv 报告。
修复日志级别计数。感谢 Jean-Christophe Arnu 报告。
改善对 B::Lint 中裸子程序名检查的兼容性。
修复 perlcritic 检查问题。
添加 --prettify-json，对 JSON 输出排版；默认输出全部写在一行。
修复事件分布报告。
修复 log_line_prefix 包含多个 %% 时 --prefix 的缺陷。感谢 svb007 报告。
添加 --log-timezone +/-XX，按相对 GMT 的小时偏移调整日志中的日期/时间后再解析。这会使报告时间与原始日志不同，增加按时间搜索的难度。客户端时区不同仍可能需要通过 -Z 调整图表。感谢 xdexter 提出需求。
从关键字列表移除 INDEXES，并加入 BUFFERS。
修复游标查询的归一化。
移除 Dockerfile 和 docker run 文档。上游认为 pgBadger 是无强制额外依赖的单个 Perl 脚本，可在不同平台运行；无需安装时，可直接复制 pgbadger 文件并执行。
修复没有临时文件活动时的网格布局。感谢 Pierre Giraud 提供补丁。
在文档中加入 log_min_duration_statement 与 log_duration + log_statement 的注意事项。感谢 Julien Tachoire 提供补丁。
将时区偏移应用到柱状图。感谢 Julien Tachoire 提供补丁。
同一 PID 出现错误时删除当前临时文件信息。感谢 Julien Tachoire 提供补丁。
示例统一使用 app=，同时支持 appname=。此前部分示例使用 appname=，但代码未识别它；现在示例改用 app=，解析器也接受 appname=。感谢 Christoph Berg 提供补丁。
修正 -J 的长选项名称，应为 --Jobs，而非 --job_per_file。感谢 Chad Trabant 报告，以及 Etienne Bersac 提供补丁。
忽略 blib 文件。感谢 Etienne Bersac 提供补丁。
添加一致性测试。感谢 damien clochard 提供补丁。
更新文档：stderr 不是 -f 的默认值。感谢 Christophe Courtois 提供补丁。
始终更新 POD 和 README。感谢 Etienne Bersac 提供补丁。
添加回归测试。感谢 Etienne Bersac 提供补丁。
添加 editorconfig 配置。感谢 Etienne Bersac 提供补丁。
从 gitignore 中移除 vi 临时文件规则。感谢 Etienne Bersac 提供补丁。
添加 --include-time，直接选择要查看的时间。例如，从一周日志中只查看一两天，可以用一次 --include-time 替代多个 --exclude-time。感谢 Wesley Bowman 提供补丁。
检查 POD 语法。感谢 Etienne Bersac 提供补丁。
添加 HACKING，记录测试方法。感谢 Etienne Bersac 提供补丁。
移除过时的 --bar-graph 选项。感谢 Etienne Bersac 提供补丁。
移除容易误导的 .perltidyrc。该文件来自 2012 年，代码已与其规范差距很大，perltidy 的统一差异达 10k 行。感谢 Etienne Bersac 提供补丁。
修复 SQL 格式化中使用未初始化值的问题。感谢 John Krugger 和 Jean-paul Argudo 报告。

8.5 - pgBadger 9.x 版本记录

pgBadger 9.x 系列的完整上游版本记录

v9.2 · 2017-07-27

这是维护版本，并增加以下功能：

添加检查点距离与估计值报告。
SQL 格式化器支持 AWS Redshift 关键字。
远程模式自动识别日志格式，允许同时解析远程 PgBouncer 与 PostgreSQL 日志。

其他缺陷修复与功能改进：

修复直方图未显示超过最后一个分组范围的数据的问题。
修复缺少日志行号模式 [%l-n] 时的 journalctl 解析。感谢 Christian Schmitt 报告。
添加检查点距离与估计值报告。感谢 jjsantam 提出需求。
为更新 CSS 与 JavaScript 的脚本 tools/updt_embedded_rsc.pl 补充工作内容说明。
全部日志文件为空时不再警告，并以返回码 0 退出。
修复 build_log_line_prefix_regex() 未在 %regex_map 中查找 %n 的问题。感谢 ghosthound 提供补丁。
将 FATAL: cannot use CSV 的错误级别改为 WARNING。感谢 kong1man 报告。
修复未初始化值的警告。感谢 Payal 报告。
在错误归一化中加入 permission denied 消息。
将内嵌 pgFormatter 更新至最新提交 5bdc018。
支持 AWS Redshift 关键字。感谢 cavanaug 提出需求。
修复查询被取消后临时文件报告缺少该查询的问题。感谢 Fabrizio de Royes Mello 报告。
将绑定参数替换为 ?，对查询进行归一化。
增加校验，防止结束时间早于起始时间。感谢 Christophe Courtois 提供补丁。
修正多处拼写与语法；程序名称统一为 pgBadger，可执行文件名除外。统一 PgBouncer、GitHub 和 CSS 的官方写法，并同步 POD 与 README。感谢 Euler Taveira 提供补丁。
修复使用 --disable-type 时的菜单：将 top_cancelled_info 判断及列表闭合放入 disable_type 判断中，同时调整 disable_lock 判断的缩进。感谢 Euler Taveira 提供补丁。
修复使用未初始化值的问题。感谢 johnkrugger 报告。
远程日志自动识别格式时，移除读取日志文件的测试。感谢 clomdd 报告。
远程模式自动识别日志格式，允许同时解析远程 PgBouncer 和 PostgreSQL 日志。
修复日志行校验后错误增加会话数的问题。感谢 Achilleas Mantzios 报告。
小幅调整 pgBadger 描述的格式。
修复文档中的重复信息。感谢 cscatolini 提供补丁。

v9.1 · 2017-01-24

这是维护版本，并增加以下功能：

当 log_line_prefix 包含 SQLState（参见 %e）时，报告错误类别分布。
将 SQL 格式化器更新至 pgFormatter v1.6。
改善错误消息归一化。
添加 --normalized-only，生成包含日志中全部归一化查询及次数的文本文件。
允许以 %c（会话 ID）替代 %p（PID）作为唯一会话标识。
在事件报告中加入等待锁的消息。
添加 --start-monday，使日历每周从周一开始，默认则从周日开始。

其他缺陷修复与功能改进：

日志行前缀含 SQLState 时，报告错误类别分布。感谢 jacks33 提出需求。
修复调整窗口大小时的增量全局索引。感谢 clomdd 报告。
修复 log_line_prefix 的命令标签占位符 %i，允许含空格。
修复 --exclude-line，以及同时启用保留策略与 --noreport 时删除过期目录的逻辑。
修正 vacuum 活动表中的拼写错误。感谢 Nicolas Gollet 提供补丁。
修复 autovacuum 报告。感谢 Nicolas Gollet 提供补丁。
修正标志作者为 Damien Cazeils，并修正英文注释。感谢 Thibaut Madelaine 提供补丁。
在 -f 说明中补充 PgBouncer 日志格式。感谢 clomdd 报告。
在文档中补充 --normalized-only 信息。
修复上一补丁破坏的日期/时间报告。
修复 log_duration=on 与 log_statement=all 时耗时和查询的关联。感谢 Eric Jensen 报告。
修复 advisory lock 消息的归一化。感谢 Thibaut Madelaine 报告。
修复 auto_explain 输出的报告。感谢 fch77700 报告。
修复标准输入日志记录触发不需要的格式自动识别的问题。感谢 Jesus Adolfo Parra 报告。
在前缀中查找数据库客户端的正则表达式停止字符中加入左括号，以处理包含源端口的 PostgreSQL 客户端字符串。感谢 Jon Nelson 提供补丁。
修正拼写错误。感谢 Jon Nelson 提供补丁。
允许以 %c（会话 ID）替代 %p（PID）作为唯一会话标识。感谢 Jerryliuk 报告。
支持当时预计 PostgreSQL 10.0 将采用的默认 log_line_prefix：'%m [%p] '。
修复缺失的首行解释器调用。
修复 CSV 报告缺少平均值的问题。感谢 Yosuke Tomita 报告。
修正 autodetect_format() 的错误消息。
添加 --start-monday，使日历每周从周一开始，默认从周日开始。感谢 Joosep Mae 提出需求。
修复 --histo-average。感谢 Yves Martin 报告。
在文档中移除 --ssh-option 的复数写法。感谢 mark-a-s 报告。
修复 --exclude-time 过滤，并重写跳过无关日志行及更新进度条的代码。感谢 Michael Chesterton 报告。
修复前缀中使用 %r 而非 %h 的支持。

v9.0 · 2016-09-02

这个主要版本迁移至 Bootstrap 3，并升级全部资源文件（CSS 与 JavaScript）。同时修复缺陷并改进功能。

与旧增量报告的向后兼容性可能得以保留。

将资源文件的源码和许可证放入专用子目录，并添加脚本更新内嵌于 pgBadger 的压缩资源。感谢 Christoph Berg 协助并提出需求。
启用连接日志且 log_line_prefix 缺少用户、数据库或主机信息时，尝试从连接字符串检测这些值。

扩展正则表达式，自动识别数据库名、用户名、客户端 IP 与应用名称。表达式如下：
```
db => qr/(?:db|database)=([^,]*)/;
user => qr/(?:user|usr)=([^,]*)/;
client => qr/(?:client|remote|ip|host)=([^,]*)/;
appname => qr/(?:app|application)=([^,]*)/;
```
在增量模式下，为新的 CSS 和 JavaScript 创建以 pgBadger 主版本号命名的子目录，以兼容旧版报告。
放大 pgBadger 标志，避免在新字体大小下显得过小。
在全部报告中归一化详细信息。
修复锁报告中重复的复制图标。
修复会话耗时直方图缺失的图表。感谢 Guillaume Lelarge 报告。
添加 LICENSE 文件，注明资源文件使用的许可证。感谢 Christoph Berg 提供补丁。
修补 jqPlot，修复下载部分图表时的无限循环。感谢 Julien Tachoires 协助解决。
tools/updt_embedded_rsc.pl 会将补丁应用到 resources/jquery.jqplot.js；已应用过时不会报错。
移除饼图数据集末尾多余的逗号。感谢 Julien Tachoires 报告。
调整归一化错误的显示。
移除未使用或自动生成的文件。
更新全部 JavaScript/CSS 资源，并创建目录存放所用 JavaScript 库的源码。新脚本 tools/updt_embedded_rsc.pl 可生成这些文件的压缩版本并嵌入 pgBadger，也会将 FontAwesome.otf 字体嵌入 fontawesome.css。

9 - 支持与贡献

报告缺陷、提出功能需求、贡献补丁并寻找 PostgreSQL 专业支持

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

缺陷与功能需求

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

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

贡献补丁

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

上游文档生成流程为：

$ perl Makefile.PL
$ make README

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

商业支持

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

10 - 许可证与致谢

PostgreSQL License 条款、作者信息与内嵌第三方组件

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

PostgreSQL License

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 的对应版本中逐项致谢。

内嵌代码与报告资源

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

组件	许可证
bean.js、Bootstrap、jQuery、Underscore	MIT
jqPlot	用户可选择 MIT 或 GPL-2.0
Font Awesome 字体	SIL Open Font License 1.1
Font Awesome CSS	MIT

pgBadger 13.2 中文文档

为什么使用 pgBadger

报告包含什么

文档阅读顺序

上游链接

1 - 下载与安装

选择分发渠道

运行要求

从官方归档安装

安装开发版源码

验证安装

2 - 命令行参考

用法与选项

3 - PostgreSQL 日志配置

最小查询日志配置

日志前缀的必需字段

建议记录的运行事件

保持服务端消息为英文

避免互相冲突的语句设置

4 - 并行处理

使用 -j 拆分单个大文件

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

上游基准测试

限制与临时文件

5 - 增量报告

生成每日与每周报告

保留策略

把公共资源单独写出

重建已有报告

添加月度报告

6 - 输出格式

HTML 与文本

二进制中间数据

JSON

原始数据与查询导出

7 - 报告示例

完整报告

增量报告层级

安全与隐私

8 - 版本历史

8.1 - pgBadger 13.x 版本记录

v13.2 · 2025-12-29

v13.1 · 2025-03-16

v13.0 · 2024-12-08

8.2 - pgBadger 12.x 版本记录

v12.4 · 2023-12-25

v12.3 · 2023-11-27

v12.2 · 2023-08-20

v12.1 · 2023-03-20

v12.0 · 2022-09-13

8.3 - pgBadger 11.x 版本记录

v11.8 · 2022-04-08

v11.7 · 2022-01-23

v11.6 · 2021-09-04

v11.5 · 2021-02-18

v11.4 · 2020-11-24

v11.3 · 2020-07-26

v11.2 · 2020-03-11

v11.1 · 2019-09-16

v11.0 · 2019-06-25

8.4 - pgBadger 10.x 版本记录

v10.3 · 2019-02-14

v10.2 · 2018-12-27

v10.1 · 2018-09-12

v10.0 · 2018-09-09

8.5 - pgBadger 9.x 版本记录

v9.2 · 2017-07-27

v9.1 · 2017-01-24

v9.0 · 2016-09-02

9 - 支持与贡献

缺陷与功能需求

贡献补丁

商业支持

10 - 许可证与致谢

PostgreSQL License

作者与设计致谢

内嵌代码与报告资源

使用 `-j` 拆分单个大文件

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