From 92e54cc174b3f4fc834fb386f3ce3fea7d5b7b32 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Wed, 16 Jul 2025 15:15:10 +0300 Subject: [PATCH 1/7] fix indentations --- docs/telemetry.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/telemetry.md b/docs/telemetry.md index 2ac49ba98..2f901d197 100644 --- a/docs/telemetry.md +++ b/docs/telemetry.md @@ -14,11 +14,11 @@ Telemetry collects the following information: ## What is NOT collected -Percona protects your privacy and doesn't collect any personal information about you like database names, user names or credentials or any user-entered values. +Percona protects your privacy and doesn't collect any personal information about you like database names, user names or credentials or any user-entered values. All collected data is anonymous, meaning it can't be traced back to any individual user. To learn more about how Percona handles your data, read the [Percona Privacy statement](https://www.percona.com/privacy-policy). -You control whether to share this information. Participation in this program is completely voluntary. If don't want to share anonymous data, you can [disable telemetry](#disable-telemetry). +You control whether to share this information. Participation in this program is completely voluntary. If don't want to share anonymous data, you can [disable telemetry](#disable-telemetry). ## Why telemetry matters @@ -171,7 +171,6 @@ The following is an example of the collected data generated by the `percona_pg_t } ``` - ### Telemetry Agent The Percona Telemetry Agent runs as a dedicated OS daemon process `percona-telemetry-agent`. It creates, reads, writes, and deletes JSON files in the [`${telemetry root path}`](#locations). You can find the agent's log file at `/var/log/percona/telemetry-agent.log`. @@ -252,11 +251,11 @@ The package names must fit the following pattern: * `wal2json` -## Disable telemetry +## Disable telemetry Telemetry is enabled by default when you install the software. It is also included in the software packages (Telemetry Subsystem and Telemetry Agent) and enabled by default. -If you don't want to send the telemetry data, here's how: +If you don't want to send the telemetry data, here's how: ### Disable the telemetry collected during the installation @@ -297,7 +296,6 @@ If you decide not to send usage data to Percona when you install the software, y * `-e PERCONA_TELEMETRY_DISABLE=1` - Sets an environment variable within the container. In this case, it disables telemetry for Percona Distribution for PostgreSQL. * `percona/percona-distribution-postgresql:-multi` - Specifies the image to use for the container. For example, `{{dockertag}}-multi`. The `multi` part of the tag serves to identify the architecture (x86_64 or ARM64) and use the respective image. - ## Disable telemetry for the installed software Percona software you installed includes the telemetry feature that collects information about how you use this software. It is enabled by default. To turn off telemetry, you need to disable both the Telemetry Agent and the Telemetry Subsystem. @@ -328,7 +326,7 @@ Even after stopping the Telemetry Agent service, a different part of the softwar ### Telemetry Agent dependencies and removal considerations -If you decide to remove the Telemetry Agent, this also removes the database. That's because the Telemetry Agent is a mandatory dependency for Percona Distribution for PostgreSQL. +If you decide to remove the Telemetry Agent, this also removes the database. That's because the Telemetry Agent is a mandatory dependency for Percona Distribution for PostgreSQL. On YUM-based systems, the system removes the Telemetry Agent package when you remove the last dependency package. @@ -348,7 +346,7 @@ To disable the Metrics File creation, stop and drop the `percona_pg_telemetry` e ``` 2. Remove the `percona_pg_telemetry` extension from the database: - + ```sql DROP EXTENSION percona_pg_telemetry; ``` @@ -371,14 +369,12 @@ To disable the Metrics File creation, stop and drop the `percona_pg_telemetry` e $ sudo systemctl restart postgresql.service ``` - === ":material-redhat: On Red Hat Enterprise Linux and derivatives" ```{.bash data-prompt="$"} $ sudo systemctl restart postgresql-{{pgversion}} ``` - !!! tip If you wish to re-enable the Telemetry Subsystem, complete the above steps in the reverse order: From c19e7432e77f11f325ce703ee5fc35a3497204b5 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Thu, 17 Jul 2025 10:23:54 +0300 Subject: [PATCH 2/7] update docker command for disabling telemetry --- docs/telemetry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/telemetry.md b/docs/telemetry.md index 2f901d197..28240dc61 100644 --- a/docs/telemetry.md +++ b/docs/telemetry.md @@ -284,7 +284,7 @@ If you decide not to send usage data to Percona when you install the software, y ```{.bash data-prompt="$"} $ docker run -d --name pg --restart always \ -e PERCONA_TELEMETRY_DISABLE=1 \ - percona/percona-distribution-postgresql:-multi + docker pull percona/percona-distribution-postgresql:-multi ``` The command does the following: From a2d1cf9a29346e2e56167d8e458455631a050a2a Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Thu, 17 Jul 2025 16:10:14 +0300 Subject: [PATCH 3/7] add example output for removing telemetry and fix indentations for agent and metrics --- docs/release-notes-v17.5 copy.md | 50 +++++++++ docs/telemetry.md | 186 ++++++++++++++++--------------- 2 files changed, 148 insertions(+), 88 deletions(-) create mode 100644 docs/release-notes-v17.5 copy.md diff --git a/docs/release-notes-v17.5 copy.md b/docs/release-notes-v17.5 copy.md new file mode 100644 index 000000000..b2eb30ea3 --- /dev/null +++ b/docs/release-notes-v17.5 copy.md @@ -0,0 +1,50 @@ +# Percona Distribution for PostgreSQL 17.5.2 ({{date.17_5}}) + +--8<-- "release-notes-intro.md" + +This release of Percona Distribution for PostgreSQL is based on Percona Server for PostgreSQL 17.5.2 - a binary compatible, open source drop in replacement of [PostgreSQL Community 17.5](https://www.postgresql.org/docs/17/release-17-5.html). + +## Release Highlights + +### General Availability (GA) of pg_tde + +Percona Distribution for PostgreSQL now includes the 1.0 GA release of Percona's Transparent Data Encryption for PostgreSQL. + +Learn more in the [`pg_tde` 1.0 release notes :octicons-link-external-16:](https://docs.percona.com/pg-tde/release-notes/release-notes-v1.0.html). + +### Major documentation update + +The `pg_tde` documentation has received significant updates, which include: + +- New KMS configuration guides for Fortanix, Vault, KMIP and OpenBAO +- Reorganized and expanded topics for Architecture, GUC, Functions, TDE Operations and FAQ +- Extensive and numerous refinements and clarifications across the entire site + +Explore the full documentation [in the official `pg_tde` documentations](https://docs.percona.com/pg-tde/index.html). + +The following is the list of extensions available in Percona Distribution for PostgreSQL. + +| Extension | Version | Description | +|--------------------------------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------| +| [etcd :octicons-link-external-16:](https://etcd.io/) | 3.5.21 | A distributed, reliable key-value store for setting up high available Patroni clusters | +| [HAProxy :octicons-link-external-16:](http://www.haproxy.org/) | 2.8.15 | A high-availability and load-balancing solution | +| [Patroni :octicons-link-external-16:](https://patroni.readthedocs.io/en/latest/) | 4.0.5 | A HA (High Availability) solution for PostgreSQL | +| [PgAudit :octicons-link-external-16:](https://www.pgaudit.org/) | 17.1 | Provides detailed session or object audit logging via the standard logging facility provided by PostgreSQL | +| [pgAudit set_user :octicons-link-external-16:](https://github.com/pgaudit/set_user) | 4.1.0 | Provides an additional layer of logging and control when unprivileged users must escalate roles for maintenance. | +| [pgBackRest :octicons-link-external-16:](https://pgbackrest.org/) | 2.55.0 | A backup and restore solution for PostgreSQL | +| [pgBadger :octicons-link-external-16:](https://github.com/darold/pgbadger) | 13.1 | A fast PostgreSQL Log Analyzer | +| [PgBouncer :octicons-link-external-16:](https://www.pgbouncer.org/) | 1.24.1 | A lightweight connection pooler for PostgreSQL | +| [pg_gather :octicons-link-external-16:](https://github.com/jobinau/pg_gather) | v30 | An SQL script for running the diagnostics of the health of a PostgreSQL cluster | +| [pgpool2 :octicons-link-external-16:](https://git.postgresql.org/gitweb/?p=pgpool2.git;a=summary) | 4.6.0 | A middleware between PostgreSQL server and client for high availability, connection pooling, and load balancing | +| [pg_repack :octicons-link-external-16:](https://github.com/reorg/pg_repack) | 1.5.2 | Rebuilds PostgreSQL database objects | +| [pg_stat_monitor](https://github.com/percona/pg_stat_monitor) | 2.2.0 | collects and aggregates statistics for PostgreSQL and provides histogram information. | +| [pgvector :octicons-link-external-16:](https://github.com/pgvector/pgvector) | v0.8.0 | A vector similarity search for PostgreSQL | +| [PostGIS :octicons-link-external-16:](https://github.com/postgis/postgis) | 3.3.8 | A spatial extension for PostgreSQL | +| [PostgreSQL Common :octicons-link-external-16:](https://salsa.debian.org/postgresql/postgresql-common) | 277 | PostgreSQL database-cluster manager. Supports multiple PostgreSQL versions and clusters simultaneously | +| [wal2json :octicons-link-external-16:](https://github.com/eulerto/wal2json) | 2.6 | A PostgreSQL logical decoding JSON output plugin | + +For Red Hat Enterprise Linux 8 and compatible derivatives, Percona Distribution for PostgreSQL also includes the supplemental `python3-etcd` 0.4.5 packages, which are used for setting up Patroni clusters. + +Percona Distribution for PostgreSQL is also shipped with the [libpq](https://www.postgresql.org/docs/17/libpq.html) library. It contains "a set of +library functions that allow client programs to pass queries to the PostgreSQL +backend server and to receive the results of these queries." diff --git a/docs/telemetry.md b/docs/telemetry.md index 28240dc61..5acd6db81 100644 --- a/docs/telemetry.md +++ b/docs/telemetry.md @@ -100,76 +100,76 @@ Percona archives the telemetry history in `${telemetry root path}/history/`. The Metrics File uses the Javascript Object Notation (JSON) format. Percona reserves the right to extend the current set of JSON structure attributes in the future. -The following is an example of the collected data generated by the `percona_pg_telemetry` extension: - - ```json +The following is an example of the collected data generated by the `percona_pg_telemetry` extension: + + ```json + { + "db_instance_id": "7310358902660071382", + "pillar_version": "17.0", + "uptime": "36", + "databases_count": "2", + "settings": [ + { + "key": "setting", + "value": [ + { + "key": "name", + "value": "allow_in_place_tablespaces" + }, + { + "key": "unit", + "value": "NULL" + }, + { + "key": "setting", + "value": "off" + }, + { + "key": "reset_val", + "value": "off" + }, { - "db_instance_id": "7310358902660071382", - "pillar_version": "17.0", - "uptime": "36", - "databases_count": "2", - "settings": [ + "key": "boot_val", + "value": "off" + } + ] + }, + ... + ], + "databases": [ + { + "key": "database", + "value": [ + { + "key": "database_oid", + "value": "5" + }, + { + "key": "database_size", + "value": "7820895" + }, + { + "key": "active_extensions", + "value": [ { - "key": "setting", - "value": [ - { - "key": "name", - "value": "allow_in_place_tablespaces" - }, - { - "key": "unit", - "value": "NULL" - }, - { - "key": "setting", - "value": "off" - }, - { - "key": "reset_val", - "value": "off" - }, - { - "key": "boot_val", - "value": "off" - } - ] + "key": "extension_name", + "value": "plpgsql" }, - ... - ], - "databases": [ { - "key": "database", - "value": [ - { - "key": "database_oid", - "value": "5" - }, - { - "key": "database_size", - "value": "7820895" - }, - { - "key": "active_extensions", - "value": [ - { - "key": "extension_name", - "value": "plpgsql" - }, - { - "key": "extension_name", - "value": "pg_tde" - }, - { - "key": "extension_name", - "value": "percona_pg_telemetry" - } - ] - } - ] + "key": "extension_name", + "value": "pg_tde" + }, + { + "key": "extension_name", + "value": "percona_pg_telemetry" } ] } - ``` + ] + } + ] + } + ``` ### Telemetry Agent @@ -179,28 +179,28 @@ The agent does not send anything if there are no Percona-specific files in the t The following is an example of a Telemetry Agent payload: -```json -{ - "reports": [ - { - "id": "B5BDC47B-B717-4EF5-AEDF-41A17C9C18BB", - "createTime": "2023-09-01T10:56:49Z", - "instanceId": "B5BDC47B-B717-4EF5-AEDF-41A17C9C18BA", - "productFamily": "PRODUCT_FAMILY_POSTGRESQL", - "metrics": [ - { - "key": "OS", - "value": "Ubuntu" - }, - { - "key": "pillar_version", - "value": "17.0" - } - ] - } - ] -} -``` + ```json + { + "reports": [ + { + "id": "B5BDC47B-B717-4EF5-AEDF-41A17C9C18BB", + "createTime": "2023-09-01T10:56:49Z", + "instanceId": "B5BDC47B-B717-4EF5-AEDF-41A17C9C18BA", + "productFamily": "PRODUCT_FAMILY_POSTGRESQL", + "metrics": [ + { + "key": "OS", + "value": "Ubuntu" + }, + { + "key": "pillar_version", + "value": "17.0" + } + ] + } + ] + } + ``` The agent sends information about the database and metrics. @@ -345,10 +345,20 @@ To disable the Metrics File creation, stop and drop the `percona_pg_telemetry` e SELECT pg_reload_conf(); ``` -2. Remove the `percona_pg_telemetry` extension from the database: + ??? example "Example output" - ```sql - DROP EXTENSION percona_pg_telemetry; + ```sql + ALTER SYSTEM + pg_reload_conf + ---------------- + t + (1 row) + ``` + +2. Remove the `percona_pg_telemetry` extension from the `postgresql.conf` file: + + ``` + sudo nano /path/to/postgresql.conf ``` 3. Remove `percona_pg_telemetry` from the `shared_preload_libraries` configuration parameter: From 338c06cd3bbf692e556f857da0aa0b4d6b214d3b Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Thu, 17 Jul 2025 17:13:10 +0300 Subject: [PATCH 4/7] update step 2 and 3 to edit correct file parameter And added at the end the steps to revert the changes the file name user needs to modify --- docs/telemetry.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/telemetry.md b/docs/telemetry.md index 5acd6db81..2d5b2b0a9 100644 --- a/docs/telemetry.md +++ b/docs/telemetry.md @@ -355,16 +355,18 @@ To disable the Metrics File creation, stop and drop the `percona_pg_telemetry` e (1 row) ``` -2. Remove the `percona_pg_telemetry` extension from the `postgresql.conf` file: +2. Remove the `percona_pg_telemetry` extension from the database: + ```sql + DROP EXTENSION percona_pg_telemetry; ``` - sudo nano /path/to/postgresql.conf - ``` + +3. Clear `percona_pg_telemetry` from the `shared_preload_libraries` configuration parameter in the `postgresql.conf` file: -3. Remove `percona_pg_telemetry` from the `shared_preload_libraries` configuration parameter: - - ```sql - ALTER SYSTEM SET shared_preload_libraries = ''; + ```bash + #... + shared_preload_libraries = '' + #... ``` !!! important @@ -389,6 +391,6 @@ To disable the Metrics File creation, stop and drop the `percona_pg_telemetry` e If you wish to re-enable the Telemetry Subsystem, complete the above steps in the reverse order: - 1. Add the `percona_pg_telemetry` to the `shared_preload_libraries`, + 1. Add the `percona_pg_telemetry` to the `shared_preload_libraries` in the `postgresql.conf` file, 2. Set `percona_pg_telemetry.enabled` to `1`, and 3. Restart the PostgreSQL server. From 4fd3a48fc9f3689f85e913159573f3ec4214d5dd Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Fri, 18 Jul 2025 09:49:41 +0300 Subject: [PATCH 5/7] update step 3 with auto.conf file mention --- docs/telemetry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/telemetry.md b/docs/telemetry.md index 2d5b2b0a9..e37b52e5b 100644 --- a/docs/telemetry.md +++ b/docs/telemetry.md @@ -361,7 +361,7 @@ To disable the Metrics File creation, stop and drop the `percona_pg_telemetry` e DROP EXTENSION percona_pg_telemetry; ``` -3. Clear `percona_pg_telemetry` from the `shared_preload_libraries` configuration parameter in the `postgresql.conf` file: +3. Clear `percona_pg_telemetry` from the `shared_preload_libraries` configuration parameter in the `postgresql.conf` file and the `postgresql.auto.conf` file (if it exists): ```bash #... From 1bb29ffd6dd82cb73662700203503dd63abf86b2 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Fri, 18 Jul 2025 14:27:47 +0300 Subject: [PATCH 6/7] Delete docs/release-notes-v17.5 copy.md delete wrongly committed file --- docs/release-notes-v17.5 copy.md | 50 -------------------------------- 1 file changed, 50 deletions(-) delete mode 100644 docs/release-notes-v17.5 copy.md diff --git a/docs/release-notes-v17.5 copy.md b/docs/release-notes-v17.5 copy.md deleted file mode 100644 index b2eb30ea3..000000000 --- a/docs/release-notes-v17.5 copy.md +++ /dev/null @@ -1,50 +0,0 @@ -# Percona Distribution for PostgreSQL 17.5.2 ({{date.17_5}}) - ---8<-- "release-notes-intro.md" - -This release of Percona Distribution for PostgreSQL is based on Percona Server for PostgreSQL 17.5.2 - a binary compatible, open source drop in replacement of [PostgreSQL Community 17.5](https://www.postgresql.org/docs/17/release-17-5.html). - -## Release Highlights - -### General Availability (GA) of pg_tde - -Percona Distribution for PostgreSQL now includes the 1.0 GA release of Percona's Transparent Data Encryption for PostgreSQL. - -Learn more in the [`pg_tde` 1.0 release notes :octicons-link-external-16:](https://docs.percona.com/pg-tde/release-notes/release-notes-v1.0.html). - -### Major documentation update - -The `pg_tde` documentation has received significant updates, which include: - -- New KMS configuration guides for Fortanix, Vault, KMIP and OpenBAO -- Reorganized and expanded topics for Architecture, GUC, Functions, TDE Operations and FAQ -- Extensive and numerous refinements and clarifications across the entire site - -Explore the full documentation [in the official `pg_tde` documentations](https://docs.percona.com/pg-tde/index.html). - -The following is the list of extensions available in Percona Distribution for PostgreSQL. - -| Extension | Version | Description | -|--------------------------------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------| -| [etcd :octicons-link-external-16:](https://etcd.io/) | 3.5.21 | A distributed, reliable key-value store for setting up high available Patroni clusters | -| [HAProxy :octicons-link-external-16:](http://www.haproxy.org/) | 2.8.15 | A high-availability and load-balancing solution | -| [Patroni :octicons-link-external-16:](https://patroni.readthedocs.io/en/latest/) | 4.0.5 | A HA (High Availability) solution for PostgreSQL | -| [PgAudit :octicons-link-external-16:](https://www.pgaudit.org/) | 17.1 | Provides detailed session or object audit logging via the standard logging facility provided by PostgreSQL | -| [pgAudit set_user :octicons-link-external-16:](https://github.com/pgaudit/set_user) | 4.1.0 | Provides an additional layer of logging and control when unprivileged users must escalate roles for maintenance. | -| [pgBackRest :octicons-link-external-16:](https://pgbackrest.org/) | 2.55.0 | A backup and restore solution for PostgreSQL | -| [pgBadger :octicons-link-external-16:](https://github.com/darold/pgbadger) | 13.1 | A fast PostgreSQL Log Analyzer | -| [PgBouncer :octicons-link-external-16:](https://www.pgbouncer.org/) | 1.24.1 | A lightweight connection pooler for PostgreSQL | -| [pg_gather :octicons-link-external-16:](https://github.com/jobinau/pg_gather) | v30 | An SQL script for running the diagnostics of the health of a PostgreSQL cluster | -| [pgpool2 :octicons-link-external-16:](https://git.postgresql.org/gitweb/?p=pgpool2.git;a=summary) | 4.6.0 | A middleware between PostgreSQL server and client for high availability, connection pooling, and load balancing | -| [pg_repack :octicons-link-external-16:](https://github.com/reorg/pg_repack) | 1.5.2 | Rebuilds PostgreSQL database objects | -| [pg_stat_monitor](https://github.com/percona/pg_stat_monitor) | 2.2.0 | collects and aggregates statistics for PostgreSQL and provides histogram information. | -| [pgvector :octicons-link-external-16:](https://github.com/pgvector/pgvector) | v0.8.0 | A vector similarity search for PostgreSQL | -| [PostGIS :octicons-link-external-16:](https://github.com/postgis/postgis) | 3.3.8 | A spatial extension for PostgreSQL | -| [PostgreSQL Common :octicons-link-external-16:](https://salsa.debian.org/postgresql/postgresql-common) | 277 | PostgreSQL database-cluster manager. Supports multiple PostgreSQL versions and clusters simultaneously | -| [wal2json :octicons-link-external-16:](https://github.com/eulerto/wal2json) | 2.6 | A PostgreSQL logical decoding JSON output plugin | - -For Red Hat Enterprise Linux 8 and compatible derivatives, Percona Distribution for PostgreSQL also includes the supplemental `python3-etcd` 0.4.5 packages, which are used for setting up Patroni clusters. - -Percona Distribution for PostgreSQL is also shipped with the [libpq](https://www.postgresql.org/docs/17/libpq.html) library. It contains "a set of -library functions that allow client programs to pass queries to the PostgreSQL -backend server and to receive the results of these queries." From 18a4a69d7c76d5ff53a1a753173165815f94dfb7 Mon Sep 17 00:00:00 2001 From: Dragos Andriciuc Date: Fri, 18 Jul 2025 14:35:24 +0300 Subject: [PATCH 7/7] update step 3 bash to conf block type --- docs/telemetry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/telemetry.md b/docs/telemetry.md index e37b52e5b..3e4c13c32 100644 --- a/docs/telemetry.md +++ b/docs/telemetry.md @@ -363,7 +363,7 @@ To disable the Metrics File creation, stop and drop the `percona_pg_telemetry` e 3. Clear `percona_pg_telemetry` from the `shared_preload_libraries` configuration parameter in the `postgresql.conf` file and the `postgresql.auto.conf` file (if it exists): - ```bash + ```conf #... shared_preload_libraries = '' #...