Telemetry & Analytics
Relevant source files
The following files were used as context for generating this wiki page:
The Telemetry & Analytics system in PMM is designed to gather anonymous usage statistics and technical metrics to improve the software. It operates as a background service within pmm-managed, collecting data from various internal sources and sending it to Percona's SaaS platform (check.percona.com). The system ensures that no personal data or database content is collected, focusing instead on system versions, uptime, and distribution methods.
Sources: managed/services/telemetry/telemetry.go:40-60, ui/apps/pmm/src/pages/settings/Settings.messages.ts:28-32
System Architecture
The telemetry service follows a registry-based architecture where different "DataSources" provide metrics that are eventually aggregated into a "GenericReport". The Service struct coordinates the initialization of these sources, the fetching of metrics, and the asynchronous delivery of reports.
Component Overview
- Telemetry Service: The main orchestrator that manages the reporting loop and report preparation.
- DataSource Locator: A registry used to find and initialize specific data sources (e.g., database, system metrics).
- Sender (Portal Client): Responsible for the actual transmission of protobuf-encoded reports to the SaaS endpoint.
- Extensions: Allow for additional metric collection logic outside the standard data source framework.
Sources: managed/services/telemetry/telemetry.go:43-62, managed/services/telemetry/telemetry.go:121-135
Data Flow Diagram
The following diagram illustrates the flow from metric collection to final transmission:
Core Data Structures
The system relies on specific Go structures to define how metrics are gathered and what the final payload contains.
Generic Report Structure
The primary payload for telemetry transmission is the GenericReport, which includes:
- InstanceId: A unique UUID generated for the PMM Server instance.
- ProductFamily: Identifies the software as part of the PMM family.
- Metrics: A key-value list containing versions, durations, and distribution methods.
Service Configuration
The service is governed by a ServiceConfig which dictates the SaaS endpoint and reporting behavior.
| Configuration Field | Description |
|---|---|
Enabled | Global toggle for the telemetry service. |
SaasHostname | The target server for reports (default: check.percona.com). |
Reporting.Interval | Frequency of telemetry collection (default: 24h). |
Reporting.SendTimeout | Context timeout for transmission attempts. |
Reporting.RetryCount | Number of attempts to send a report before buffering or failing. |
Sources: managed/services/telemetry/telemetry.go:374-386, managed/services/telemetry/telemetry.go:43-55, managed/CONTRIBUTING.md:55-65
Logic and Execution
Collection Loop
The telemetry service runs a continuous loop governed by a ticker. It checks the PMM Server settings before every run to ensure the user hasn't disabled telemetry via the UI.
Distribution Method Detection
PMM identifies its installation environment (Docker, Podman, Kubernetes, etc.) to help Percona understand deployment trends. This information is derived through a distributionUtilService.
Relevant Distribution Methods identified in the code include:
- Docker: Standard containerized deployment.
- Podman: RedHat-based containerization.
- Virtual Appliance (OVA): Deployment via VMware/VirtualBox.
- Helm/Kubernetes: Orchestrated cloud-native deployments.
Sources: managed/services/telemetry/telemetry.go:108-115, managed/services/supervisord/supervisord.go:185-200, CONTRIBUTING.md:120-140
User Configuration and Privacy
Users can manage telemetry settings through the PMM Web UI. The interface highlights that collection is anonymous and focused on usage statistics rather than database content.
- Setting Name:
telemetry - Default State: Controlled by the installation environment and user selection during initial setup.
- Data Stored: A unique UUID is stored in the
settingstable of the internal PostgreSQL database to track the instance across reports.
Sources: ui/apps/pmm/src/pages/settings/Settings.messages.ts:28-34, managed/services/telemetry/telemetry.go:374-385
Conclusion
The Telemetry & Analytics system provides a robust, non-intrusive mechanism for Percona to monitor the health and distribution of PMM installations. By utilizing a modular architecture of DataSources and Extensions, the system can be easily updated to collect new technical metrics while strictly adhering to privacy standards by excluding user data.