pgBadger: 快速生成 PostgreSQL 日志分析报告

一月 16, 2024

摘要pgBadger是一个工具,可用于在 PostgreSQL 中生成日志分析报告。

本文包含以下部分:

概要

用法:pgbadger [选项] logfile […]

PostgreSQL 日志分析器,具有完整详细的报告和图表。

参数

logfile 可以是单个日志文件、文件列表,或者返回一个文件列表的 shell 命令。如果要从 stdin 传入日志内容,请使用 - 作为文件名。请注意,来自 stdin 的输入不适用于 csvlog。

选项

  • -a | --average minutes

    生成查询和连接的平均图的分钟数。默认为 5 分钟。

  • -A | --histo-average min

    生成查询直方图的分钟数。默认为 60 分钟。

  • -b | --begin datetime

    要在日志中解析的数据的开始日期/时间(timestamp 或 time)

  • -c | --dbclient host

    仅报告给定客户端主机的日志内容。

  • -C | --nocomment

    从查询中删除类似 /* … */ 的注释。

  • -d | --dbname database

    仅报告给定数据库的日志内容。

  • -D | --dns-resolv

    客户端 IP 地址将替换为其 DNS 名称。请注意,这确实会减慢 pgBadger 的速度。

  • -e | --end datetime

    要在日志中解析的数据的结束日期/时间(timestamp 或 time)

  • -E | --explode

    通过为每个数据库生成一个报表来拆分主报表。与数据库无关的全局信息,将添加到 postgres 数据库报告中。

  • -f | --format logtype

    可能的值:syslog、syslog2、stderr、jsonlog、csv、pgbouncer、logplex、rds 和 redshift。当 pgBadger 无法检测出日志格式时,请使用此选项。

  • -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,要将输出转储到 stdout,请使用 - 作为文件名。

  • -O | --outdir path

    输出文件必须保存到的目录。

  • -p | --prefix string

    postgresql.conf 中自定义的log_line_prefix的值。仅当您未使用 pgBadger 文档中指定的标准前缀时才使用它,例如,如果您的前缀包含客户端 ip 或应用程序名称等其他变量。请参阅下面的示例。

  • -P | --no-prettify

    禁用美化 SQL 查询的格式化程序。

  • -q | --quiet

    不要打印任何内容到 stdout,甚至不要打印进度条。

  • -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

    在增量模式下,允许 pgBadger 以单独的文件,将 CSS 和 JS 文件写入到输出目录中。

  • -z | --zcat exec_path

    设置 zcat 程序的完整路径。如果 zcat、bzcat 或 unzip 不在路径中,请使用它。

  • -Z | --timezone +/-XX

    设置 GMT 时区的小时数。使用它来调整 JavaScript 图表中的日期/时间。该值可以是整数(如:2)或浮点数(如:2.5)。

  • --pie-limit num

    低于 num% 的饼图数据会显示一个总和。

  • --exclude-query regex

    任何与给定正则表达式匹配的查询,都将从报表中排除。例如:"^(VACUUM|COMMIT)"。您可以多次使用此选项。

  • --exclude-file filename

    在指定正则表达式从报表中排除查询时,限定包含用于排除查询的日志文件的路径。每行一个正则表达式。

  • --include-query regex

    任何与给定正则表达式不匹配的查询,都将从报表中排除。您可以多次使用此选项。例如:"(tbl1|tbl2)"。

  • --include-file filename

    在指定正则表达式从报表中筛选查询时,限定包含用于筛选查询的日志文件的路径。每行一个正则表达式。

  • --disable-error

    不生成错误报告。

  • --disable-hourly

    不生成每小时报告。

  • --disable-type

    不要按类型、数据库或用户生成查询报告。

  • --disable-query

    不生成查询报告(最慢、最频繁、按用户的查询、按数据库的查询等)。

  • --disable-session

    不生成会话报告。

  • --disable-connection

    不生成连接报告。

  • --disable-lock

    不生成锁的报告。

  • --disable-temporary

    不生成临时对象的报告。

  • --disable-checkpoint

    不生成检查点/重启点报告。

  • --disable-autovacuum

    不生成 autovacuum 报告。

  • --charset

    用于设置要使用的 HTML 字符集。默认值:utf-8。

  • --csv-separator

    用于设置 CSV 字段分隔符,默认值:,

  • --exclude-time regex

    任何与给定正则表达式匹配的时间戳,都将从报告中排除。示例:“2013-04-12 .*"。您可以多次使用此选项。

  • --include-time regex

    报告中仅包含与给定正则表达式匹配的时间戳。示例:“2013-04-12 .*"。您可以多次使用此选项。

  • --exclude-db name

    从报表中排除指定数据库的日志内容。示例:“pg_dump”。可多次使用。

  • --exclude-appname name

    从报表中排除指定应用程序名称的日志内容。示例:“pg_dump”。可多次使用。

  • --exclude-line regex

    排除任何与给定正则表达式匹配的日志内容。可多次使用。

  • --exclude-client name

    排除指定客户端 IP 的日志内容。可多次使用。

  • --anonymize

    隐藏查询中的所有常量值,可用于隐藏机密数据。

  • --noreport

    在增量模式下不会创建任何报告。

  • --log-duration

    强制 pgBadger 关联由 log_duration = on 和 log_statement = ‘all’ 生成的日志内容。

  • --enable-checksum

    用于在每个查询报表下添加一个 MD5 校验和。

  • --journalctl command

    通过调用 journalctl 替换 PostgreSQL 日志文件的命令。基本上可能是:journalctl -u postgresql-9.5

  • --pid-dir path

    设置 PID 文件必须存储到的路径。默认 /tmp

  • --pid-file file

    设置 pid 文件的名称,以管理 pgBadger 的并发执行。默认值:pgbadger.pid

  • --rebuild

    在包含二进制数据文件的增量输出目录中,用于重建所有 HTML 报表。

  • --pgbouncer-only

    仅在页面头部显示与 PgBouncer 相关的菜单。

  • --start-monday

    在增量模式下,日历周从星期日开始。使用此选项可在星期一开始。

  • --iso-week-number

    在增量模式下,日历周从星期一开始,并遵循 ISO 8601 周数,范围 01 到 53,其中第 1 周是新年中至少有 4 天的第一周。

  • --normalized-only

    仅将所有规范化的查询转储到 out.txt

  • --log-timezone +/-XX

    设置从 GMT 时区开始的小时数,从日志文件读取到日期/时间后,在解析日志内容之前必须用该时区调整时间。使用此选项会使得根据日期/时间搜索日志变得更加困难。该值可以是整数(例如:2)或浮点数(例如:2.5)。

  • --prettify-json

    如果您希望美化 JSON 输出,请使用它。

  • --month-report YYYY-MM

    创建指定月份的累积 HTML 报表。需要有增量报告输出目录,和所有必要的二进制数据文件。

  • --day-report YYYY-MM-DD

    创建指定日期的 HTML 报告。需要有增量报告输出目录,和所有必要的二进制数据文件。

  • --noexplain

    不要处理 auto_explain 生成的日志行。

  • --command CMD

    用以检索 stdin 上的日志行要执行的命令。pgBadger 将打开一个命令的管道,并解析命令生成的日志内容。

  • --no-week

    通知 pgbadger 不要以增量模式构建每周报告。如果要花费太多时间,这会很有用。

  • --explain-url URL

    使用它来覆盖图形化解释工具的 URL。默认值:https://explain.depesz.com/

  • --tempdir DIR

    设置用来写入临时文件的目录。默认值:File::Spec->tmpdir() || '/tmp'

  • --no-process-info

    禁止更改进程标题,以帮助识别 pgbadger 进程,某些系统不支持它。

  • --dump-all-queries

    转储日志文件中找到的所有查询,替换查询中各个占位符位置包含的绑定参数。

  • --keep-comments

    不要从规范化查询中删除注释。如果要区分相同的规范化查询,它可能很有用。

  • --no-progressbar

    禁用进度条。

