https://github.com/percona/percona_pg_telemetry
Percona telemetry extension for PostgreSQL
https://github.com/percona/percona_pg_telemetry
percona percona-distribution pg postgresql telemetry telemetry-collection
Last synced: 11 months ago
JSON representation
Percona telemetry extension for PostgreSQL
- Host: GitHub
- URL: https://github.com/percona/percona_pg_telemetry
- Owner: percona
- License: mit
- Created: 2024-03-27T22:21:51.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-07-18T10:24:32.000Z (11 months ago)
- Last Synced: 2025-07-18T10:32:39.941Z (11 months ago)
- Topics: percona, percona-distribution, pg, postgresql, telemetry, telemetry-collection
- Language: C
- Homepage: https://docs.percona.com/postgresql/17/telemetry.html
- Size: 148 KB
- Stars: 2
- Watchers: 8
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: code-of-conduct.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[](https://github.com/Percona-Lab/percona_pg_telemetry/actions/workflows/postgresql-12-build.yml)
[](https://github.com/Percona-Lab/percona_pg_telemetry/actions/workflows/postgresql-13-build.yml)
[](https://github.com/Percona-Lab/percona_pg_telemetry/actions/workflows/postgresql-14-build.yml)
[](https://github.com/Percona-Lab/percona_pg_telemetry/actions/workflows/postgresql-15-build.yml)
[](https://github.com/Percona-Lab/percona_pg_telemetry/actions/workflows/postgresql-16-build.yml)
[](https://github.com/Percona-Lab/percona_pg_telemetry/actions/workflows/postgresql-17-build.yml)
[](https://scorecard.dev/viewer/?uri=github.com/percona/percona_pg_telemetry)
[](https://forums.percona.com/)
# Percona Telemetry Extension for PostgreSQL
Welcome to `percona_pg_telemetry` - extension for Percona telemetry data collection for PostgreSQL!
## Overview
The extenions it be provided with the Percona distribution. The extension, at no point in time, collects, maintains, or sends any user personal/identifiable/sensitive data.
### Configuration
You can find the configuration parameters of the `percona_pg_telemetry` extension in the `pg_settings` view by filtering `name` column with `percona_pg_telemetry` prefix. To change the default configuration, specify new values for the desired parameters using the GUC (Grand Unified Configuration) system. Alternatively, values may be changed by a superuser either at the server start time or via `ALTER SYSTEM` command followed `SELECT pg_reload_conf();` statement.
#### Parameters
1. `percona_pg_telemetry.enabled`
* Default: true
* Unit: boolean
* When set to `false`, the leader process terminates when the configuration is read.
2. `percona_pg_telemetry.path`
* Default: /usr/local/percona/telemetry/pg
3. `percona_pg_telemetry.scrape_interval`
* Default: 86,400 (24 hours)
* Unit: s
* It is configured to wakeup the leader process every 24 hours by default. The leader
may be woken up by a configuration reload interrupt or when the shutdown process is
initiated.
4. `percona_pg_telemetry.files_to_keep`
* Default: 7
* Unit: Integer
* It forces the extension to maintain upto this number of files. Older files will get
removed and new files will be created.
> **NOTE** GUCs 3 - 4 are only visible if environment variable PT_DEBUG is set. This is prevent users in production environment to change these variables which are only for testing purposes.
#### Functions
1. `percona_pg_telemetry_version()`
* Outputs the version of the extension.
2. `percona_pg_telemetry_status()`
* OUT: latest_output_filename - TEXT
- Path of the JSON output file.
* OUT: pt_enabled - BOOLEAN
- True if telemetry data collection is enabled.
> **NOTE** Functions are only visible after you have created the extension using the 'CREATE EXTENSION percona_pg_telemetry;' command.
### Setup
You can enable `percona_pg_telemetry` when your `postgresql` instance is not running.
`percona_pg_telemetry` needs to be loaded at the start time. The extension requires additional shared memory; therefore, add the `percona_pg_telemetry` value for the `shared_preload_libraries` parameter and restart the `postgresql` instance.
Use the [ALTER SYSTEM](https://www.postgresql.org/docs/current/sql-altersystem.html) command from `psql` terminal to modify the `shared_preload_libraries` parameter.
```sql
ALTER SYSTEM SET shared_preload_libraries = 'percona_pg_telemetry';
```
> **NOTE**: If you’ve added other modules to the `shared_preload_libraries` parameter (for example, `pg_stat_monitor`), list all of them separated by commas for the `ALTER SYSTEM` command.
Start or restart the `postgresql` instance to apply the changes.
Create the extension using the [CREATE EXTENSION](https://www.postgresql.org/docs/current/sql-createextension.html) command. Using this command requires the privileges of a superuser or a database owner. Connect to `psql` as a superuser for a database and run the following command:
```sql
CREATE EXTENSION percona_pg_telemetry;
```
This allows you to see the stats collected by `percona_pg_telemetry`.
By default, `percona_pg_telemetry` is created for the `postgres` database. To access its functions in other databases, you need to create the extension for every required database.
### Building from source
To build `percona_pg_telemetry` from source code, you require the following:
* git
* make
* gcc
* postgresql-devel | postgresql-server-dev-all
You can download the source code of the latest release of `percona_pg_telemetry` from [the releases page on GitHub](https://github.com/percona/percona_pg_telemetry/releases) or using git:
```
git clone git://github.com/percona/percona_pg_telemetry.git
```
Compile and install the extension
```
cd percona_pg_telemetry
make
make install
```
To run the associated regression tests, a make target is available. ```make installcheck``` is deliberately disabled as the preload configuration may not be set for installed servers.
```
make check
```
### Uninstall `percona_pg_telemetry`
To uninstall `percona_pg_telemetry`, do the following:
1. Disable telemetry data collection. From the `psql` terminal or another similar client, run the following command:
```sql
ALTER SYSTEM SET percona_pg_telemetry.enabled = 0;
SELECT pg_reload_conf();
```
**NOTE**: This will cause the leader process to exit. To restart the leader process, ensure that `percona_pg_telemetry.enabled = 1`, and then restart the database server process.
2. Drop `percona_pg_telemetry` extension:
```sql
DROP EXTENSION percona_pg_telemetry;
```
3. Remove `percona_pg_telemetry` from the `shared_preload_libraries` configuration parameter:
```sql
ALTER SYSTEM SET shared_preload_libraries = '';
```
**Important**: If the `shared_preload_libraries` parameter includes other modules, specify them all for the `ALTER SYSTEM SET` command to keep using them.
4. Restart the `postgresql` instance to apply the changes.