Skip to content

Commit 295a099

Browse files
patrickbirchpatrickbirch
committed
PS-10920 [DOCS] - [feedback] PS 8.4 telemetry disabling. no comment, one star rating
 modified: docs/telemetry.md
1 parent 7033b24 commit 295a099

1 file changed

Lines changed: 220 additions & 20 deletions

File tree

‎docs/telemetry.md‎

Lines changed: 220 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,251 @@
1-
# Telemetry on Percona Server for MySQL
1+
# Telemetry and data collection
22

3-
Percona telemetry fills in the gaps in our understanding of how you use Percona Server for MySQL to improve our products. Participation in the anonymous program is optional. You can opt-out if you prefer to not share this information.
3+
Percona has two kinds of telemetry for Percona Server for MySQL:
44

5-
## What information is collected
5+
* Installation-time telemetry — runs once at install or container startup.
66

7-
At this time, telemetry is added only to the Percona packages and Docker images. Percona Server for MySQL collects only information about the installation environment. Future releases may add additional metrics.
7+
* Continuous telemetry — a DB component plus a host agent that collect and send metrics on a schedule.
88

9-
Be assured that access to this raw data is rigorously controlled. Percona does not collect personal data. All data is anonymous and cannot be traced to a specific user. To learn more about our privacy practices, read our [Percona Privacy statement :octicons-link-external-16:](https://www.percona.com/privacy-policy#h.e34c40q8sb1a).
9+
You control whether to share this information. The program is optional: you can disable either or both systems if you do not want to share anonymous data.
1010

11-
An example of the data collected is the following:
11+
Percona does not gather personal information. All collected data is anonymous and cannot be used to identify individual users or servers. Details: [Percona Privacy policy :octicons-link-external-16:](https://www.percona.com/privacy-policy#h.e34c40q8sb1a).
12+
13+
Telemetry is included in Percona software packages, compressed archives (tarballs), and Docker images. Continuous telemetry from tarballs needs the telemetry agent and a writable telemetry directory.
14+
15+
## Why telemetry matters
16+
17+
Telemetry helps Percona see how the software is used, spot bugs and performance issues early, and prioritize fixes and features. In turn, users benefit from faster fixes, more relevant improvements, and a more stable product over time.
18+
19+
## Installation-time telemetry
20+
21+
This telemetry runs only once during software installation or Docker container startup. It collects system configuration, hardware, software version, and environment details at that moment, then does not run again.
22+
23+
### Installation-time telemetry file example
1224

1325
```json
1426
[{"id" : "c416c3ee-48cd-471c-9733-37c2886f8231",
1527
"product_family" : "PRODUCT_FAMILY_PS",
1628
"instanceId" : "6aef422e-56a7-4530-af9d-94cc02198343",
17-
"createTime" : "2023-10-16T10:46:23Z",
29+
"createTime" : "2026-03-26T15:43:18Z",
1830
"metrics":
1931
[{"key" : "deployment","value" : "PACKAGE"},
20-
{"key" : "pillar_version","value" : "8.1.0-1"},
21-
{"key" : "OS","value" : "Oracle Linux Server 8.8"},
32+
{"key" : "pillar_version","value" : "{{release}}"},
33+
{"key" : "OS","value" : "Oracle Linux Server 9"},
2234
{"key" : "hardware_arch","value" : "x86_64 x86_64"}]}]
2335
```
2436

25-
## Disable telemetry
37+
### Disable installation-time telemetry
2638

27-
Telemetry is enabled by default. If you decide not to send usage data to Percona, you can set the `PERCONA_TELEMETRY_DISABLE=1` environment variable for either the root user or in the operating system prior to the installation process.
39+
This feature is enabled by default. To disable it, set `PERCONA_TELEMETRY_DISABLE=1` for the root user or in the environment before installing. This does not turn off continuous telemetry.
2840

2941
=== "Debian-derived distribution"
3042

31-
Add the environment variable before the install process.
32-
3343
```shell
3444
sudo PERCONA_TELEMETRY_DISABLE=1 apt install percona-server-server
3545
```
3646

3747
=== "Red Hat-derived distribution"
3848

39-
Add the environment variable before the install process.
40-
4149
```shell
42-
sudo PERCONA_TELEMETRY_DISABLE=1 yum install percona-server-server
50+
sudo PERCONA_TELEMETRY_DISABLE=1 dnf install percona-server-server
4351
```
4452

45-
=== "DOCKER"
53+
=== "Docker"
4654

47-
Add the environment variable when running a command in a new container.
48-
4955
```shell
50-
docker run -d -e MYSQL_ROOT_PASSWORD=test1234# -e PERCONA_TELEMETRY_DISABLE=1 -e --name=percona-server percona/percona-server:8.1
56+
docker run -d -e MYSQL_ROOT_PASSWORD=test1234# -e PERCONA_TELEMETRY_DISABLE=1 --name=percona-server percona/percona-server:8.4
5157
```
58+
59+
## Continuous telemetry
60+
61+
Continuous telemetry uses a telemetry agent and a database component. It collects information and sends it daily (after an initial period—see below).
62+
63+
### Elements of the continuous telemetry system
64+
65+
| Piece | Role |
66+
| ----- | ---- |
67+
| Percona Telemetry DB component | Collects metrics inside the server and writes them to a metrics file on disk. |
68+
| Metrics file | JSON file on the host filesystem holding collected metrics. |
69+
| Telemetry agent (`percona-telemetry-agent`) | OS-level process: collects OS metrics, reads the metrics file, merges data, sends to Percona Platform, and records installed Percona packages via the local package manager. |
70+
71+
On the Percona Platform side:
72+
73+
| Piece | Role |
74+
| ----- | ---- |
75+
| Telemetry Service | API endpoint that receives telemetry and stores it. |
76+
| Telemetry Storage | Long-term storage for telemetry data. |
77+
78+
### Overview of the DB component
79+
80+
Percona Server for MySQL installs a DB component by default (source integration or modular `component_percona_telemetry`).
81+
82+
The DB component:
83+
84+
* Collects database metrics daily
85+
86+
* Writes a new timestamped `.json` file under the telemetry directory
87+
88+
* Keeps roughly one week of metrics files (older files are removed before creating new ones)
89+
90+
The DB component does not collect:
91+
92+
* Database names
93+
94+
* User names or credentials
95+
96+
* Application or user data
97+
98+
### Locations of metrics files and telemetry history
99+
100+
Root for host telemetry: `/usr/local/percona/telemetry`
101+
102+
Product-specific paths (prepend the root):
103+
104+
| Product | Path |
105+
| ------- | ---- |
106+
| Percona Server for MySQL | `${telemetry root}/ps/` |
107+
| Percona Server for MongoDB (`mongod`) | `${telemetry root}/psmdb/` |
108+
| Percona Server for MongoDB (`mongos`) | `${telemetry root}/psmdbs/` |
109+
| Percona XtraDB Cluster | `${telemetry root}/pxc/` |
110+
| PostgreSQL products | `${telemetry root}/pg/` |
111+
112+
Archived copies after successful sends: `${telemetry root}/history/`
113+
114+
### Metrics file format
115+
116+
Files are JSON. Percona may extend the schema over time. Example (structure as shipped in upstream docs; `active_plugins` and similar lists may be long in real files):
117+
118+
```json
119+
{
120+
"db_instance_id": "e83c568c-e140-11ee-8320-7e207666b18a",
121+
"pillar_version": "{{release}}",
122+
"active_plugins": [
123+
"binlog",
124+
"caching_sha2_password",
125+
"InnoDB",
126+
"PERFORMANCE_SCHEMA"
127+
],
128+
"active_components": [
129+
"file://component_percona_telemetry"
130+
],
131+
"uptime": "6185",
132+
"databases_count": "7",
133+
"databases_size": "33149",
134+
"se_engines_in_use": [
135+
"InnoDB"
136+
],
137+
"replication_info": {
138+
"is_semisync_source": "1",
139+
"is_replica": "1"
140+
}
141+
}
142+
```
143+
144+
### Percona telemetry agent
145+
146+
The `percona-telemetry-agent` runs on the database host. It manages JSON files under the telemetry root path.
147+
148+
- Log file: `/var/log/percona/telemetry-agent.log`
149+
- First 24 hours: no collection or upload
150+
- After that: attempts to send daily; on failure, retries up to five times
151+
- After a successful send, it stores a copy under `history/` and deletes the original file produced by the database
152+
- If the telemetry directory lacks the expected Percona-related files, nothing is sent
153+
154+
#### Telemetry agent payload example
155+
156+
```json
157+
{
158+
"reports": [
159+
{
160+
"id": "B5BDC47B-B717-4EF5-AEDF-41A17C9C18BB",
161+
"createTime": "2026-03-26T15:44:54Z",
162+
"instanceId": "B5BDC47B-B717-4EF5-AEDF-41A17C9C18BA",
163+
"productFamily": "PRODUCT_FAMILY_PS",
164+
"metrics": [
165+
{
166+
"key": "OS",
167+
"value": "Ubuntu"
168+
},
169+
{
170+
"key": "pillar_version",
171+
"value": "{{release}}"
172+
}
173+
]
174+
}
175+
]
176+
}
177+
```
178+
179+
| Field | Description |
180+
| ----- | ----------- |
181+
| `id` | Random UUID v4 for the request |
182+
| `createTime` | Timestamp |
183+
| `instanceId` | DB host ID from metrics/`telemetry_uuid`, or a generated UUID v4 if missing |
184+
| `productFamily` | Derived from file path (e.g. `PRODUCT_FAMILY_PS`) |
185+
| `metrics` | Key/value pairs from the metrics file |
186+
187+
OS-level metrics included with checks can include:
188+
189+
| Key | Description |
190+
| --- | ----------- |
191+
| `OS` | Operating system name |
192+
| `hardware_arch` | CPU architecture |
193+
| `deployment` | e.g. `PACKAGE` or `DOCKER` |
194+
| `installed_packages` | Installed Percona-related packages (name, version, repository when available) |
195+
196+
Reported package names typically match patterns such as: `percona-*`, `Percona-*`, `proxysql*`, `pmm`, `etcd*`, `haproxy`, `patroni`, `pg*`, `postgis`, `wal2json`, and similar.
197+
198+
## Disable continuous telemetry
199+
200+
Continuous telemetry is enabled by default. To turn it off completely, use this order of operations:
201+
202+
1. Add `percona_telemetry_disable=1` under `[mysqld]` in `my.cnf` (or your included option file), then restart the server so the setting is active. Do this before relying on `UNINSTALL COMPONENT` alone: after a restart, the server can load telemetry again if this variable is not set, even if you had uninstalled the component earlier.
203+
2. Run `UNINSTALL COMPONENT "file://component_percona_telemetry";` so the server stops writing telemetry metrics files.
204+
3. Stop and disable the `percona-telemetry-agent` service so no data is sent from the host.
205+
206+
These steps do not affect installation-time telemetry (that is controlled with `PERCONA_TELEMETRY_DISABLE` at install time).
207+
208+
### Disable the telemetry agent
209+
210+
=== "Temporarily (until next reboot)"
211+
212+
```shell
213+
systemctl stop percona-telemetry-agent
214+
```
215+
216+
=== "Permanently"
217+
218+
```shell
219+
systemctl disable percona-telemetry-agent
220+
```
221+
222+
#### Agent dependencies and removal
223+
224+
The telemetry agent is a mandatory dependency of Percona Server for MySQL packages. Removing the agent can remove or break the database package on some systems—check your package manager behavior before removing.
225+
226+
* DNF: Removing the last package that depended on the agent may remove the agent package.
227+
228+
* APT: Use `apt autoremove` where appropriate; APT may not remove the agent automatically when you remove only the server package.
229+
230+
### Disable the DB component
231+
232+
Even with the agent stopped, the component can still write metrics files for about seven days until you uninstall it.
233+
234+
Use `UNINSTALL COMPONENT` after you have set `percona_telemetry_disable=1` and restarted (see the ordered steps above). Uninstalling alone does not guarantee telemetry stays off when the server restarts.
235+
236+
```sql
237+
UNINSTALL COMPONENT "file://component_percona_telemetry";
238+
```
239+
240+
`my.cnf` should already contain the following from step 1; if you have not added it yet, add it and restart:
241+
242+
```ini
243+
[mysqld]
244+
percona_telemetry_disable=1
245+
```
246+
247+
## Related reading
248+
249+
* [Install Percona Server for MySQL](installation.md)
250+
* [Running Percona Server for MySQL in a Docker container](docker.md)
251+
* [UNINSTALL COMPONENT](uninstall-component.md)

0 commit comments

Comments
 (0)