pg_stat_monitor buckets PostgreSQL query statistics by time

A replacement for pg_stat_statements, not a companion to it

pg_stat_monitor is a query performance monitoring tool for PostgreSQL, and the README is clear about its relationship to the extension most people already run. It is developed on the basis of pg_stat_statements as its more advanced replacement.

That word replacement is the design statement. pg_stat_statements keeps ever-increasing counts, so the questions it answers are cumulative: which query is the most expensive in total, over the life of the database since the statistics were reset. pg_stat_monitor aggregates the collected data into configurable time based units, called buckets, and the README gives the reason: this allows focusing on statistics generated for shorter time periods and makes query timing information such as max, min and mean time more accurate.

The accuracy point is the subtle one. A mean execution time computed over every query the server has ever seen is dominated by the bulk of the workload, so a spike in a narrow window barely moves it. The same mean computed over one bucket reflects what was happening in that window. If you are trying to correlate a slowdown with a deploy, a batch job or an incident window, buckets are the feature that makes the data answer the question.

The rest of the value proposition is coverage. The README says it provides improved insights that allow database users to understand query origins, execution, planning statistics and details, query information and metadata, and that it aggregates the collected data so users do not have to do it themselves. The goal is a more holistic picture in a single view rather than several views you have to join.

The feature list is cut off, but the design is clear

The features section in the README is truncated, but what survives of it is enough to characterise the tool.

The first feature is time interval grouping. Instead of supplying one set of ever-increasing counts, pg_stat_monitor computes stats for a configured number of time intervals, the time buckets. The stated benefit is that performance issues and patterns can be identified based on time and workload, and the framing of the whole feature list is that it simplifies query observability by providing a more holistic view of a query from performance, application and analysis perspectives.

The second thing to know is a caveat the README puts in a callout of its own. Because of the differences in data processing, memory blocks and WAL related statistics data are displayed inconsistently when both pg_stat_monitor and pg_stat_statements are used together. That is a real operational warning: the two extensions do not compose cleanly for those particular statistics, and an operator who installs both will see numbers that do not agree.

Whether to keep pg_stat_statements alongside is therefore a decision rather than a default, and the sensible reading is that you should not expect the two to agree about memory block or WAL figures, and should decide which one is your source of truth for those.

The documentation for the full feature set lives outside the repository, in the Percona user guide and reference pages linked from the README, with the homepage for the project being the documentation site.

Supported versions, and where the packages come from

pg_stat_monitor supports PostgreSQL versions 14 and above, and it is compatible with both the PostgreSQL provided by the PostgreSQL Global Development Group and with Percona Distribution for PostgreSQL.

The tested matrix is narrower than the stated support, and the README is honest about it. The extension should work on the latest version of both Percona Distribution and PostgreSQL, but it is only tested with PostgreSQL 14, 15, 16, 17 and 18 on both providers. The table in the README lists the Percona Distribution versions with Percona as the provider, and the plain PostgreSQL versions with PGDG as the provider.

Packaging is thorough, which is where a Percona project earns its keep. RPM packages for RHEL and CentOS and DEB packages for Debian and Ubuntu are available from the Percona repositories for PostgreSQL 14, 15, 16, 17 and 18, and the RPM packages are also available in the official PostgreSQL PGDG yum repositories. The README also lists an installation route through PGXN, and a route for building from sources.

The build badges at the top of the README reflect the matrix, with one package workflow per PostgreSQL major version from 14 to 18, and the README points at the releases page for the latest stable releases.

For a team running a version that is not in that list, the extension may still work, since the support statement is version 14 and above, but you are outside what the project tests.

Building it from source, and the SQL upgrade chain

The repository is a PostgreSQL extension written in C, with the SQL side and the packaging alongside it, and the Makefile shows the standard PGXS layout.

MODULE_big = pg_stat_monitor
PG_CONFIG ?= pg_config
PGXS := $(shell $(PG_CONFIG) --pgxs)
include $(PGXS)

So the build is driven by pg_config from an installed PostgreSQL, and the extension name and the objects built are declared at the top. There is also a meson.build file, so a Meson based build is available alongside the classic one.

