{"id":29670402,"url":"https://github.com/percona/telemetry-agent","last_synced_at":"2025-12-15T08:46:35.277Z","repository":{"id":196651964,"uuid":"696284713","full_name":"percona/telemetry-agent","owner":"percona","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-15T16:01:20.000Z","size":468,"stargazers_count":2,"open_issues_count":3,"forks_count":5,"subscribers_count":28,"default_branch":"main","last_synced_at":"2025-07-15T16:50:44.080Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/percona.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-09-25T13:03:41.000Z","updated_at":"2025-07-15T08:21:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"4cce3f22-dd55-4ade-afb7-a212e4924d8b","html_url":"https://github.com/percona/telemetry-agent","commit_stats":null,"previous_names":["percona-lab/telemetry-agent","percona/telemetry-agent"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/percona/telemetry-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/percona%2Ftelemetry-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/percona%2Ftelemetry-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/percona%2Ftelemetry-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/percona%2Ftelemetry-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/percona","download_url":"https://codeload.github.com/percona/telemetry-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/percona%2Ftelemetry-agent/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266561553,"owners_count":23948632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-22T19:36:06.258Z","updated_at":"2025-12-15T08:46:30.227Z","avatar_url":"https://github.com/percona.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Percona Telemetry\n\n[![CI](https://github.com/percona/telemetry-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/percona/telemetry-agent/actions/workflows/ci.yml)\n[![CLA assistant](https://cla-assistant.percona.com/readme/badge/percona/telemetry-agent)](https://cla-assistant.percona.com/percona/telemetry-agent)\n[![Go Report Card](https://goreportcard.com/badge/github.com/percona/telemetry-agent)](https://goreportcard.com/report/github.com/percona/telemetry-agent)\n\n\u003c!-- TOC --\u003e\n* [Percona Telemetry](#percona-telemetry)\n  * [Installation-time telemetry](#installation-time-telemetry)\n    * [Disable installation-time telemetry](#disable-installation-time-telemetry)\n  * [Continuous telemetry](#continuous-telemetry)\n    * [Elements of the continuous telemetry system](#elements-of-the-continuous-telemetry-system)\n    * [Locations of metrics files and telemetry history](#locations-of-metrics-files-and-telemetry-history)\n    * [Metrics file format](#metrics-file-format)\n    * [Percona Telemetry Agent](#percona-telemetry-agent)\n      * [Telemetry agent payload example](#telemetry-agent-payload-example)\n      * [Telemetry Agent configuration](#telemetry-agent-configuration)\n    * [Disable continuous telemetry](#disable-continuous-telemetry)\n      * [Disable the Telemetry Agent](#disable-the-telemetry-agent)\n        * [Disable temporarily](#disable-temporarily)\n        * [Disable permanently](#disable-permanently)\n      * [Disable DB component](#disable-db-component)\n\u003c!-- TOC --\u003e\n\nThis repository contains the Percona Telemetry Agent for Pillars telemetry project, a tool that collects telemetry \ninformation and sends it to Percona Telemetry service.\n\nFor the time being Pillars (Percona Server for MySQL, Percona Server for MongoDB, Percona Server for PostgreSQL) \nTelemetry consists of the following parts:\n* [Installation-time telemetry](#installation-time-telemetry)\n* [Continuous telemetry](#continuous-telemetry)\n\nAll telemetry data is sent to the Percona Telemetry service. The service is responsible for storing and processing the\ndata. The data is used to improve the quality of Percona products and services.\nTelemetry data is sent to https://check.percona.com/v1/telemetry/GenericReport endpoint in a JSON format.\n\n## Installation-time telemetry\n\nThis feature is enabled in Percona Linux packages and Docker containers by default. In order to disable it see \n[Disable installation-time telemetry](#disable-installation-time-telemetry)\n\nThis telemetry is executed only once during software installation. It collects information at the moment of installation \nor Docker container startup and does not run afterward.\n\nFor this purpose the script `call-home.sh` is used that collects telemetry information and sends it to a Percona Telemetry service.\nThe script validates only if mandatory parameters are provided. It does not check the validity and itegritiy of provided parameters.\n\nUsage: \n```{.bash data-prompt=\"$\"}\n./call-home.sh OPTIONS\nOPTIONS can be:\n  -h  Show this message\n  -f  [PERCONA_PRODUCT_FAMILY]              Product family identifier.                                  [REQUIRED]\n  -v  [PERCONA_PRODUCT_VERSION]             Product version.                                            [REQUIRED]\n  -s  [PERCONA_OPERATING_SYSTEM]            Operating system identifier.                                [Default: autodetected with fallback to \"unknown\"]\n  -d  [PERCONA_DEPLOYMENT_METHOD]           Deployment method.                                          [REQUIRED]\n  -i  [PERCONA_INSTANCE_ID]                 Instance id                                                 [Default: autogenerated]\n  -j  [PERCONA_TELEMETRY_CONFIG_FILE_PATH]  Path of the file where to store the unique ID of this node. [Default: /usr/local/percona/telemetry_uuid]\n  -u  [PERCONA_TELEMETRY_URL]               Percona Telemetry Service endpoint                          [Default: https://check.percona.com/v1/telemetry/GenericReport]\n  -c  [PERCONA_CONNECT_TIMEOUT]             Default timeout for the curl to establish connection.       [Default: 5]\n  -t  [PERCONA_SEND_TIMEOUT]                Default timeout for the whole curl command.                 [Default: 10]\n```\n\nNote that `-d PERCONA_PRODUCT_FAMILY` can be set to any string, but only the following ones will be accepted\nby Percona Telemetry service (there is no validation of the script side):\n```\nPRODUCT_FAMILY_PS\nPRODUCT_FAMILY_PXC\nPRODUCT_FAMILY_PXB\nPRODUCT_FAMILY_PSMDB\nPRODUCT_FAMILY_PBM\nPRODUCT_FAMILY_POSTGRESQL\nPRODUCT_FAMILY_PMM\nPRODUCT_FAMILY_EVEREST\nPRODUCT_FAMILY_PERCONA_TOOLKIT\n```\n\nFor example, on Debian-derived distribution, you may run the script as:\n```{.bash data-prompt=\"$\"}\n./call-home.sh -f \"PRODUCT_FAMILY_PS\" -v \"8.0.33\" -s \"$(cat /etc/issue)\" -i \"13f5fc62-35b4-4716-b3e6-96c761fc204d\" -j /tmp/percona.telemetry -u https://check.percona.com/v1/telemetry/GenericReport -c 1 -t 2\n```\n\non a Red Hat-derived distribution, you may run the script as:\n```{.bash data-prompt=\"$\"}\n./call-home.sh -f \"PRODUCT_FAMILY_PS\" -v \"8.0.33\" -s \"$(cat /etc/redhat-release)\" -i \"13f5fc62-35b4-4716-b3e6-96c761fc204d\" -j /tmp/percona.telemetry -u https://check.percona.com/v1/telemetry/GenericReport -c 1 -t 2\n```\n\n### Disable installation-time telemetry\n\nThe data collection may be disabled via setting an environment variable `PERCONA_TELEMETRY_DISABLE=1` during Linux package \ninstallation or Docker container startup.\n\nFor example, on Debian-derived distribution (this action does not affect the continuous telemetry part):\n```{.bash data-prompt=\"$\"}\nsudo PERCONA_TELEMETRY_DISABLE=1 apt install percona-server-server\n```\n\non a Red Hat-derived distribution (this action does not affect the continuous telemetry part):\n```{.bash data-prompt=\"$\"}\nsudo PERCONA_TELEMETRY_DISABLE=1 dnf install percona-server-server\n```\n\nor in a Docker container (this action disables the continuous telemetry part as well):\n```{.bash data-prompt=\"$\"}\ndocker run -e PERCONA_TELEMETRY_DISABLE=1 percona/percona-server\n```\n\n## Continuous telemetry\n\nThis telemetry part involves setting up a Telemetry Agent and a database (DB) component. It continuously collects and \nsends information daily.\n\nThe Telemetry Agent runs at scheduled daily intervals to collect data. The agent gathers data (for example, usage statistics) \nand sends this information to the Percona Telemetry Service.\n\n### Elements of the continuous telemetry system\n\nPercona collects information using these elements:\n\n| Function                                                          | Description                                                                                                                                                                                                                                                                                                                                                 |\n|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Percona Telemetry DB component                                    | This component collects metrics directly from the database and stores them in a metrics file.                                                                                                                                                                                                                                                               |\n| [Metrics File](#locations-of-metrics-files-and-telemetry-history) | This standalone file on the database host's file system stores the collected metrics.                                                                                                                                                                                                                                                                       |\n| [Telemetry Agent](#percona-telemetry-agent)                       | This independent process runs on your database host's operating system and performs the following tasks:\u003cbr\u003e - Collects OS-level metrics.\u003cbr\u003e- Reads the metrics file and adds the OS-level metrics.\u003cbr\u003e- Sends the complete set of metrics to the Percona Platform.\u003cbr\u003e - Collects the list of installed Percona packages using the local package manager. |\n\n### Locations of metrics files and telemetry history\n\nPercona stores the Metrics file in one of the following directories on the local file system. The location depends on the product.\n\n* Telemetry root path - `/usr/local/percona/telemetry`\n* PSMDB (mongod) root path -   `${telemetry root path}/psmdb/`\n* PSMDB (mongos) root path - `${telemetry root path}/psmdbs/`\n* PS root path -   `${telemetry root path}/ps/`\n* PXC root path - `${telemetry root path}/pxc/`\n* PG root path - `${telemetry root path}/pg/`\n\nPercona archives the telemetry history in `${telemetry root path}/history/`.\n\n### Metrics file format\n\nThe Metrics file uses the Javascript Object Notation (JSON) format. Percona reserves the right to extend the current set \nof JSON structure attributes in the future.\n\nAn example of the Metrics file content is the following:\n\n ```json\n {\n   \"db_instance_id\": \"e83c568c-e140-11ee-8320-7e207666b18a\",\n   \"pillar_version\": \"8.0.35-27\",\n   \"active_plugins\": [\n     \"binlog\",\n     \"mysql_native_password\",\n     \"sha256_password\",\n     \"caching_sha2_password\",\n     \"sha2_cache_cleaner\",\n     \"daemon_keyring_proxy_plugin\",\n     \"PERFORMANCE_SCHEMA\",\n     \"ROCKSDB_INDEX_FILE_MAP\",\n     \"ROCKSDB_LOCKS\",\n     \"ROCKSDB_TRX\",\n     \"ROCKSDB_DEADLOCK\"\n   ],\n   \"active_components\": [\n     \"file://component_percona_telemetry\"\n   ],\n   \"uptime\": \"6185\",\n   \"databases_count\": \"7\",\n   \"databases_size\": \"33149\",\n   \"se_engines_in_use\": [\n     \"InnoDB\",\n     \"ROCKSDB\"\n   ],\n   \"replication_info\": {\n     \"is_semisync_source\": \"1\",\n     \"is_replica\": \"1\"\n   }\n }\n ```\n\n### Percona Telemetry Agent\n\nThis program, called `percona-telemetry-agent`, constantly runs in the background on your server's host system. \nIt manages JSON files, which store the collected data in a specific location (`${telemetry root path}`). This agent can \ncreate, read, write, and delete these files.\nThe agent's log file, containing information about its activity, is located at `/var/log/percona/telemetry-agent.log`.\n\nIn the first 24 hours, no information is collected or sent. After that period, the agent tries to send the collected \ninformation to Percona Telemetry Service daily. If this operation fails, the agent retries up to five times. \nAfter the data is successfully sent, the agent saves a copy of the sent data in a separate \"history\" folder \n(`${telemetry root path}/history/`), and then, deletes the original file created by the database.\n\nThe agent won't send any data if the target directory doesn't contain specific files related to Percona software.\n\n#### Telemetry agent payload example\n\nThe following is an example of a Telemetry Agent payload:\n\n ```json\n {\n   \"reports\": [\n     {\n       \"id\": \"B5BDC47B-B717-4EF5-AEDF-41A17C9C18BB\",\n       \"createTime\": \"2023-09-01T10:56:49Z\",\n       \"instanceId\": \"B5BDC47B-B717-4EF5-AEDF-41A17C9C18BA\",\n       \"productFamily\": \"PRODUCT_FAMILY_PS\",\n       \"metrics\": [\n         {\n           \"key\": \"OS\",\n           \"value\": \"Ubuntu\"\n         },\n         {\n           \"key\": \"pillar_version\",\n           \"value\": \"8.0.33-25\"\n         }\n       ]\n     }\n   ]\n }\n ```\n\nThe agent sends information about the database and metrics.\n\n| Key           | Description                                                                                                                                                       |\n|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id            | A randomly generated Universally Unique Identifier (UUID) version 4 of request                                                                                    |\n| createTime    | UNIX timestamp of request creation                                                                                                                                |\n| instanceId    | The DB Host ID. The value can be taken from the `instanceId`, the `/usr/local/percona/telemetry_uuid`\u003cbr/\u003e or generated as a UUID version 4 if the file is absent |\n| productFamily | The value from the file path                                                                                                                                      |\n| metrics       | An array of key:value pairs collected from the Metrics file                                                                                                       |\n\nThe following operating system-level metrics are sent with each metrics send iteration:\n\n| Key                  | Description                                                                                |\n|----------------------|--------------------------------------------------------------------------------------------|\n| \"OS\"                 | The name of the operating system                                                           |\n| \"hardware_arch\"      | CPU architecture used on DB host                                                           |\n| \"deployment\"         | How the application was deployed. \u003cbr\u003e The possible values could be \"PACKAGE\" or \"DOCKER\". |\n| \"installed_packages\" | A list of the installed Percona's packages.                                                |\n\n#### Telemetry Agent configuration\n\nTelemetry Agent can be configured during startup by setting the following environment variables or their CLI arguments equivalents:\n\n| Environment variable                    | CLI param                         | Description                                                     | Default value                                        |\n|-----------------------------------------|-----------------------------------|-----------------------------------------------------------------|------------------------------------------------------|\n| PERCONA_TELEMETRY_ROOT_PATH             | --telemetry.root-path             | The root path for telemetry files                               | /usr/local/percona/telemetry                         |\n| PERCONA_TELEMETRY_CHECK_INTERVAL        | --telemetry.check-interval        | The interval in seconds between telemetry checks                | 86400                                                |\n| PERCONA_TELEMETRY_RESEND_INTERVAL       | --telemetry.resend-interval       | The interval in seconds between telemetry resend attempts       | 60                                                   |\n| PERCONA_TELEMETRY_HISTORY_KEEP_INTERVAL | --telemetry.history-keep-interval | The interval in seconds between telemetry history files cleanup | 604800                                               |\n| PERCONA_TELEMETRY_URL                   | --telemetry.url                   | The URL of the Percona Telemetry Service                        | https://check.percona.com/v1/telemetry/GenericReport |\n|                                         | --log.verbose                     | Enable verbose logging                                          | false                                                |\n|                                         | --log.dev-mode                    | Enable development mode                                         | false                                                |\n|                                         | --version                         | Print version and exit                                          | false                                                |\n|                                         | --help                            | Show help                                                       | false                                                |\n\nChanging any of this configuration parameters requires a restart of the Telemetry Agent.\n\n### Disable continuous telemetry\n\nPercona software enables the continuous telemetry system by default. Disable the Telemetry agent and uninstall the DB \ncomponent to turn off this telemetry completely.\n\nThese actions do not affect [Installation-time telemetry](#installation-time-telemetry).\n\n#### Disable the Telemetry Agent\n\nYou can either disable the Telemetry agent for a session or permanently. These actions do not affect the DB component, i.e.\nDB will still continue collecting metrics but they will not be sent to Percona Telemetry Service. \n\n##### Disable temporarily\n\nTurn off Telemetry Agent temporarily until the next server restart:\n ```{.bash data-prompt=$}\n systemctl stop percona-telemetry-agent\n ```\n\n##### Disable permanently\n\nTurn off Telemetry Agent permanently:\n ```{.bash data-prompt=$}\n systemctl stop percona-telemetry-agent\n systemctl disable percona-telemetry-agent\n ```\n\n#### Disable DB component\n\nThe DB component continues to generate daily telemetry files and store them for a week, even after you stop the \nTelemetry Agent service.\nRefer to particular Percona DB server documentation in order to disable the DB component.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpercona%2Ftelemetry-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpercona%2Ftelemetry-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpercona%2Ftelemetry-agent/lists"}