pgBadger 能够使用无密码 ssh 连接解析一个远程日志文件。使用 -r 或 --remote-host 设置主机 IP 地址或主机名。还有一些额外的选项来完全控制 ssh 连接。

  • --ssh-program ssh

    要使用的 SSH 程序的路径。默认值:ssh。

  • --ssh-port port

    用于连接的 SSH 端口。默认值:22。

  • --ssh-user username

    连接登录名。默认为运行的用户。

  • --ssh-identity file

    要使用的认证文件的路径。

  • --ssh-timeout second

    SSH 连接超时时间。默认值:10 秒。

  • --ssh-option options

    用于 SSH 连接的 -o 选项列表。

    始终使用的选项:

    • -o ConnectTimeout=$ssh_timeout
    • -o PreferredAuthentications=hostbased,publickey

也可以使用 URI 指定要解析的日志文件,支持的协议为 http[s] 和 [s]ftp。curl 命令会被用于下载文件,并在下载过程中解析文件。还支持 ssh 协议,并可以像访问远程主机一样使用 ssh 命令。请参阅下面的示例。

返回码:

  • 0:成功时
  • 1:发生错误时退出
  • 2:如果被中断,例如使用 CTR+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 -
# 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

对远程日志文件使用 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/

如果您在每天 23:00 和 13:00,会进行一次 pg_dump,每次半小时内完成,则可以按如下方式使用 pgBadger,将这些时间段从报告中排除:

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 -

