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.