Skip to content

DOCS-182 Update telemetry steps and commands PG17 #824

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jul 18, 2025
Merged

DOCS-182 Update telemetry steps and commands PG17 #824

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
92e54cc
fix indentations
Andriciuc Jul 16, 2025
c19e743
update docker command for disabling telemetry
Andriciuc Jul 17, 2025
a2d1cf9
add example output for removing telemetry and fix indentations for ag…
Andriciuc Jul 17, 2025
338c06c
update step 2 and 3 to edit correct file parameter
Andriciuc Jul 17, 2025
4fd3a48
update step 3 with auto.conf file mention
Andriciuc Jul 18, 2025
1bb29ff
Delete docs/release-notes-v17.5 copy.md
Andriciuc Jul 18, 2025
18a4a69
update step 3 bash to conf block type
Andriciuc Jul 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
210 changes: 109 additions & 101 deletions docs/telemetry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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.

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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:<TAG>-multi
docker pull percona/percona-distribution-postgresql:<TAG>-multi
```

The command does the following:
Expand All @@ -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:<TAG>-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.
Expand Down Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -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.