这将通过 stdin 将 Heroku PostgreSQL 日志流式传输到 pgbadger。

pgBadger 可以使用 rds 格式自动检测 RDS 和 cloudwatch 的 PostgreSQL 日志:

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

每个 CloudSQL PostgreSQL 日志都是一个相当普通的 PostgreSQL 日志,但封装为 JSON 格式。它是由 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 2919-05 /path/to/incremental/reports/

这会将月份名称的链接添加到增量报表的日历视图中,以查看 2019 年 5 月的报告。如果报告是使用 -E 或 --explode 选项生成的,请带上它们。

描述

pgBadger 是一个专为提高速度而构建的 PostgreSQL 日志分析器,可根据您的 PostgreSQL 日志文件提供完全详细的报告。这是一个小型的独立 Perl 脚本,其性能优于任何其他 PostgreSQL 日志分析器。

它是用纯 Perl 编写的,并使用一个 JavaScript 库(flotr2)来绘制图表,因此您不需要安装任何其他 Perl 模块或其他软件包。此外,该库为我们提供了更多功能,例如缩放。pgBadger 还使用了 Bootstrap JavaScript 库和 FontAwesome 网络字体进行更好的设计。一切都是嵌入形式的。

如果文件足够长,pgBadger 能够自动检测您的日志文件格式(syslog、stderr、csvlog 或 jsonlog)。它可以解析大型日志文件,以及压缩日志文件。支持的压缩格式有 gzip、bzip2、lz4、xz、zip 和 zstd。对于 xz 格式,必须具有高于 5.05 的 xz 版本,以支持 --robot 选项。LZ4 文件必须使用 --content-size 选项进行压缩,pgbadger 才能确定未压缩的文件大小。有关完整的特性列表,请参见下文。

所有图表都是可缩放的,可以保存为 PNG 图像。

您还可以使用命令行选项,限制 pgBadger 仅报告错误,或者删除报告的任何部分。

pgBadger 支持在 postgresql.conf 文件的log_line_prefix参数中设置的任何自定义格式,只要它至少指定了 %t 和 %p 模式即可。

pgBadger 允许通过使用 -j 选项指定 CPU 数量,并行处理单个或多个日志文件。

如果要节省系统性能,还可以使用log_duration替代log_min_duration_statement,仅报告查询的持续时间和数量。

特性

pgBadger 可以报告有关 SQL 查询的所有信息:

  • 总体统计数据。
  • 等待次数最多的查询。
  • 等待时间最长的查询。
  • 生成最多临时文件的查询。
  • 生成最大临时文件的查询。
  • 最慢的查询。
  • 花费最多时间的查询。
  • 出现次数最多的查询。
  • 出现次数最多的错误。
  • 查询时间的直方图。
  • 会话时间的直方图。
  • 热点查询中涉及的用户。
  • 热点查询中涉及的应用程序。
  • 生成最多取消的查询。
  • 取消最多的查询。
  • 耗时最多的预备/绑定查询

以下报告还提供每小时的图表,分为五分钟的时间段:

  • SQL 查询统计信息。
  • 临时文件统计信息。
  • 检查点统计信息。
  • 自动清理进程和自动分析进程的统计信息。
  • 取消的查询。
  • 错误事件(panic、fatal、error 和 warning)。
  • 错误分类的分布。