The DATA list is the interesting part, because it is the extension's schema history laid out in full. There is a base install script, pg_stat_monitor--2.0.sql, a second one at pg_stat_monitor--2.1.sql, and a chain of upgrade scripts: 1.0 to 2.0, 2.0 to 2.1, 2.1 to 2.2, 2.2 to 2.3 and 2.3 to 2.4. PostgreSQL walks that chain when the extension is upgraded, so an installation can be moved from any earlier version to the current one without a manual step.

The regression test list is the other thing worth reading, because it is a map of the feature surface. There are about thirty-seven test files, and their names cover the GUCs, the query id handling, the counters, the relations and database level views, the top query and parent query tracking, the command type breakdown, error handling, row counts, squashing, tags, user level tracking, security definer functions, rollback behaviour, level tracking and error level decoding, parallel query, select and dml and utility statements, cursors, planning statistics, WAL statistics, privileges, the plan cache and histograms. TAP_TESTS is enabled as well, so the extension runs under the TAP test harness as well as the standard regression suite.

Packaging artefacts and project hygiene

The repository carries packaging inputs for three different channels, which is more than most extension repositories do.

There is a debian directory and an rpm directory, so the DEB and RPM packages are built from this tree, and a percona-packaging directory for the Percona distribution channel. There is a META.json file, which is the metadata format used by the PGXN packaging system, and the README carries a PGXN version badge, so the extension is distributed through that channel as well. The scripts directory holds the packaging and build helper scripts, and the suppressions directory holds the suppression list used when running static analysis, which is the usual way to keep a lint tool quiet about code it cannot understand without giving up on it entirely.

The project hygiene files are visible too. There is a .licenserc.yaml, which configures a licence header check, a SECURITY.md for reporting a vulnerability, a code-of-conduct.md, a CONTRIBUTING.md and a CHANGELOG.md. The README carries an OpenSSF Scorecard badge and an OpenSSF Best Practices badge, both of which measure the repository's own supply chain hygiene, plus a codecov coverage badge and a link to the Percona forums.

The t directory is the TAP test output location, and the regression directory holds the SQL regression fixtures that the test list above drives.

The licence is recorded as a custom one that GitHub cannot classify, which for a Percona project is the standard shape of a dual licensing arrangement, so read the LICENSE file rather than assuming which terms apply to your use.

Maintenance, and the two questions to ask before installing

The release record shows a project with a regular cadence. The published versions are 2.4.0 on 2026-09-08, 2.3.2 on 2026-05-11 and 2.3.1 on 2025-11-28, and the last push was on 2026-10-19. The repository is not archived.

Two questions are worth asking before you install it on a production server.

The first is the interaction with pg_stat_statements, and it is the callout the README puts in the overview rather than in a compatibility note. Memory block and WAL statistics are displayed inconsistently when both extensions run, so if your dashboards currently read from pg_stat_statements, adding pg_stat_monitor means deciding which extension those dashboards read from, and checking the memory and WAL numbers rather than assuming they carry over.

The second is the version. Support is stated as PostgreSQL 14 and above, but the tested list stops at 18. PostgreSQL ships a new major version every year, so the gap between the newest tested major and the newest released major is a timing question, and a team running the very latest server is running a combination the project has not yet exercised.

There is a smaller operational point that the extension's own design implies. Because it stores statistics in buckets, it needs a configuration, and the repository includes pg_stat_monitor.conf as the configuration file that the test suite runs against, with the REGRESS_OPTS pointing the test configuration at it. The bucket size and retention are decisions you make at install time, and they determine both how useful the time window is and how much the extension stores.

One curiosity about the repository metadata: the primary language is recorded as Perl, even though the extension itself is C with SQL, which reflects the language distribution the tooling detected rather than the code you would be reading.

Editorial conclusion

pg_stat_monitor fits a database team that needs to correlate query behaviour with a time window, such as a deploy or an incident, and it does not fit a team that only wants cumulative counters, because it is a superset of that and carries the same overhead plus bucket configuration. Before you install it, read the note about running it alongside pg_stat_statements, since memory block and WAL statistics are displayed inconsistently when both are enabled, and check that your PostgreSQL major version is one of the tested ones. The extension is packaged as DEB and RPM for PostgreSQL 14 to 18, version 2.4.0 was released on 2026-09-08, and the last push was on 2026-10-19.

Frequently asked questions

Official sources

1. Issues
2. percona/pg_stat_monitor on GitHub
3. Project website
4. README
5. Releases