pgBadger 13.2 Documentation

• 1: Download and Installation
• 2: Command-Line Reference
• 3: PostgreSQL Logging Configuration
• 4: Parallel Processing
• 5: Incremental Reports
• 6: Output Formats
• 7: Sample Reports
• 8: Release History
  • 8.1: pgBadger 13.x Release Notes
  • 8.2: pgBadger 12.x Release Notes
  • 8.3: pgBadger 11.x Release Notes
  • 8.4: pgBadger 10.x Release Notes
  • 8.5: pgBadger 9.x Release Notes
• 9: Support and Contributing
• 10: License and Credits

1 - Download and Installation

Sources: official download section and the pinned upstream README.md.

Choose a distribution channel

The documentation snapshot in this site is based on the 13.2 source tree. Always check the release page before downloading: the local snapshot is intentionally fixed, while upstream releases continue to change.

Requirements

The HTML report path needs only:

• a modern Perl distribution;
• a web browser to render the embedded JavaScript charts.

Optional capabilities add the following dependencies:

Install JSON support on Debian or Ubuntu:

$ sudo apt-get install libjson-xs-perl

On an RPM-based system:

$ sudo yum install perl-JSON-XS

Use --zcat to override a decompressor path. Supplying one custom command disables mixing different compressed formats in the same invocation.

Install from an official tarball

Download a release archive, then build and install it with Perl’s standard toolchain:

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

The default site layout installs the program as /usr/local/bin/pgbadger and the manual page as /usr/local/share/man/man1/pgbadger.1.

For a distribution-style installation under /usr, generate the Makefile with:

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

INSTALLDIRS=perl is another upstream-supported layout. Inspect the generated paths before installing into a managed system.

Install development code

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

Development code may contain changes not yet covered by a release note. Prefer a tagged archive for reproducible production packaging.

Verify the installation

$ pgbadger --version
$ pgbadger --help

Continue with the command-line reference and PostgreSQL logging configuration.

2 - Command-Line Reference

This page preserves the command reference generated from the pinned upstream source. Option names and help text remain verbatim so they can be compared directly with pgbadger --help.

Source: pgBadger README.md at commit a1ad95a.

Usage and options

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 Logging Configuration

Source: pinned upstream README.md, sections “PostgreSQL Configuration” and “Log Statements”.

pgBadger can only report information that PostgreSQL writes to the log. Start with a parseable prefix and a deliberate statement-logging policy, then add the operational events you want to analyze.

Minimum query logging

To include query text and duration, enable duration-based statement logging:

log_min_duration_statement = 0

0 logs every completed statement. On a busy server, choose a higher threshold in milliseconds to control log volume. Measure the overhead and storage growth before enabling a low threshold in production.

If you only need duration and query counts, not the query text, use:

log_min_duration_statement = -1
log_duration = on

Prefer log_min_duration_statement when you need the slowest-query and total-query-time reports.

Required prefix fields

A custom log_line_prefix must include both:

• a time field: %t, %m, or %n;
• a process or session field: %p or %c.

A minimal stderr prefix is:

log_line_prefix = '%t [%p]: '

A more useful prefix records user, database, application, and client:

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

The equivalent prefix for a syslog destination omits the timestamp and process fields already supplied by syslog:

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

Another supported key order is:

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

When your prefix is not one of pgBadger’s recognized forms, pass the exact value with --prefix. Do not simplify or retype it differently from postgresql.conf.

Recommended event settings

Enable the event classes you want to appear in the report:

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

These settings can produce substantial log traffic. In particular, log_temp_files = 0 and log_autovacuum_min_duration = 0 log every qualifying event; adjust them to match the workload and retention budget.

Keep server messages in English

The parser recognizes PostgreSQL server messages in English. Use either:

lc_messages = 'en_US.UTF-8'

or:

lc_messages = 'C'

Locales such as fr_FR.UTF-8 are not supported by the upstream parser.

Avoid conflicting statement settings

Do not enable log_min_duration_statement, log_duration, and log_statement = 'all' together. The same execution can be logged more than once, which inflates pgBadger counters and greatly increases log volume.

After reloading PostgreSQL, inspect several real log entries before running a large analysis. Verify that the timestamp, process/session identifier, user, database, application, and client fields match the selected format.

4 - Parallel Processing

Source: pinned upstream README.md, section “Parallel Processing”.

pgBadger has two complementary multiprocessing modes. Choose according to the shape of the input, not simply the number of CPUs.

Split one large file with -j

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

The upstream algorithm divides each file into N byte ranges, forks one parser per range, writes temporary binary statistics, then merges those statistics into the final report.

for each log file
    divide the file into N chunks
    find each chunk's start and end offsets
    fork N parsers at those offsets
    write one temporary binary statistics file per parser
wait for the workers
merge the binary files and build the report

Because log records and multi-line statements do not align perfectly with byte offsets, up to roughly N queries per file may be truncated, omitted, or—more commonly—counted twice at chunk boundaries. Use this mode for aggregate analysis of very large files, not for a workflow that requires an exact forensic count of every record.

Process many files with -J

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