还有一些关于以下分布的饼图:

  • 锁统计信息。
  • 按类型(选择/插入/更新/删除)分类的查询。
  • 每个数据库/应用程序的查询类型分布
  • 每个数据库/用户/客户端/应用程序的会话数。
  • 每个数据库/用户/客户端/应用程序的连接数。
  • 每个表的自动清理和自动分析。
  • 每个用户的查询和每个用户的总持续时间。

所有图表都是可缩放的,可以保存为 PNG 图像。报告的 SQL 查询会自动高亮和美化。

pgBadger 还能够解析 PgBouncer 日志文件,并创建以下报告:

  • 请求吞吐量
  • 字节 I/O 吞吐量
  • 平均查询持续时间
  • 同步会话
  • 会话时间直方图
  • 每个数据库的会话
  • 每个用户的会话
  • 每个主机的会话
  • 已建立的连接
  • 每个数据库的连接
  • 每个用户的连接
  • 每个主机的连接
  • 最常用的保留池
  • 最常见的错误/事件

您还可以使用增量报告,包括一份每天的报告和一份每周的累积报告。有两种多进程模式可用于加快日志解析速度,一种是每个日志文件使用一个 CPU 核心,另一种是使用多个 CPU 核心来解析单个文件。这些模式可以组合使用。

可以使用 -A 命令行选项调整直方图粒度。默认情况下,它们会报告每小时发生的每个热点查询/错误的平均值,但您可以指定细化到分钟的粒度。

pgBadger 还可以在一个中心位置,使用无密码 SSH 连接解析远程日志文件。此模式可用于压缩文件,和按文件的多进程模式(-J),但不能用于 CSV 日志格式。

报告的示例可在此处找到:https://pgbadger.darold.net/#reports

要求

pgBadger 是一个单一的 Perl 脚本 - 除了一个现代的 Perl 发行版之外,您不需要任何东西。图表是使用 JavaScript 库渲染的,因此除了 Web 浏览器之外,您不需要其他任何东西。您的浏览器将完成所有工作。

如果您计划解析 PostgreSQL CSV 日志文件,您可能需要一些 Perl 模块:

Text::CSV_XS - to parse PostgreSQL CSV log files.

此模块是可选的,如果您没有 CSV 格式的 PostgreSQL 日志,则无需安装它。

如果要将统计信息导出为 JSON 文件,则需要一个额外的 Perl 模块:

JSON::XS - JSON serialising/deserialising, done correctly and fast

此模块是可选的,如果不选择 json 输出格式,则无需安装。在类 Debian 的系统上,您可以使用以下命令来安装它:

sudo apt-get install libjson-xs-perl

在类 RPM 的系统上,使用:

sudo yum install perl-JSON-XS

压缩的日志文件格式可从文件扩展名自动检测。如果 pgBadger 找到 gz 扩展名,它将使用 zcat 命令;如果是 bz2 扩展名,它将使用 bzcat;对于 lz4,它将使用 lz4cat;对于 zst,它将使用 zstdcat;如果文件扩展名为 zip 或 xz,则将使用 unzip 或 xz 命令。

如果在 PATH 环境变量中找不到这些命令,请使用 --zcat 命令行选项来更改此路径。例如:

--zcat="/usr/local/bin/gunzip -c" or --zcat="/usr/local/bin/bzip2 -dc"
--zcat="C:\tools\unzip -p"

默认情况下,pgBadger 会根据文件扩展名使用 zcat、bzcat、lz4cat、zstdcat 和 unzip 命令。如果使用压缩格式的默认自动检测,则可以混合使用 gz、bz2、lz4、xz、zip 或 zstd 文件。指定自定义的 --zcat 选项值,就无法混合使用多种压缩格式了。

请注意,多进程处理不能用于压缩文件或 CSV 文件,也不能在 Windows 平台下使用。

安装

从 GitHub 下载 tarball,并解压缩归档文件,如下所示:

tar xzf pgbadger-11.x.tar.gz
cd pgbadger-11.x/
perl Makefile.PL
make && sudo make install

