percona · patrickbirch · Mar 20, 2026
diff --git a/docs/_static/percona-telemetry.png b/docs/_static/percona-telemetry.png
diff --git a/docs/telemetry.md b/docs/telemetry.md
@@ -1,51 +1,253 @@
-# Telemetry on Percona Server for MySQL
+# Telemetry and data collection
 
-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.
+Percona has two kinds of telemetry for Percona Server for MySQL:
 
-## What information is collected
+* Installation-time telemetry — runs once at install or container startup.
 
-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.
+* Continuous telemetry — a DB component and a host agent that collect and send metrics on a schedule.
 
-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).
+You control whether to share telemetry data. The program is optional: you can disable either or both systems if you do not want to share anonymous data.
 
-An example of the data collected is the following:
+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).
+
+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.
+
+## Why telemetry matters
+
+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.
+
+## Installation-time telemetry
+
+Installation-time telemetry runs only once during software installation or Docker container startup. Installation-time telemetry collects system configuration, hardware, software version, and environment details during installation or container startup, then does not run again.
+
+### Installation-time telemetry file example
 
 ```json
 [{"id" : "c416c3ee-48cd-471c-9733-37c2886f8231",
 "product_family" : "PRODUCT_FAMILY_PS",
 "instanceId" : "6aef422e-56a7-4530-af9d-94cc02198343",
-"createTime" : "2023-10-16T10:46:23Z",
+"createTime" : "2026-03-26T15:43:18Z",
 "metrics":
 [{"key" : "deployment","value" : "PACKAGE"},
-{"key" : "pillar_version","value" : "8.1.0-1"},
-{"key" : "OS","value" : "Oracle Linux Server 8.8"},
+{"key" : "pillar_version","value" : "{{release}}"},
+{"key" : "OS","value" : "Oracle Linux Server 9"},
 {"key" : "hardware_arch","value" : "x86_64 x86_64"}]}]
 ```
 
-## Disable telemetry
+### Disable installation-time telemetry
 
-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.
+Installation-time telemetry is enabled by default. To disable installation-time telemetry, set `PERCONA_TELEMETRY_DISABLE=1` for the root user or in the environment before installing. Disabling installation-time telemetry does not turn off continuous telemetry.
 
 === "Debian-derived distribution"
 
-    Add the environment variable before the install process.
-
     ```shell
     sudo PERCONA_TELEMETRY_DISABLE=1 apt install percona-server-server
     ```
 
 === "Red Hat-derived distribution"
 