Each worker owns a complete file, so this mode avoids the chunk-boundary gap. It becomes most useful with hundreds of small files and enough CPU and I/O capacity. The upstream documentation also permits -J for independent compressed files; single-file chunking with -j requires seekable, uncompressed input.

Upstream benchmark

The upstream manual reports these measurements on an 8-CPU host. Treat them as a comparison of the two algorithms, not as a prediction for current hardware.

One 9.5 GB file:

Two hundred 10 MB files, 2 GB total:

The practical default is -j for a few large files and -J for many small files. Both modes can be combined when the input and platform support it, but benchmark the combination: log parsing may become limited by storage throughput before CPU.

Limits and temporary files

• -j is not available for compressed or CSV input and relies on process forking, so it is not a Windows mode.
• Remote CSV parsing is not supported by the upstream remote-input path.
• Parallel analysis creates temporary files named like tmp_pgbadgerXXXX.bin under the selected temporary directory (by default the system temporary directory).
• Do not clean those files while pgBadger is running. Use --tempdir to place them on storage with sufficient capacity.
• Start with a modest worker count and watch CPU, read throughput, temporary-space consumption, and elapsed time.

5 - Incremental Reports

Source: pinned upstream README.md, section “Incremental Reports”.

Incremental mode stores parsed statistics in binary form, then builds one HTML report per day, a cumulative report per week, and a calendar-style index linking them together. It is intended for repeated processing of rotated logs without counting the same entries again.

Build daily and weekly reports

Run pgBadger after the daily log rotation and provide a persistent output directory:

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

-I enables incremental mode and -O selects the directory that holds the binary state, calendar index, and generated reports. pgBadger maintains its own incremental state in that directory, so --last-parsed is unnecessary unless you deliberately want the state file elsewhere.

Use a separate HTML directory while retaining binary state in the original directory:

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

Treat the binary files as source data for future rebuilds. Back them up or retain the original logs if report regeneration matters.

Retention

Keep only a chosen number of weeks:

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

Older week and day directories are removed automatically. Test the policy on a non-production copy before enabling it around your only report history.

Write shared assets separately

By default, HTML reports embed their JavaScript and CSS. In a directory containing many incremental reports, -X / --extra-files writes shared assets separately and reduces duplicated output:

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

All reports and their versioned resource directory must be moved together.

Rebuild existing reports

After upgrading pgBadger or applying a report-generation fix, rebuild HTML from retained binary data:

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

Use -E / --explode again if the original reports were generated per database.

Use the long option --rebuild. In the current command reference, -R means --retention; treating -R as a rebuild shortcut would apply the wrong option.

Add a monthly report

Daily and weekly reports are automatic. Monthly aggregation is explicit because it may be expensive for a large history:

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

The generated month is added to the calendar index. Re-running the command rebuilds that month from the available binary data. For per-database history, repeat -E:

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

The complete command reference also provides --day-report YYYY-MM-DD, --no-week, --noreport, --start-monday, and --iso-week-number for more specialized schedules.

Open the bundled incremental-report example to inspect the calendar, week links, and daily-report hierarchy without a network connection.

6 - Output Formats

Source: pinned upstream README.md, sections “Binary Format” and “JSON Format”, plus the generated command reference.

pgBadger selects output from the filename extension or from -x / --extension. Use -o / --outfile more than once to create multiple formats from the same parse.

HTML and text

The default output is out.html:

$ pgbadger postgresql.log -o report.html

HTML normally embeds the scripts, styles, fonts, and report data needed for standalone viewing. -X / --extra-files moves shared JavaScript and CSS out of incremental reports; keep those assets beside the HTML tree.

Generate text explicitly:

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

Use - as the output filename to write a supported format to standard output.

Binary intermediate data

Binary output separates parsing from presentation. Generate hourly increments from one growing daily log:

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

Merge one or more binary files into a fresh report:

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

When the server writes one log file per hour, create one binary file for each rotation, then rebuild the cumulative HTML whenever required:

$ 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

Keep binary files from compatible pgBadger versions together. Read the release notes for incremental-format compatibility before upgrading a long-lived report directory.

JSON

JSON output is intended for programmatic consumers such as monitoring or reporting pipelines:

$ pgbadger -o report.json postgresql.log

Install JSON::XS first. Add --prettify-json for readability when file size and generation time are secondary.

Raw and query-oriented exports

The command reference also provides specialized exports:

• --dump-raw-csv parses the log and writes row-oriented CSV without building a report;
• --csv-separator changes the raw CSV delimiter;
• --dump-all-queries emits every query after replacing bind parameters;
• --normalized-only writes normalized queries;
• --query-numbering numbers query-oriented text output.

These modes may contain application SQL, identifiers, users, client addresses, or literal values. Review the output before sharing it and use --anonymize when the intended analysis does not require literals.

7 - Sample Reports

Source: the three examples linked from the official pgBadger website, downloaded on 2026-08-15. The example content itself was generated by pgBadger 11.8 in May 2022.

The original examples are stored with this site, so report navigation, charts, styles, and scripts remain available without reaching the upstream server.