默认情况下,这会将 Perl 脚本 pgbadger 复制到 /usr/local/bin/pgbadger,并将手册页复制到 /usr/local/share/man/man1/pgbadger.1。这些都是 ‘site’ 安装的默认安装目录。

如果要在 /usr/ 位置下安装所有内容,请使用 INSTALLDIRS=‘perl’ 作为 Makefile.PL 的参数。这样,脚本将安装到 /usr/bin/pgbadger,手册页将安装到 /usr/share/man/man1/pgbadger.1。

例如,要在类 Debian 的系统上安装所有内容,请按以下步骤操作:

perl Makefile.PL INSTALLDIRS=vendor

默认情况下,INSTALLDIRS 设置为 site。

PostgreSQL 配置

在开始之前,您必须在 postgresql.conf 中启用和设置一些配置项。

您必须首先启用 SQL 查询日志记录,才能分析某些内容:

log_min_duration_statement = 0

这样会记录每条语句,在繁忙的服务器上,您可能希望增加此值,仅记录持续时间较长的查询。请注意,如果设置log_statement为 ‘all’,则不会通过log_min_duration_statement指令记录任何内容。有关详细信息,请参阅下一章。

pgBadger 支持在 postgresql.conf 文件的log_line_prefix配置中,设置任何自定义格式,只要它至少指定一个时间转义序列(%t、%m 或 %n),和一个与进程相关的转义序列(%p 或 %c)。

例如,对于 ‘stderr’ 日志格式,log_line_prefix必须至少有:

log_line_prefix = '%t [%p]: '

日志行前缀可以添加用户、数据库名称、应用程序名称和客户端 IP 地址,如下所示:

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

或者对于 syslog 的日志文件格式:

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

也可以是向 stderr 输出的日志行前缀:

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

或者对于 syslog 输出:

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

您需要在 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_statement,因为 pgBadger 不会解析其日志格式。

当然,您的日志消息应该是英文的,无论是否支持国际化语言:

lc_messages='en_US.UTF-8'
lc_messages='C'

pgBadger 解析器不支持其他区域设置,比如像 ‘fr_FR.UTF-8’。

记录语句

有关log_min_duration_statementlog_durationlog_statement配置项的注意事项。

如果希望查询统计信息包含实际的查询字符串,则必须将log_min_duration_statement设置为 0,或多一点的毫秒数。

如果您只想报告查询的持续时间和数量,不需要有关查询的所有详细信息,可以将log_min_duration_statement设置为 -1,以禁用它,并在 postgresql.conf 文件中启用log_duration。如果想要添加最常见的查询报告,可以选择将log_min_duration_statement设置为更高的值,或启用log_statement

启用log_min_duration_statement后,会添加有关最慢的查询和花费时间最多的查询的报告。请注意,如果您已设置log_statement为 ‘all’,使用log_min_duration_statement不会记录任何内容。

警告:不要同时启用log_min_duration_statementlog_durationlog_statement,这会产生错误的计数器值。请注意,这也会大大增加日志的大小。应该始终首选log_min_duration_statement

并行处理

要启用并行处理,您只需使用 -j N 选项,其中 N 是要使用的 CPU 核数。

然后,pgBadger 会按如下方式进行处理:

for each log file
    chunk size = int(file size / N)
    look at start/end offsets of these chunks
    fork N processes and seek to the start offset of each chunk
        each process will terminate when the parser reach the end offset of its chunk
        each process write stats into a binary temporary file
    wait for all children processes to terminate
All binary temporary files generated will then be read and loaded into memory to
build the html output.

使用这种方法,在日志块的开头/结尾,对于每个日志文件 pgBadger 可能会截断或省略最多 N 个查询,如果您的日志文件中有数百万个查询,这是一个可忽略不计的差距。您正在寻找的查询,丢失的几率接近 0,这就是为什么这个差距被认为是合适的原因。大多数情况下,查询被截断时,会被计数两次。

当您有许多小日志文件和许多 CPU 时,一次将一个 CPU 核心专用于一个日志文件会更快。若要启用此行为,必须改用选项 -J N。有 200 个日志文件,每个日志文件 10MB,有 8 个 CPU 核心,使用 -J 选项就会变得有意义。使用此方法,您将确保不会丢失报告中的任何查询。

这是在一个有 8 个 CPU 和单个 9.5GB 文件的服务器上完成的基准测试。

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

