Skip to content

Commit

Permalink
docs: make package vs non-package consistent
Browse files Browse the repository at this point in the history
  • Loading branch information
@keithf4
keithf4 committed Dec 10, 2024
1 parent 4abd279 commit f58cf34
Show file tree
Hide file tree
Showing 5 changed files with 48 additions and 45 deletions.
4 changes: 2 additions & 2 deletions .pre-commit-config.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ default_install_hook_types:
- pre-commit
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.6.0
rev: v5.0.0
hooks:
- id: check-merge-conflict
- id: check-symlinks
Expand All @@ -21,7 +21,7 @@ repos:
stages: [commit-msg]
additional_dependencies: ['@commitlint/config-conventional']
- repo: https://github.com/codespell-project/codespell
rev: v2.1.0
rev: v2.3.0
hooks:
- id: codespell
# if you need to add more words to ignore, they are comme separated
Expand Down
3 changes: 3 additions & 0 deletions changelogs/fragments/package_docs.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
---
trivial:
- documentation - Make documentation around package vs non-package installs more clear and consistent. Remove postgres_exporter file references from PG Metrics list.
47 changes: 24 additions & 23 deletions hugo/content/exporter/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,43 +8,44 @@ The Linux instructions below use RHEL, but any Linux-based system should work. [


- [Installation](#installation)
- [RPM installs](#rpm-installs)
- [Non-RPMs installs](#non-rpm-installs)
- [Package Install](#package-install)
- [Non-Package Install](#non-package-install)
- [Upgrading](#upgrading)
- [Setup](#setup)
- [RHEL or CentOS](#setup-on-rhel-or-centos)
- [RHEL](#setup-on-rhel)
- [Metrics Collected](#metrics-collected)
- [PostgreSQL](#postgresql)
- [System](#system)
- [Legacy postgres_exporter Setup](#postgres-exporter)


IMPORTANT NOTE: As of pgMonitor version 5.0.0, postgres_exporter has been deprecated in favor of sql_exporter. Support for postgres_exporter is still possible with 5.0, but only for bug fixes while custom queries are still supported. No new features will be added using postgres_exporter and it will be fully obsoleted in a future version of pgMonitor. We recommend migrating to sql_exporter as soon as possible.
IMPORTANT NOTE: As of pgMonitor version 5.0.0, postgres_exporter has been deprecated in favor of sql_exporter. Support for postgres_exporter is still possible with 5.0, but only for bug fixes while custom queries are still supported upstream. No new features will be added using postgres_exporter and it will be fully obsoleted in a future version of pgMonitor. We recommend migrating to sql_exporter as soon as possible.

## Installation {#installation}


### RPM installs {#rpm-installs}
### Package Install {#package-install}

The following RPM packages are available to [Crunchy Data](https://www.crunchydata.com) customers through the [Crunchy Customer Portal](https://access.crunchydata.com/). To access the pgMonitor packages, please follow the same instructions for setting up access to the Crunchy Postgres packages.

After installing via these packages, continue reading at the [Setup](#setup) section.

##### Available Packages
#### Available Packages

| Package Name | Description |
|--------------------------------|---------------------------------------------------------------------------|
| blackbox-exporter | Package for the blackbox_exporter |
| node-exporter | Base package for node_exporter |
| pg-bloat-check | Package for pg_bloat_check script |
| pgmonitor-node_exporter-extras | Crunchy-optimized configurations for node_exporter |
| pgmonitor-pg##-extension | Crunchy monitoring PostgreSQL extension used by sql_exporter |
| sql-exporter | Base package for sql_exporter |
| sql-exporter-extras | Crunchy-optimized configurations for sql_exporter |
| Package Name | Description |
|---------------------------------------|---------------------------------------------------------------------------|
| blackbox-exporter | Package for the blackbox_exporter |
| pgmonitor-blackbox-exporter-extras | Crunchy-optimized configurations for blackbox_exporter |
| node-exporter | Base package for node_exporter |
| pg-bloat-check | Package for pg_bloat_check script |
| pgmonitor-node_exporter-extras | Crunchy-optimized configurations for node_exporter |
| pgmonitor-pg##-extension | Crunchy monitoring PostgreSQL extension used by sql_exporter |
| sql-exporter | Base package for sql_exporter |
| pgmonitor-sql-exporter-extras | Crunchy-optimized configurations for sql_exporter |



### Non-RPM installs {#non-rpm-installs}
### Non-Package Install {#non-package-install}

For non-package installations on Linux, applications can be downloaded from their respective repositories:

Expand Down Expand Up @@ -127,7 +128,7 @@ Note that blackbox_exporter is typically installed on the Prometheus node and do

## Setup {#setup}

### Setup on RHEL or CentOS {#setup-on-rhel-or-centos}
### Setup on RHEL {#setup-on-rhel}

#### Service Configuration

Expand Down Expand Up @@ -332,7 +333,7 @@ PostgreSQL metrics are collected by [sql_exporter](https://github.com/burningalc

#### Common Metrics

Metrics contained in the `queries_global.yml` file. These metrics are common to all versions of PostgreSQL and are recommended as a minimum default for the global exporter.
These metrics are common to all versions of PostgreSQL and are recommended as a minimum default for the global exporter exporter connection.

* *ccp_archive_command_status_seconds_since_last_fail* - Seconds since the last `archive_command` run failed. If zero, the `archive_command` is succeeding without error.

Expand Down Expand Up @@ -429,15 +430,15 @@ The following `ccp_stat_database_*` metrics are statistics collected from the [p

#### PostgreSQL Version Specific Metrics

The following metrics either require special considerations when monitoring specific versions of PostgreSQL, or are only available for specific versions. These metrics are found in the `queries_pg##.yml` files, where ## is the major version of PG. Unless otherwise noted, the below metrics are available for all versions of PG. These metrics are recommend as a minimum default for the global exporter.
The following metrics either require special considerations when monitoring specific versions of PostgreSQL, or are only available for specific versions. Unless otherwise noted, the below metrics are available for all versions of PG. These metrics are recommend as a minimum default for the global exporter.

* *ccp_data_checksum_failure_count* - PostgreSQL 12 and later only. Total number of checksum failures on this database.

* *ccp_data_checksum_failure_time_since_last_failure_seconds* - PostgreSQL 12 and later only. Time interval in seconds since the last checksum failure was encountered.

#### Backup Metrics

Backup monitoring only covers pgBackRest at this time. These metrics are found in the `queries_backrest.yml` file. These metrics only need to be collected once per database instance so should be collected by the global postgres_exporter.
Backup monitoring only covers pgBackRest at this time. These metrics only need to be collected once per PostgreSQL instance so should be collected by the global exporter connection.

* *ccp_backrest_last_full_backup_time_since_completion_seconds* - Time since completion of last pgBackRest FULL backup

Expand All @@ -455,7 +456,7 @@ Backup monitoring only covers pgBackRest at this time. These metrics are found i

#### Per-Database Metrics

These are metrics that are only available on a per-database level. These metrics are found in the `queries_per_db.yml` file. These metrics are optional and recommended for the non-global, per-db postgres_exporter. They can be included in the global exporter as well if the global database needs per-database metrics monitored. Please note that depending on the number of objects in your database, collecting these metrics can greatly increase the storage requirements for Prometheus since all of these metrics are being collected for each individual object.
These are metrics that are only available on a per-database level. These metrics are optional and recommended for the non-global, per-db exporter connection. They can be included in the global exporter as well if the global database needs per-database metrics monitored. Please note that depending on the number of objects in your database, collecting these metrics can greatly increase the storage requirements for Prometheus since all of these metrics are being collected for each individual object.

* *ccp_table_size_size_bytes* - Table size inclusive of all indexes in that table

Expand All @@ -477,7 +478,7 @@ The following `ccp_stat_user_tables_*` metrics are statistics collected from the

#### Bloat Metrics

Bloat metrics are only available if the `pg_bloat_check` script has been setup to run. See instructions above. These metrics are found in the `queries_bloat.yml` file. These metrics are per-database so, should be used by the per-db postgres_exporter.
Bloat metrics are only available if the `pg_bloat_check` script has been setup to run. See instructions above. These metrics are per-database so, should be used by the per-db exporter connection.

* *ccp_bloat_check_size_bytes* - Size of object in bytes

Expand Down Expand Up @@ -533,7 +534,7 @@ There are many other suggestions, projects, and exporters out there that can pro

## Legacy postgres_exporter Setup {#postgres-exporter}

If you had been using pgMonitor prior to version 5.0.0, postgres_exporter was the method used to collect PostgreSQL metrics. This exporter can still be used with 5.0.0, but there are some additional steps required. It is HIGHLY recommended to switch to using sql_exporter as soon as possible. Custom query support will be dropped from postgres_exporter at some point in the future and that will break pgMonitor since it relies solely on custom queries. No new features of pgMonitor are being developed around postgres_exporter.
If you had been using pgMonitor prior to version 5.0.0, postgres_exporter was the method used to collect PostgreSQL metrics. This exporter can still be used with 5.0.0, but there are some additional steps required and it will be deprecated in the near future. It is HIGHLY recommended to switch to using sql_exporter as soon as possible. Custom query support will be dropped from postgres_exporter at some point in the future and that will break pgMonitor since it relies solely on custom queries. No new features of pgMonitor are being developed around postgres_exporter.

Most of the installation steps are the same as above with the below differences for the relevant sections.

Expand Down
14 changes: 7 additions & 7 deletions hugo/content/grafana/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,11 @@ weight: 3

- [Included Dashboards](#dashboards)
- [Installation](#installation)
- [Linux](#linux)
- [Package Install](#package-install)
- [Non-Package Install](#non-package-install)
- [Upgrading](#upgrading)
- [Setup](#setup)
- [Linux](#setup-on-linux)
- [RHEL](#setup-on-linux)

### Included Dashboards {#dashboards}

Expand Down Expand Up @@ -40,9 +41,7 @@ pgMonitor comes with several dashboards ready to be used with automatic provisio

## Installation {#installation}

### Linux {#linux}

#### With RPM Packages
### Package Install {#package-install}

There are RPM packages available to [Crunchy Data](https://www.crunchydata.com) customers through the [Crunchy Customer Portal](https://access.crunchydata.com/). To access the pgMonitor packages, please follow the same instructions for setting up access to the Crunchy Postgres packages.

Expand All @@ -56,14 +55,15 @@ If you install the below available packages, you can continue reading at the [Se
| pgmonitor-grafana-extras-common | Crunchy files common for all Grafana installations (Ex. datasource & dashboard provisioning) |
| pgmonitor-grafana-extras-etcd | Crunchy dashboards for etcd (etcd built-in exporter) |
| pgmonitor-grafana-extras-linux | Crunchy dashboards for Linux OS metrics (node_exporter) |
| pgmonitor-grafana-extras-haproxy | Crunchy dashboards for HAProxy (built-in exporter) |
| pgmonitor-grafana-extras-pg | Crunchy dashboards for PostgreSQL metrics common to all PG exporters |
| pgmonitor-grafana-extras-pg-postgres-exporter | Crunchy dashboards for metrics provided by postgres_exporter (see version 5 upgrade for deprecation notice) |
| pgmonitor-grafana-extras-pg-sql-exporter | Crunchy dashboards for metrics provided by the sql_exporter |
| pgmonitor-grafana-extras-pgbouncer-direct | Crunchy dashboards for PgBouncer metrics collected directly from bouncer via the sql_exporter |
| pgmonitor-grafana-extras-pgbouncer-fdw | Crunchy dashboards for PgBouncer metrics collected via the pgbouncer_fdw |
| pgmonitor-grafana-extras-prometheus | Crunchy dashboards for proividing direct Prometheus visualization (alerting) |

#### Without Packages
### Non-Package Install {#non-package-install}

Create the following directories on your grafana server if they don't exist:

Expand Down Expand Up @@ -94,7 +94,7 @@ Please note that due to the change from postgres_exporter to sql_exporter, and i

## Setup {#setup}

### Setup on Linux {#setup-on-linux}
### Setup on RHEL {#setup-on-linux}

#### Configuration Database

Expand Down
25 changes: 12 additions & 13 deletions hugo/content/prometheus/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,16 +7,15 @@ weight: 2
Prometheus can be set up on any Linux-based system, but pgMonitor currently only supports running it on RHEL/CentOS 7 or later.

- [Installation](#installation)
- [RHEL / CentOS](#rhel-centos)
- [Package Install](#package-install)
- [Non-Package Install](#non-package-install)
- [Upgrading](#upgrading)
- [Setup](#setup)
- [RHEL / CentOS](#setup-on-rhel-centos)
- [RHEL](#setup-on-rhel)

## Installation {#installation}

### RHEL / CentOS {#rhel-centos}

#### With RPM Packages
### Package Install {#package-install}

There are RPM packages available to [Crunchy Data](https://www.crunchydata.com) customers through the [Crunchy Customer Portal](https://access.crunchydata.com/). To access the pgMonitor packages, please follow the same instructions for setting up access to the Crunchy Postgres packages.

Expand All @@ -31,32 +30,32 @@ After installing via these RPMs, you can continue reading at the [Setup](#setup)
| pgmonitor-alertmanager-extras | Custom Crunchy configurations for Alertmanager |
| pgmonitor-prometheus-extras | Custom Crunchy configurations for Prometheus |

#### Without Crunchy Data Packages
### Non-Package Install {#non-package-install}

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](https://prometheus.io/) and [Alertmanager](https://prometheus.io/docs/alerting/alertmanager/) from the original site at [https://prometheus.io/download](https://prometheus.io/download). Note that no base service setup is provided here, just the binaries.

##### Minimum Versions
#### 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
#### User and Configuration Directory Installation

You will need to create a system user named {{< shell >}}ccp_monitoring{{< /shell >}} which you can do with the following command:

```bash
sudo useradd -m -d /var/lib/ccp_monitoring ccp_monitoring
```

##### Configuration File Installation
#### Configuration File Installation

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

###### Prometheus
##### Prometheus

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

Expand All @@ -76,7 +75,7 @@ The following pgmonitor configuration files should be placed according to the fo
| 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
##### 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:

Expand All @@ -93,15 +92,15 @@ The following pgMonitor configuration files should be placed according to the fo
| alertmanager/common/crunchy-alertmanager.yml | /etc/prometheus/crunchy-alertmanager.yml |


### Upgrading {#upgrading}
## Upgrading {#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](/changelog/v5_upgrade/)
* See the [CHANGELOG ](/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 {{< shell >}}*.rpmnew{{< /shell >}} 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}

### Setup on RHEL/CentOS {#setup-on-rhel-centos}
### Setup on RHEL {#setup-on-rhel}

#### Service Configuration

Expand Down

0 comments on commit f58cf34

Please sign in to comment.