Skip to content

Commit 2e58a44

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 2e58a44

1 file changed

Lines changed: 206 additions & 17 deletions

File tree

‎docs/telemetry.md‎

Lines changed: 206 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,28 @@
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+
See also: [Telemetry and data collection — Percona Server for MySQL 8.0 :octicons-link-external-16:](https://docs.percona.com/percona-server/8.0/telemetry.html).
16+
17+
## Why telemetry matters
18+
19+
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.
20+
21+
## Installation-time telemetry
22+
23+
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.
24+
25+
### Installation-time telemetry file example
1226

1327
```json
1428
[{"id" : "c416c3ee-48cd-471c-9733-37c2886f8231",
@@ -17,35 +31,210 @@ An example of the data collected is the following:
1731
"createTime" : "2023-10-16T10:46:23Z",
1832
"metrics":
1933
[{"key" : "deployment","value" : "PACKAGE"},
20-
{"key" : "pillar_version","value" : "8.1.0-1"},
34+
{"key" : "pillar_version","value" : "8.0.35-27"},
2135
{"key" : "OS","value" : "Oracle Linux Server 8.8"},
2236
{"key" : "hardware_arch","value" : "x86_64 x86_64"}]}]
2337
```
2438

25-
## Disable telemetry
39+
### Disable installation-time telemetry
2640

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.
41+
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.
2842

2943
=== "Debian-derived distribution"
3044

31-
Add the environment variable before the install process.
32-
3345
```shell
3446
sudo PERCONA_TELEMETRY_DISABLE=1 apt install percona-server-server
3547
```
3648

3749
=== "Red Hat-derived distribution"
3850

39-
Add the environment variable before the install process.
40-
4151
```shell
4252
sudo PERCONA_TELEMETRY_DISABLE=1 yum install percona-server-server
4353
```
4454

45-
=== "DOCKER"
55+
=== "Docker"
56+
57+
```shell
58+
docker run -d -e MYSQL_ROOT_PASSWORD=test1234# -e PERCONA_TELEMETRY_DISABLE=1 --name=percona-server percona/percona-server:8.1
59+
```
60+
61+
## Continuous telemetry
62+
63+
Continuous telemetry uses a telemetry agent and a database component. It collects information and sends it daily (after an initial period—see below).
64+
65+
### Elements of the continuous telemetry system
66+
67+
| Piece | Role |
68+
| ----- | ---- |
69+
| Percona Telemetry DB component | Collects metrics inside the server and writes them to a metrics file on disk. |
70+
| Metrics file | JSON file on the host filesystem holding collected metrics. |
71+
| 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. |
72+
73+
On the Percona Platform side:
74+
75+
| Piece | Role |
76+
| ----- | ---- |
77+
| Telemetry Service | API endpoint that receives telemetry and stores it. |
78+
| Telemetry Storage | Long-term storage for telemetry data. |
79+
80+
### Overview of the DB component
81+
82+
Percona Server for MySQL installs a DB component by default (source integration or modular `component_percona_telemetry`). It:
83+
84+
- Collects database metrics daily
85+
- Writes a new timestamped `.json` file under the telemetry directory
86+
- Keeps roughly one week of metrics files (older files are removed before creating new ones)
87+
88+
The DB component does not collect:
89+
90+
- Database names
91+
- User names or credentials
92+
- Application or user data
93+
94+
### Locations of metrics files and telemetry history
95+
96+
Root for host telemetry: `/usr/local/percona/telemetry`
97+
98+
Product-specific paths (prepend the root):
99+
100+
| Product | Path |
101+
| ------- | ---- |
102+
| Percona Server for MySQL | `${telemetry root}/ps/` |
103+
| Percona Server for MongoDB (`mongod`) | `${telemetry root}/psmdb/` |
104+
| Percona Server for MongoDB (`mongos`) | `${telemetry root}/psmdbs/` |
105+
| Percona XtraDB Cluster | `${telemetry root}/pxc/` |
106+
| PostgreSQL products | `${telemetry root}/pg/` |
107+
108+
Archived copies after successful sends: `${telemetry root}/history/`
109+
110+
### Metrics file format
111+
112+
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):
113+
114+
```json
115+
{
116+
"db_instance_id": "e83c568c-e140-11ee-8320-7e207666b18a",
117+
"pillar_version": "8.0.35-27",
118+
"active_plugins": [
119+
"binlog",
120+
"mysql_native_password",
121+
"InnoDB",
122+
"PERFORMANCE_SCHEMA"
123+
],
124+
"active_components": [
125+
"file://component_percona_telemetry"
126+
],
127+
"uptime": "6185",
128+
"databases_count": "7",
129+
"databases_size": "33149",
130+
"se_engines_in_use": [
131+
"InnoDB",
132+
"ROCKSDB"
133+
],
134+
"replication_info": {
135+
"is_semisync_source": "1",
136+
"is_replica": "1"
137+
}
138+
}
139+
```
140+
141+
### Percona telemetry agent
142+
143+
The `percona-telemetry-agent` runs on the database host. It manages JSON files under the telemetry root path.
144+
145+
- Log file: `/var/log/percona/telemetry-agent.log`
146+
- First 24 hours: no collection or upload
147+
- After that: attempts to send daily; on failure, retries up to five times
148+
- After a successful send, it stores a copy under `history/` and deletes the original file produced by the database
149+
- If the telemetry directory lacks the expected Percona-related files, nothing is sent
150+
151+
#### Telemetry agent payload example
152+
153+
```json
154+
{
155+
"reports": [
156+
{
157+
"id": "B5BDC47B-B717-4EF5-AEDF-41A17C9C18BB",
158+
"createTime": "2023-09-01T10:56:49Z",
159+
"instanceId": "B5BDC47B-B717-4EF5-AEDF-41A17C9C18BA",
160+
"productFamily": "PRODUCT_FAMILY_PS",
161+
"metrics": [
162+
{
163+
"key": "OS",
164+
"value": "Ubuntu"
165+
},
166+
{
167+
"key": "pillar_version",
168+
"value": "8.0.33-25"
169+
}
170+
]
171+
}
172+
]
173+
}
174+
```
175+
176+
| Field | Description |
177+
| ----- | ----------- |
178+
| `id` | Random UUID v4 for the request |
179+
| `createTime` | Timestamp |
180+
| `instanceId` | DB host ID from metrics/`telemetry_uuid`, or a generated UUID v4 if missing |
181+
| `productFamily` | Derived from file path (e.g. `PRODUCT_FAMILY_PS`) |
182+
| `metrics` | Key/value pairs from the metrics file |
183+
184+
OS-level metrics included with checks can include:
185+
186+
| Key | Description |
187+
| --- | ----------- |
188+
| `OS` | Operating system name |
189+
| `hardware_arch` | CPU architecture |
190+
| `deployment` | e.g. `PACKAGE` or `DOCKER` |
191+
| `installed_packages` | Installed Percona-related packages (name, version, repository when available) |
192+
193+
Reported package names typically match patterns such as: `percona-*`, `Percona-*`, `proxysql*`, `pmm`, `etcd*`, `haproxy`, `patroni`, `pg*`, `postgis`, `wal2json`, and similar.
194+
195+
## Disable continuous telemetry
196+
197+
Continuous telemetry is enabled by default. To turn it off completely:
198+
199+
1. Stop and disable the telemetry agent service.
200+
2. Uninstall the DB telemetry component and set `percona_telemetry_disable=1` so it does not reload on restart.
201+
202+
These steps do not affect installation-time telemetry (that is controlled with `PERCONA_TELEMETRY_DISABLE` at install time).
203+
204+
### Disable the telemetry agent
205+
206+
=== "Temporarily (until next reboot)"
207+
208+
```shell
209+
systemctl stop percona-telemetry-agent
210+
```
211+
212+
=== "Permanently"
46213

47-
Add the environment variable when running a command in a new container.
48-
49214
```shell
50-
docker run -d -e MYSQL_ROOT_PASSWORD=test1234# -e PERCONA_TELEMETRY_DISABLE=1 -e --name=percona-server percona/percona-server:8.1
215+
systemctl disable percona-telemetry-agent
51216
```
217+
218+
#### Agent dependencies and removal
219+
220+
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.
221+
222+
- YUM: Removing the last package that depended on the agent may remove the agent package.
223+
- APT: Use `apt autoremove` where appropriate; APT may not remove the agent automatically when you remove only the server package.
224+
225+
### Disable the DB component
226+
227+
Even with the agent stopped, the component can still write metrics files for about seven days. Uninstall the component without restarting the server:
228+
229+
```sql
230+
UNINSTALL COMPONENT "file://component_percona_telemetry";
231+
```
232+
233+
Restarting the server after uninstall can reload telemetry if configuration still loads the component. To keep telemetry disabled across restarts, add to `my.cnf`:
234+
235+
```ini
236+
[mysqld]
237+
percona_telemetry_disable=1
238+
```
239+
240+
Then restart the server.

0 commit comments

Comments
 (0)