有 200 个日志文件,每个日志文件 10MB,因此总共 2GB,结果会略有不同:

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

因此,建议使用 -j,除非您有数百个小日志文件,并且至少可以使用 8 个 CPU 核心。

重要:当您进行并行解析时,pgBadger 会在 /tmp 目录中生成大量临时文件,并在最后删除它们,因此除非 pgBadger 未运行,否则不要删除这些文件。它们都使用模板tmp_pgbadgerXXXX.bin命名,因此可以轻松识别。

增量报告

pgBadger 包括了一个使用选项 -I 或 --incremental 的自动增量报告模式。在此模式下运行时,pgBadger 会每天生成一份报告,每周生成一份累积报告。输出首先以二进制格式写入到强制输出目录中(请参阅选项 -O 或 --outdir),然后以 HTML 格式生成带有主索引文件的每日和每周报告。

主索引文件会按周显示一个下拉菜单,其中包含了一个指向每周报告的链接,以及指向每周里面每日报告的链接。

例如,如果基于每日轮换的文件,按如下方式运行 pgBadger:

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

您将拥有整个运行期间的所有每日和每周报告。

在这种模式下,pgBadger 会在输出目录中创建一个自动增量文件,因此除非您想更改该文件的路径,否则您不必使用 -l 选项。这意味着您可以每天在每周轮换的日志文件上以此模式运行 pgBadger,并且它不会计算日志记录两次。

为了节省磁盘空间,您可能需要使用 -X 或 --extra-files 命令行选项,来强制让 pgBadger 将 JavaScript 和 CSS 数据写入到输出目录中的单独文件。然后,将使用脚本和链接标记加载资源。

重新生成报告

在修复一个 pgbadger 报告,或使用新特性更新所有 HTML 报告后,可以重新生成增量报告。要重新生成还存在二进制文件的所有报告,请按以下步骤操作:

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

它还会更新所有资源文件(JS 和 CSS)。如果报告是使用 -E 或 --explode 选项生成的,请带上它们。

月度报告

默认情况下,增量模式下的 pgBadger 仅计算每日和每周报告。如果需要每月累积报告,则必须使用单独的命令来指定要生成的报告。 例如,要生成 2019 年 8 月的报告,请执行以下操作:

pgbadger -X --month-report 2019-08 /var/www/pg_reports/

这会将一个月份名称的链接添加到增量报表的日历视图中,以查看月度报表。当月的报告可以每天运行,每次都会完全重新生成。默认情况下不会生成月度报告,因为处理的数据量大,可能需要花费大量时间。

如果报告是使用按数据库的选项( -E | --explode )构建的,则在调用 pgbadger 构建月度报告时也必须带上它们:

pgbadger -E -X --month-report 2019-08 /var/www/pg_reports/

使用重新构建选项( -R | --rebuild )时,也与此相同。

二进制格式

使用二进制格式,可以创建自定义的增量和累积报告。例如,如果要每小时从一个每日 PostgreSQL 日志文件,刷新一份 pgBadger 报告,则可以每小时运行以下命令:

pgbadger --last-parsed .pgbadger_last_state_file -o sunday/hourX.bin /var/log/pgsql/postgresql-Sun.log

以二进制格式生成增量数据文件。要从该二进制文件生成新的 HTML 报告,请执行以下操作:

pgbadger sunday/*.bin

或者,再举一个例子,如果每小时生成一个日志文件,并且希望在每次轮换日志文件时重新生成报告,请按以下步骤操作:

pgbadger -o day1/hour01.bin /var/log/pgsql/pglog/postgresql-2012-03-23_10.log
pgbadger -o day1/hour02.bin /var/log/pgsql/pglog/postgresql-2012-03-23_11.log
pgbadger -o day1/hour03.bin /var/log/pgsql/pglog/postgresql-2012-03-23_12.log
...

例如,当您要刷新 HTML 报告时,每次生成一个新的二进制文件后,只需执行以下操作:

pgbadger -o day1_report.html day1/*.bin

可适当调整命令以满足您的特定需求。

JSON 格式

JSON 格式非常适合与其他语言共享数据,这使得将 pgBadger 结果集成到其他监控工具(如 Cacti 或 Graphite)中变得很容易。