-    Add the environment variable before the install process.
-
     ```shell
-    sudo PERCONA_TELEMETRY_DISABLE=1 yum install percona-server-server
+    sudo PERCONA_TELEMETRY_DISABLE=1 dnf install percona-server-server
+    ```
+
+=== "Docker"
+
+    ```shell
+    docker run -d -e MYSQL_ROOT_PASSWORD=test1234# -e PERCONA_TELEMETRY_DISABLE=1 --name=percona-server percona/percona-server:8.4
+    ```
+
+## Continuous telemetry
+
+Continuous telemetry uses a telemetry agent and a database component. Continuous telemetry collects information and sends the data daily (after an initial period).
+
+<img src="_static/percona-telemetry.png" alt="Continuous telemetry: database component, metrics file, host agent, and Percona Platform" width="800" style="max-width: 100%; height: auto;" />
+
+### Elements of the continuous telemetry system
+
+| Piece | Role |
+| ----- | ---- |
+| Percona Telemetry DB component | Collects metrics inside the server and writes them to a metrics file on disk. |
+| Metrics file | JSON file on the host filesystem holding collected metrics. |
+| 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. |
+
+On the Percona Platform side:
+
+| Piece | Role |
+| ----- | ---- |
+| Telemetry Service | API endpoint that receives telemetry and stores the payloads. |
+| Telemetry Storage | Long-term storage for telemetry data. |
+
+### Overview of the DB component
+
+Percona Server for MySQL installs a DB component by default (source integration or modular `component_percona_telemetry`).
+
+The DB component:
+
+* Collects database metrics daily
+
+* Writes a new timestamped `.json` file under the telemetry directory
+
+* Keeps roughly one week of metrics files (older files are removed before creating new ones)
+
+The DB component does not collect:
+
+* Database names
+
+* User names or credentials
+
+* Application or user data
+
+### Locations of metrics files and telemetry history
+
+Root for host telemetry: `/usr/local/percona/telemetry`
+
+Product-specific paths (prepend the root):
+
+| Product | Path |
+| ------- | ---- |
+| Percona Server for MySQL | `${telemetry root}/ps/` |
+| Percona Server for MongoDB (`mongod`) | `${telemetry root}/psmdb/` |
+| Percona Server for MongoDB (`mongos`) | `${telemetry root}/psmdbs/` |
+| Percona XtraDB Cluster | `${telemetry root}/pxc/` |
+| PostgreSQL products | `${telemetry root}/pg/` |
+
+Archived copies after successful sends: `${telemetry root}/history/`
+
+### Metrics file format
+
+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):
+
+```json
+{
+  "db_instance_id": "e83c568c-e140-11ee-8320-7e207666b18a",
+  "pillar_version": "{{release}}",
+  "active_plugins": [
+    "binlog",
+    "caching_sha2_password",
+    "InnoDB",
+    "PERFORMANCE_SCHEMA"
+  ],
+  "active_components": [
+    "file://component_percona_telemetry"
+  ],
+  "uptime": "6185",
+  "databases_count": "7",
+  "databases_size": "33149",
+  "se_engines_in_use": [
+    "InnoDB"
+  ],
+  "replication_info": {
+    "is_semisync_source": "1",
+    "is_replica": "1"
+  }
+}
+```
+
+### Percona telemetry agent
+
+The `percona-telemetry-agent` runs on the database host. The agent manages JSON files under the telemetry root path.
+
+- Log file: `/var/log/percona/telemetry-agent.log`
+- First 24 hours: no collection or upload
+- After the first 24 hours: attempts to send daily; on failure, retries up to five times
+- After a successful send, the agent stores a copy under `history/` and deletes the original file produced by the database
+- If the telemetry directory lacks the expected Percona-related files, nothing is sent
+
+#### Telemetry agent payload example
+
+```json
+{
+  "reports": [
+    {
+      "id": "B5BDC47B-B717-4EF5-AEDF-41A17C9C18BB",
+      "createTime": "2026-03-26T15:44:54Z",
+      "instanceId": "B5BDC47B-B717-4EF5-AEDF-41A17C9C18BA",
+      "productFamily": "PRODUCT_FAMILY_PS",
+      "metrics": [
+        {
+          "key": "OS",
+          "value": "Ubuntu"
+        },
+        {
+          "key": "pillar_version",
+          "value": "{{release}}"
+        }
+      ]
+    }
+  ]
+}
+```
+
+| Field | Description |
+| ----- | ----------- |
+| `id` | Random UUID v4 for the request |
+| `createTime` | Timestamp |
+| `instanceId` | DB host ID from metrics/`telemetry_uuid`, or a generated UUID v4 when the host ID is absent |
+| `productFamily` | Derived from file path (e.g. `PRODUCT_FAMILY_PS`) |
+| `metrics` | Key/value pairs from the metrics file |
+
+OS-level metrics included with checks can include:
+
+| Key | Description |
+| --- | ----------- |
+| `OS` | Operating system name |
+| `hardware_arch` | CPU architecture |
+| `deployment` | e.g. `PACKAGE` or `DOCKER` |
+| `installed_packages` | Installed Percona-related packages (name, version, repository when available) |
+
+Reported package names typically match patterns such as: `percona-*`, `Percona-*`, `proxysql*`, `pmm`, `etcd*`, `haproxy`, `patroni`, `pg*`, `postgis`, `wal2json`, and similar.
+
+## Disable continuous telemetry
+
+Continuous telemetry is enabled by default. To disable continuous telemetry completely, use the following order of operations:
+
+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. Add the option and restart before relying on `UNINSTALL COMPONENT` alone: after a restart, the server can load telemetry again if `percona_telemetry_disable` is not set, even if you had uninstalled the component earlier.
+2. Run `UNINSTALL COMPONENT "file://component_percona_telemetry";` so the server stops writing telemetry metrics files.
+3. Stop and disable the `percona-telemetry-agent` service so no data is sent from the host.
+
+Disabling continuous telemetry as described above does not affect installation-time telemetry. To opt out of installation-time telemetry, set `PERCONA_TELEMETRY_DISABLE` before installing.
+
+### Disable the telemetry agent
+
+=== "Temporarily (until next reboot)"
+
+    ```shell
+    systemctl stop percona-telemetry-agent
     ```
 
-=== "DOCKER"
+=== "Permanently"
 
-    Add the environment variable when running a command in a new container.
-
     ```shell
-    docker run -d -e MYSQL_ROOT_PASSWORD=test1234# -e PERCONA_TELEMETRY_DISABLE=1 -e --name=percona-server percona/percona-server:8.1
+    systemctl disable percona-telemetry-agent
     ```
+
+#### Agent dependencies and removal
+
+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.
+
+* DNF: Removing the last package that depended on the agent may remove the agent package.
+
+* APT: Use `apt autoremove` where appropriate; APT may not remove the agent automatically when you remove only the server package.
+
+### Disable the DB component
+
+Even with the agent stopped, the DB telemetry component can still write metrics files for about seven days until you uninstall the component.
+
+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.
+
+```sql
+UNINSTALL COMPONENT "file://component_percona_telemetry";
+```
+
+`my.cnf` should already contain the following from step 1; if `percona_telemetry_disable=1` is not present yet, add the line and restart:
+
+```ini
+[mysqld]
+percona_telemetry_disable=1
+```
+
+## Related reading
+
+* [Install Percona Server for MySQL](installation.md)
+* [Running Percona Server for MySQL in a Docker container](docker.md)
+* [UNINSTALL COMPONENT](uninstall-component.md)