The highest tagged major version is
README
¶
pgwatch: PostgreSQL monitoring solution
Overview
pgwatch is a scalable and flexible PostgreSQL-specific monitoring solution that offers a comprehensive view of database performance and health. It provides a user-friendly interface through Grafana dashboards, allowing users to easily inspect various metrics and trends.
Visit demo.pgwatch.com for a Grafana demo, and pgwat.ch for full documentation.
Quick Start
To fetch and run the latest demo Docker image, exposing
- Grafana on port 3000,
- the administrative web UI on port 8080,
- the internal configuration and metrics database on port 5432:
docker run --detach --name pgwatch-demo \
-p 5432:5432 -p 3000:3000 -p 8080:8080 -e PW_TESTDB=true \
cybertecpostgresql/pgwatch-demo
After a few minutes, you can open the "Database Overview" dashboard and start looking at the metrics. To define your own dashboards, you need to log in to Grafana as admin (admin/pgwatchadmin).
If you don't want to add the test database for monitoring, remove the PW_TESTDB parameter when launching the container.
Development and production use
For production and long-term installation cybertecpostgresql/pgwatch Docker image should be used.
For the fastest development and deployment experience, the Docker compose files are provided.
-
The usual production setup should involve:
git clone https://github.com/cybertec-postgresql/pgwatch.git && cd pgwatch git checkout v5.0.0 # or any other version you want to use docker compose -f ./docker/docker-compose.yml up --detach -
For development purposes, you want to build the image from source:
git clone https://github.com/cybertec-postgresql/pgwatch.git && cd pgwatch docker compose -f ./docker/docker-compose.yml build docker compose -f ./docker/docker-compose.yml up --detach task demo:init
These commands will build and start services listed in the compose file:
- configuration and metric database;
- pgwatch monitoring agent with WebUI;
- Grafana with dashboards.
✔ Network pgwatch_default Created
✔ Container pgwatch-postgres-1 Healthy
✔ Container pgwatch-pgwatch-1 Started
✔ Container pgwatch-grafana-1 Started
Monitor Database
After starting, you could open the monitoring dashboard and start looking at metrics.
To add a test database to monitoring, you can use the built-in WebUI.
Produce Workload
To emulate workload for the added test database, execute:
task demo:bench
dropping old tables...
creating tables...
generating data (client-side)...
vacuuming...
creating primary keys...
done in 9.46 s (drop tables 0.11 s, create tables 0.01 s, client-side generate 6.95 s, vacuum 0.26 s, primary keys 2.13 s).
pgbench (17.2 (Debian 17.2-1.pgdg120+1))
starting vacuum...end.
progress: 5.0 s, 1551.3 tps, lat 3.805 ms stddev 11.169, 0 failed
progress: 10.0 s, 307.5 tps, lat 45.560 ms stddev 380.998, 0 failed
progress: 15.0 s, 2579.0 tps, lat 3.865 ms stddev 2.611, 0 failed
progress: 20.0 s, 1974.9 tps, lat 5.038 ms stddev 4.808, 0 failed
progress: 25.0 s, 1414.9 tps, lat 7.048 ms stddev 5.124, 0 failed
progress: 30.0 s, 1643.0 tps, lat 6.056 ms stddev 4.395, 0 failed
progress: 35.0 s, 947.4 tps, lat 10.423 ms stddev 34.786, 0 failed
progress: 40.0 s, 1832.3 tps, lat 5.485 ms stddev 4.438, 0 failed
progress: 45.0 s, 1541.0 tps, lat 6.456 ms stddev 4.135, 0 failed
progress: 50.0 s, 2017.3 tps, lat 4.938 ms stddev 3.316, 0 failed
progress: 55.0 s, 1730.3 tps, lat 5.751 ms stddev 4.706, 0 failed
progress: 60.0 s, 1363.6 tps, lat 7.302 ms stddev 32.543, 0 failed
transaction type: <builtin: TPC-B (sort of)>
scaling factor: 50
query mode: simple
number of clients: 10
number of threads: 2
maximum number of tries: 1
number of transactions per client: 10000
number of transactions actually processed: 100000/100000
number of failed transactions: 0 (0.000%)
latency average = 6.253 ms
latency stddev = 49.094 ms
initial connection time = 15.263 ms
tps = 1567.619330 (without initial connection time)
dropping old tables...
done in 0.11 s (drop tables 0.11 s).
Inspect database
[!IMPORTANT] pgAdmin uses port 80. If you want it to use another port, change it in
docker/compose.pgadmin.ymlfile.
To look at what is inside the pgwatch database, you can spin up pgAdmin4:
docker compose -f ./docker/docker-compose.yml up --detach pgadmin
Go to localhost in your favorite browser and log in as admin@local.com, password admin.
Server pgwatch should already be added to the Servers group.
Development
If you apply any changes to the source code and want to restart the agent, it's usually enough to run:
docker compose -f ./docker/docker-compose.yml up pgwatch --build --force-recreate --detach
The command above will rebuild the pgwatch agent from source and relaunch the container.
Logs
If you are running containers in detached mode, you can still follow the logs:
docker compose -f ./docker/docker-compose.yml logs --follow
Or you may check the log of a particular service:
docker compose -f ./docker/docker-compose.yml logs pgwatch --follow
Contributing
Feedback, suggestions, problem reports, and pull requests are very much appreciated.
Directories
¶
| Path | Synopsis |
|---|---|
|
package api contains the API definitions for external use, such as the RPC sink.
|
package api contains the API definitions for external use, such as the RPC sink. |
|
pb
Package pb contains the protobuf definitions for pgwatch gRPC API.
|
Package pb contains the protobuf definitions for pgwatch gRPC API. |
|
cmd
|
|
|
pgwatch
command
pgwatch is a command line tool that collects metrics from PostgreSQL databases and forwards to external sinks.
|
pgwatch is a command line tool that collects metrics from PostgreSQL databases and forwards to external sinks. |
|
docs
|
|
|
howto/embedding
command
Command embedding is a minimal pgwatch embedder: it runs the real collector and REST API, serves its own web UI instead of the React one, adds an authenticated /hello endpoint next to the REST API, and contributes its own command-line flag group.
|
Command embedding is a minimal pgwatch embedder: it runs the real collector and REST API, serves its own web UI instead of the React one, adds an authenticated /hello endpoint next to the REST API, and contributes its own command-line flag group. |
|
internal
|
|
|
testutil
Package testutil provides testing utilities for pgwatch tests.
|
Package testutil provides testing utilities for pgwatch tests. |
|
webui/embed
Package embed carries the React web UI built from internal/webui and exposes it as the default ui.Provider.
|
Package embed carries the React web UI built from internal/webui and exposes it as the default ui.Provider. |
|
Package pkg is the root of pgwatch's public API.
|
Package pkg is the root of pgwatch's public API. |
|
app
Package app bootstraps pgwatch: it wires the logger, the configuration readers, the sink writer, the schema check, the reaper and the web server into the same startup sequence the pgwatch binary runs, and owns signal handling, panic recovery and exit-code mapping.
|
Package app bootstraps pgwatch: it wires the logger, the configuration readers, the sink writer, the schema check, the reaper and the web server into the same startup sequence the pgwatch binary runs, and owns signal handling, panic recovery and exit-code mapping. |
|
cmdopts
Package cmdopts provides functionality to parse command line options and ENV variables.
|
Package cmdopts provides functionality to parse command line options and ENV variables. |
|
db
Package db provides common functionality to work with databases.
|
Package db provides common functionality to work with databases. |
|
log
Package log contains the logger interface and its implementation used in the project.
|
Package log contains the logger interface and its implementation used in the project. |
|
metrics
Package metrics is responsible for reading and writing metric definitions.
|
Package metrics is responsible for reading and writing metric definitions. |
|
reaper
Package reaper is responsible to query the metrics from monitored sources and send measurements to sinks.
|
Package reaper is responsible to query the metrics from monitored sources and send measurements to sinks. |
|
sinks
Package sinks provides functionality to store monitored data in different ways.
|
Package sinks provides functionality to store monitored data in different ways. |
|
sources
Provides functionality to read monitored data from different sources.
|
Provides functionality to read monitored data from different sources. |
|
ui
Package ui defines the contract between the pgwatch web server and the web user interface it serves.
|
Package ui defines the contract between the pgwatch web server and the web user interface it serves. |
|
webserver
Package webserver serves the REST API and the web user interface.
|
Package webserver serves the REST API and the web user interface. |