Complete report

The complete report is a self-contained HTML document. Use its top navigation to inspect global statistics, queries, sessions, connections, temporary files, checkpoints, autovacuum activity, locks, and PgBouncer-specific charts.

The data is a demonstration fixture, not a current benchmark. Values, PostgreSQL versions, and the embedded pgBadger UI reflect the report generation date.

Incremental hierarchy

The incremental example preserves the full link structure:

report/
├── index.html
├── 2012/
│   ├── week-49/index.html
│   ├── week-50/index.html
│   └── 12/06 … 12/index.html
└── 11/
    ├── pgbadger.min.css
    ├── pgbadger.min.js
    └── bundled chart and UI assets

The top index links to two weekly reports and seven daily reports. All relative links were retained, so moving only index.html would break the example; keep the complete directory tree together.

Security and privacy

Real reports may expose SQL text, bind values, database and user names, application names, client addresses, error details, and workload patterns. Before publishing a report:

• use --anonymize when literals are not needed;
• apply include/exclude filters before report generation;
• inspect the final HTML or exported data, not only the command line;
• protect the report location with the same care as operational logs.

8 - Release History

The official website publishes release news inline on its home page. That page stops at 12.4 and accidentally repeats 11.1–11.3 with conflicting dates. This edition uses the pinned upstream ChangeLog as the canonical record, removes only those duplicate renderings, and adds the later 13.x releases.

Canonical source: ChangeLog at commit a1ad95a. Entries are preserved in full and ordered newest first within each series.

For downloadable archives and assets, use GitHub Releases. Release dates in this section describe upstream source history; they are not the download time of this documentation snapshot.

8.1 - pgBadger 13.x Release Notes

These entries preserve the complete upstream change record for pgBadger 13.x, newest first.

Source: upstream ChangeLog at commit a1ad95a.

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 Release Notes

These entries preserve the complete upstream change record for pgBadger 12.x, newest first.

Source: upstream ChangeLog at commit a1ad95a.

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 Release Notes

These entries preserve the complete upstream change record for pgBadger 11.x, newest first.

Source: upstream ChangeLog at commit a1ad95a.

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 Release Notes

These entries preserve the complete upstream change record for pgBadger 10.x, newest first.

Source: upstream ChangeLog at commit a1ad95a.

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 Release Notes

These entries preserve the complete upstream change record for pgBadger 9.x, newest first.

Source: upstream ChangeLog at commit a1ad95a.

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 - Support and Contributing

Sources: official support section and upstream CONTRIBUTING.md.

pgBadger is maintained as an open project. Bug reports, feature proposals, documentation fixes, and patches are handled through the upstream GitHub repository.

Bugs and feature requests

1. Upgrade to the newest released version and confirm the behavior still occurs.
2. Search open issues and closed issues for an existing answer.
3. Reduce the problem to the smallest safe log sample and command line that still reproduces it.
4. Remove credentials, sensitive SQL, bind values, host names, addresses, and business data.
5. Open a new issue with the pgBadger version, operating system, input format, exact options, observed result, and expected result.

For crashes or parser mistakes, include only the minimum sanitized log lines needed to reproduce the boundary. A complete production log or generated report is rarely appropriate for a public issue.

Contribute a patch

The project includes an .editorconfig file for consistent spacing. Keep command help, POD, and generated Markdown documentation aligned when a change affects user-visible behavior.

The upstream documentation workflow is:

$ perl Makefile.PL
$ make README

doc/pgBadger.pod is the primary long-form source. pgbadger --help supplies the synopsis, while the README files are generated views. Run the relevant tests before submitting a pull request.

• Source repository
• Pull requests
• Contribution guide
• Development notes

Commercial support

The pgBadger project does not promise maintenance or support under its license. For paid help with PostgreSQL logging, performance analysis, or report automation, consult the PostgreSQL professional services directory.

10 - License and Credits

Source: upstream LICENSE, README.md, and resources/LICENSE at the pinned source commit.

pgBadger is free and open-source software distributed under the PostgreSQL License. It may be used, copied, modified, and distributed without a fee, subject to retaining the copyright and license notices.

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.

Authors and design credits

• pgBadger is an original work by Gilles Darold.
• The pgBadger logo is an original creation by Damien Cazeils.
• The pgBadger v4.x design came from the “Art is code” company.
• The website is a work of Gilles Darold.
• Contributors are credited throughout the upstream ChangeLog.

Embedded and report resources

A modified version of the SQL::Beautify Perl module is embedded in pgBadger. It is copyright © 2009 Jonas Kramer and published under the Artistic License 2.0.

Generated-report resources have their own notices, including:

The local source snapshot retains the complete upstream resources/LICENSE. The bundled example reports are historical generated artifacts and retain their original embedded notices and resource versions.

Documentation snapshot

This pgsql.cc edition reorganizes the upstream documentation into Hugo pages, adds navigation and Chinese reading aids, and preserves exact command help and ChangeLog text where fidelity matters. The pgBadger source documentation remains under the PostgreSQL License; original project names, authorship, and upstream links are retained.