pgMonitor bundles exporters, Prometheus, Grafana and alerting for one cluster

An assembly of well known components, not one program

The README describes pgMonitor as your all-in-one tool to easily create an environment to visualize the health and performance of your PostgreSQL cluster, and the key phrase is a suite of tools. The repository layout makes that concrete. The top level directories are `alertmanager/`, `blackbox_exporter/`, `build/`, `changelogs/`, `grafana/`, `hugo/`, `node_exporter/`, `pgbadger/`, `postgres_exporter/`, `prometheus/`, `release/` and `sql_exporter/`.

Read that list and the design becomes clear. This is not a monitoring application with its own agent. It is a curated collection of upstream projects, each in its own directory: a PostgreSQL metrics exporter, a host metrics exporter, a blackbox prober, a SQL exporter, a Prometheus server, Grafana for visualisation, Alertmanager for alerting, and pgBadger for log analysis. The `hugo/` directory is the documentation site, `build/` and `release/` are the packaging machinery, and `changelogs/` holds per component release notes.

The primary language of the repository is PLpgSQL, which points at where the custom work sits: SQL that runs inside the database to collect the metrics that the standard exporter does not gather on its own.

For a reader deciding whether to use this, that composition is the whole story. You are not adopting a product, you are adopting an arrangement.

Six metrics the README names, and why each one matters

The README lists what the suite collects, and each item is phrased as an operational question rather than a technical one.

Connection counts answer how busy is your system being accessed and if connections are hanging. Database size answers how much disk your cluster is using. Replication lag answers whether your replicas are falling behind in loading data from your primary. Transaction wraparound is framed as a rule rather than a question, don't let your PostgreSQL database stop working. Bloat is about how much extra space your tables and indexes are using. System metrics cover CPU, memory, I/O and uptime.

That framing is a clue about the design. Wraparound and bloat are the two that end in an incident rather than a question, and they are the two that cannot be read off a standard host exporter. A monitoring environment that only reports CPU and disk gives you a dashboard; one that tracks wraparound distance and bloat gives you warning before the cluster stops.

The README is also clear that the list is a starting point rather than a ceiling. It says pgMonitor is highly configurable, and that advanced users can design their own metrics, visualizations, and add in other features such as alerting. The custom metrics are where the PLpgSQL in the repository earns its place.

Configurability cuts both ways

The configurability claim deserves a second look, because it is both the reason to adopt the project and the reason it takes longer to become useful.

On one side, a monitoring stack assembled by hand tends to stall at the first awkward metric. Someone wants replication lag in seconds rather than bytes, or wants a chart that compares bloat across schemas, and the work expands into writing queries, wiring them into an exporter, and rebuilding dashboards. A pre-arranged environment with editable configuration files gives you that head start.

On the other side, every layer in this stack has its own configuration and its own upgrade path. `postgres_exporter/`, `node_exporter/`, `prometheus/`, `grafana/` and `alertmanager/` are separate components with separate releases, and the `changelogs/` directory at the top level is a reminder that a version matrix exists. The `build/` and `release/` directories exist precisely because producing a consistent set of these components is the hard part, and the `CHANGELOG.rst` at the root records what changed between the tagged versions.

So the value is a working arrangement rather than new code, and the cost of adopting it is the obligation to keep that arrangement working as the components move.

The README sends you to the documentation site

There is no installation command anywhere in this README, and that is not an omission to be annoyed about. The repository points to the official Crunchy Data pgMonitor documentation at access.crunchydata.com, under documentation for pgmonitor latest, and separately links the contributing guidelines for anyone who wants to update the documentation itself. The `hugo/` directory in the repository is the source for that site.

Two things follow for an adopter. First, the operational detail, how to install the components, how to point the exporter at your cluster, how to import the dashboards and how to wire the alerting rules, is documented outside the repository, and following it is the only supported route to a working environment. Second, because the docs are versioned as latest, the version you read may be ahead of the tag you install, and the repository's own convention of keeping `changelogs/` per component is the way to check what actually changed.

The repository also carries the smaller signals of a maintained project: a `.pre-commit-config.yaml` for pre-commit checks, a `.commitlintrc.yml` for commit message rules, a `.gitmodules` file, which indicates that some content is pulled in as submodules, and a `CHANGELOG.rst` at the root. The default branch is `development`, and the tags are v5.3.0 from 2025-07-10, v5.2.1 from 2025-04-21 and v5.2.0 from 2025-03-27.

Licence, warranty wording and trademarks

The repository metadata classifies the licence as one GitHub cannot categorise, and the terms live in the LICENSE file at the root, so read that file rather than assuming a standard open source licence. The README also carries a legal notices section, and it is worth reading closely because it says something specific: Crunchy Data Solutions, Inc. provides this guide as is without warranty of any kind, either express or implied, including the implied warranties of non infringement, merchantability and fitness for a particular purpose. That disclaimer is attached to the guide, and the README additionally states that Crunchy, Crunchy Data Solutions, Inc. and the Crunchy Hippo Logo are trademarks of Crunchy Data Solutions, Inc.

The copyright lines have changed shape recently, which tells you the project has moved between owners: copyright 2017 to 2025 for Crunchy Data Solutions, Inc. and copyright 2025 to 2026 for Snowflake, Inc. If you are evaluating the project for commercial use, those two facts, the custom licence classification and the trademark notice, are the ones to check with your legal team rather than reading a licence identifier off the repository page.

The sponsorship section is also informative about the shape of the project. Crunchy Data sponsors pgMonitor along with many other open source projects to support the PostgreSQL community and the software ecosystem, which is a reasonable signal that the arrangement is maintained by people who work with PostgreSQL clusters for a living, though it is not a guarantee about your specific environment.

Cluster visibility, not query level answers

The clearest case for not choosing pgMonitor is a workload where the question is not about the cluster but about the queries. The metrics the README lists are cluster and host level: connections, size, replication, wraparound, bloat, and system resource usage. A dashboard that shows those answers whether your slow statement is a missing index or a bad query plan, and pgMonitor does not claim to.

The log analysis component, pgBadger, sits in the stack for that reason, and understanding the split tells you where the real work is. A request level view of what the database actually did is a separate exercise from a picture of how the instance is behaving, and the second is what this suite is built to give you.

The second wrong-tool case is scale. A single small database that someone wants to keep an eye on does not need Prometheus, Grafana, Alertmanager and a set of exporters. Two or three queries against the PostgreSQL system views, or the host's own monitoring, would answer the same questions with nothing to operate. The stack pays off when there are several clusters, several environments, and someone whose job it is to notice a wraparound warning before the database stops working, which is the situation the README's wording is written for.

Editorial conclusion

Adopt pgMonitor when you want a ready-made PostgreSQL monitoring environment rather than a hand assembled set of exporters, and when you can give it the maintenance attention a multi component stack needs. Do not adopt it for a single small database where a couple of queries against the system views would do, and do not expect per query analysis from it, since that belongs to the log analysis component. Verify first that the documentation for the version you install matches the tag you take, that the metric definitions in the configuration match what your queries need, and that you are comfortable with the release gap, since the last push was on 2026-04-23 while the newest tag, v5.3.0, dates from 2025-07-10.

Frequently asked questions

Official sources

1. CrunchyData/pgmonitor on GitHub
2. Issues
3. README
4. Releases