diff --git a/docs/telemetry.md b/docs/telemetry.md index 2ac49ba9..3e4c13c3 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 @@ -100,77 +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" + }, + { + "key": "boot_val", + "value": "off" + } + ] + }, + ... + ], + "databases": [ + { + "key": "database", + "value": [ + { + "key": "database_oid", + "value": "5" + }, + { + "key": "database_size", + "value": "7820895" + }, { - "db_instance_id": "7310358902660071382", - "pillar_version": "17.0", - "uptime": "36", - "databases_count": "2", - "settings": [ + "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 @@ -180,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. @@ -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 @@ -285,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: @@ -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. @@ -347,16 +345,28 @@ To disable the Metrics File creation, stop and drop the `percona_pg_telemetry` e SELECT pg_reload_conf(); ``` + ??? example "Example output" + + ```sql + ALTER SYSTEM + pg_reload_conf + ---------------- + t + (1 row) + ``` + 2. Remove the `percona_pg_telemetry` extension from the database: - + ```sql DROP EXTENSION percona_pg_telemetry; ``` + +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): -3. Remove `percona_pg_telemetry` from the `shared_preload_libraries` configuration parameter: - - ```sql - ALTER SYSTEM SET shared_preload_libraries = ''; + ```conf + #... + shared_preload_libraries = '' + #... ``` !!! important @@ -371,18 +381,16 @@ 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: - 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.