Setting up Prometheus

Prometheus can be set up on any Linux-based system, but pgMonitor currently only supports running it on RHEL/CentOS 7 or later.

Installation

RHEL / CentOS

With RPM Packages

There are RPM packages available to Crunchy Data customers through the Crunchy Customer Portal. To access the pgMonitor packages, please follow the same instructions for setting up access to the Crunchy Postgres packages.

After installing via these RPMs, you can continue reading at the Setup section.

Available Packages
Package Name Description
alertmanager Base package for the Alertmanager
prometheus2 Base package for Prometheus 2.x
pgmonitor-alertmanager-extras Custom Crunchy configurations for Alertmanager
pgmonitor-prometheus-extras Custom Crunchy configurations for Prometheus

Without Crunchy Data Packages

For installations without using packages provided by Crunchy Data, we recommend using the repository maintained at https://github.com/lest/prometheus-rpm. Instructions for setup and installation are contained there. Note this only sets up the base service. The additional files and steps for pgMonitor still need to be set up as instructed below.

Or you can also download Prometheus and Alertmanager from the original site at https://prometheus.io/download. Note that no base service setup is provided here, just the binaries.

Minimum Versions

pgMonitor has been tested with the following versions at a minimum. Later versions should generally work. If they do not, please open an issue on our Github.

  • Prometheus 2.49.1
  • Alertmanager 0.26.0
User and Configuration Directory Installation

You will need to create a system user named ccp_monitoring which you can do with the following command:

sudo useradd -m -d /var/lib/ccp_monitoring ccp_monitoring
Configuration File Installation

The files contained in this repository are assumed to be installed in the following locations with the following names:

Prometheus

The Prometheus data directory should be /var/lib/ccp_monitoring/prometheus and owned by the ccp_monitoring user. You can set it up with:

sudo install -d -m 0700 -u ccp_monitoring -g ccp_monitoring /var/lib/ccp_monitoring/prometheus

The following pgmonitor configuration files should be placed according to the following mapping:

pgMonitor Configuration File System Location
prometheus/linux/crunchy-prometheus-service-rhel.conf /etc/systemd/system/prometheus.service.d/crunchy-prometheus-service-rhel.conf
prometheus/linux/sysconfig.prometheus /etc/sysconfig/prometheus
prometheus/linux/crunchy-prometheus.yml /etc/prometheus/crunchy-prometheus.yml
prometheus/linux/auto.d/*.yml.example /etc/prometheus/auto.d/*.yml.example
prometheus/linux/alert-rules.d/crunchy-alert-rules*.yml.example /etc/prometheus/alert-rules.d/crunchy-alert-rules-*.yml.example
prometheus/common/auto.d/*.yml.example /etc/prometheus/auto.d/*.yml.example
prometheus/common/alert-rules.d/crunchy-alert-rules*.yml.example /etc/prometheus/alert-rules.d/crunchy-alert-rules-*.yml.example
Alertmanager

The Alertmanager data directory should be /var/lib/ccp_monitoring/alertmanager and owned by the ccp_monitoring user. You can set it up with:

sudo install -d -m 0700 -o ccp_monitoring -g ccp_monitoring /var/lib/ccp_monitoring/alertmanager

The following pgMonitor configuration files should be placed according to the following mapping:

pgMonitor Configuration File System Location
alertmanager/linux/crunchy-alertmanager-service-rhel.conf /etc/systemd/system/alertmanager.service.d/crunchy-alertmanager-service-rhel.conf
alertmanager/linux/sysconfig.alertmanager /etc/sysconfig/alertmanager
alertmanager/common/crunchy-alertmanager.yml /etc/prometheus/crunchy-alertmanager.yml

Upgrading

  • If you are upgrading to version 5.0 and transitioning to using the new sql_exporter, please see the documentation in Upgrading to pgMonitor v5.0.0
  • See the CHANGELOG for full details on both major & minor version upgrades.
  • Note, items like the alert rules and configuration files often require user edits. The packages will install newer versions of these files, but if the user has changed their contents but kept the same file name, the package will not overwrite them. Instead it will make a file with an *.rpmnew extension that contains the newer version of the file. These new files can be reviewed/compared to he user’s file to incorporate any desired changes.

Setup

Setup on RHEL/CentOS

Service Configuration

The following files contain defaults that should enable Prometheus and Alertmanager to run effectively on your system for the purposes of using pgmonitor. You should take some time to review them.

If you need to modify them, see the notes in the files for more details and recommendations:

  • /etc/systemd/system/prometheus.service.d/crunchy-prometheus-service-rhel.conf
  • /etc/systemd/system/alertmanager.service.d/crunchy-alertmanager-service-rhel.conf

The below files contain startup properties for Prometheues and Alertmanager. Please review and modify these files as you see fit:

  • /etc/sysconfig/prometheus
  • /etc/sysconfig/alertmanager

The below files dictate how Prometheus and Alertmanager will behave at runtime for the purposes of using pgMonitor. Please review each file below and follow the instructions in order to set things up:

File Instructions
/etc/prometheus/crunchy-prometheus.yml Main configuration file for prometheus to set things like scrape intervals and alerting. blackbox_exporter monitoring can also be enabled if desired. Service file provided by pgMonitor expects config file to be named “crunchy-prometheus.yml”. For full configuration options please see the Prometheus upstream documentation
/etc/prometheus/crunchy-alertmanager.yml Setup alert target (e.g., SMTP, SMS, etc.), receiver and route information. Service file provided by pgMonitor expects config file to be named “crunchy-alertmanager.yml”. For full configuration options please see the Alertmanager upstream documentation
/etc/prometheus/alert-ruled.d/crunchy-alert-rules-*.yml.example Update rules as needed and remove “.example” suffix. Prometheus config provided by pgmonitor expects “.yml” files to be located in “/etc/prometheus/alert-rules.d/”. Additional information on configuring alert rules can be found in the alert rules upstream documentation.
/etc/prometheus/auto.d/*.yml You will need at least one file with a final “.yml” extension. Copy the example files to create as many additional targets as needed. Ensure the configuration files you want to use do not end in “.yml.example” but only with “.yml”. Note that in order to use the provided Grafana dashboards, the extra “exp_type” label must be applied to all targets and be set appropriately (pg, node, etcd, pgbouncer, etc). Also, PostgreSQL targets make use of the “cluster_name” variable and should be given a relevant value so all systems (primary & replicas) can be related to each other when needed (Grafana dashboards, etc). See the example target files provided for how to set the labels for postgres or node exporter targets.

Blackbox Exporter

By default, the Blackbox exporter probes are commented out in the crunchy-prometheus.yml file; please see the notes in that commented out section. For the default IPv4 TCP port targets that pgMonitor configures the blackbox_exporter with, the desired monitoring targets can be configured under the static_configs: targets section of the blackbox_tcp_services job; some examples for Grafana & Patroni are given there. It is also possible to create another auto-scrape target directory similar to auto.d and manage your blackbox targets more dynamically.

If you configure additional probes beyond the one that pgMonitor comes with, you will need to create a different Prometheus job_name for them for the given params: module name.

An example rules file for monitoring Blackbox probes, crunchy-alert-rules-blackbox.yml.example , is available in the alert-rules.d folder.

Enable Services

To enable and start Prometheus as a service, execute the following commands:

sudo systemctl enable prometheus
sudo systemctl start prometheus
sudo systemctl status prometheus

To enable and start Alertmanager as a service, execute the following commands:

sudo systemctl enable alertmanager
sudo systemctl start alertmanager
sudo systemctl status alertmanager