diff --git a/documentation/api/backups/restore-backup.md b/documentation/api/backups/restore-backup.md index a92b9e60c8a..f695e2abaa7 100644 --- a/documentation/api/backups/restore-backup.md +++ b/documentation/api/backups/restore-backup.md @@ -42,3 +42,4 @@ The API call could return an error message in the details, containing a specific - ERROR_CODE_INVALID_XTRABACKUP - different versions of xtrabackup and xbcloud - ERROR_CODE_INCOMPATIBLE_XTRABACKUP - xtrabackup is not compatible with MySQL for making a backup - ERROR_CODE_INCOMPATIBLE_TARGET_MYSQL - target MySQL version is not compatible with the artifact to perform a restore of the backup +- ERROR_CODE_INCOMPATIBLE_TARGET_MONGODB - target MongoDB version does not match the version recorded in the backup artifact diff --git a/documentation/docs/admin/security/index.md b/documentation/docs/admin/security/index.md index 7610c823bef..636b2595785 100644 --- a/documentation/docs/admin/security/index.md +++ b/documentation/docs/admin/security/index.md @@ -10,3 +10,23 @@ Taking the following precautions will ensure that you are truly secure: - [Grafana HTTPS secure cookies](../../admin/security/grafana_cookies.md) - [Encrypt the PMM Client configuration file](client_config_encryption.md) to protect stored credentials on client hosts +## Manually configure the PostgreSQL Grafana datasource + +Starting with PMM 3.9.0, PMM no longer provisions a PostgreSQL Grafana datasource by default. If you need to query PMM's internal PostgreSQL database directly, you can add the datasource manually. + +To prevent unauthorized data modification, configure the datasource with a database user that has **SELECT**-only permissions. + +To add the PostgreSQL datasource: +{.power-number} + +1. From the **Home** page, locate the Search icon (top right on the screen). +2. Type "plugins" and select **Administration > Plugins and data > Plugins**. +3. Find and open the **Postgres** plugin. +4. Select **Add new datasource**. +5. Configure the connection parameters and click **Save & test**. +6. If the test is successful, you can start using the datasource from the **Explore** page. + +!!! note + + You might see this datasource labeled as unsupported. You can safely disregard that label. The PostgreSQL datasource works as expected. + diff --git a/documentation/docs/backup/mongodb-backup/backup_mongo.md b/documentation/docs/backup/mongodb-backup/backup_mongo.md index 7b1f65f6e92..a07ac9a90cb 100644 --- a/documentation/docs/backup/mongodb-backup/backup_mongo.md +++ b/documentation/docs/backup/mongodb-backup/backup_mongo.md @@ -10,8 +10,8 @@ The following backup operations are supported for replica sets: - Storing backups on Amazon S3-compatible object storage, and on mounted filesystem - Creating and restoring Logical snapshot backups - - Creating and restoring Physical snapshot backups - - Creating logical PITR backups both locally and on S3-compatible object storage. Restoring logical PITR backups from S3-compatible object storage. + - Creating and restoring Physical snapshot backups for Percona Server for MongoDB + - You can create logical PITR backups both locally and on S3-compatible object storage. To restore a PITR backup, you must use S3-compatible object storage. PMM does not support PITR restores from local storage. ## Sharded clusters @@ -20,7 +20,7 @@ PMM 3 supports backing up sharded clusters. However, restoring for sharded clust - Storing backups on Amazon S3-compatible object storage, and on mounted filesystem - Creating Logical snapshot backups - - Creating Physical snapshot backups + - Creating Physical snapshot backups for Percona Server for MongoDB - Creating logical PITR backups both locally and on S3-compatible object storage For a detailed overview of the supported setups for MongoDB, check out the [Support matrix](mongodb_limitations.md). diff --git a/documentation/docs/backup/mongodb-backup/create_PITR_mongo.md b/documentation/docs/backup/mongodb-backup/create_PITR_mongo.md index 36ad14b3c5a..9d486b09fbc 100644 --- a/documentation/docs/backup/mongodb-backup/create_PITR_mongo.md +++ b/documentation/docs/backup/mongodb-backup/create_PITR_mongo.md @@ -5,12 +5,11 @@ Point-in-Time Recovery (PITR) restores databases up to a specific moment in time Point-in-Time Recovery helps you prevent data loss during a disaster such as crashed database, accidental data deletion or drop of tables, or unwanted update of multiple fields instead of a single one. ## Compatibility with Percona Backup for MongoDB -PMM introduced the option to create PITR Backups for MongoDB in version 2.23, as part of the larger Backup Management feature. This implementation in PMM uses Percona Backup for MongoDB (pbm) behind the scenes. +PMM introduced the option to create PITR backups for MongoDB in version 2.23 as part of the Backup Management feature. PMM uses Percona Backup for MongoDB (PBM) to create and restore these backups. -Percona Backup for MongoDB is a distributed, low-impact solution for achieving consistent backups of MongoDB sharded clusters and replica sets. -Restoring PITR backups is available for backups based on pbm ≤ 2.0.1. To restore PITR backups, make sure you have pbm ≥ 2.0.1 installed. +PMM requires PBM 2.0.1 or later. PBM is a distributed, low-impact solution for achieving consistent backups of MongoDB sharded clusters and replica sets. - Percona Backup for MongoDB supports [Percona Server for MongoDB](https://docs.percona.com/percona-server-for-mongodb/) and MongoDB Community ≤ 3.6, with [MongoDB Replication](https://docs.mongodb.com/manual/replication/) enabled. For more information, see the [Percona Backup for MongoDB documentation](https://docs.percona.com/percona-backup-mongodb/installation.html). +PBM supports logical backups for MongoDB Community and Enterprise Edition with replication enabled. It supports logical, physical, and incremental backups for [Percona Server for MongoDB](https://docs.percona.com/percona-server-for-mongodb/). Check the [PBM compatibility matrix](https://docs.percona.com/percona-backup-mongodb/details/versions.html) for the MongoDB versions supported by each PBM release. ## How does it work? diff --git a/documentation/docs/backup/mongodb-backup/mongo_prerequisites.md b/documentation/docs/backup/mongodb-backup/mongo_prerequisites.md index 31f25cad638..cc8edca90bf 100644 --- a/documentation/docs/backup/mongodb-backup/mongo_prerequisites.md +++ b/documentation/docs/backup/mongodb-backup/mongo_prerequisites.md @@ -1,7 +1,7 @@ # MongoDB backup prerequisites !!! note "PBM version compatibility" - PMM 3 and later are not compatible with Percona Backup for MongoDB (PBM) version 2.10 and above. You must use PBM version 2.0.1 to 2.9.x with PMM. + PMM requires Percona Backup for MongoDB (PBM) 2.0.1 or later. Check the [PBM compatibility matrix](https://docs.percona.com/percona-backup-mongodb/details/versions.html) to select a PBM version that supports your MongoDB or Percona Server for MongoDB version. Before creating MongoDB backups, make sure to: {.power-number} diff --git a/documentation/docs/backup/mongodb-backup/mongodb_limitations.md b/documentation/docs/backup/mongodb-backup/mongodb_limitations.md index d50933e48a6..f9a3aa2196f 100644 --- a/documentation/docs/backup/mongodb-backup/mongodb_limitations.md +++ b/documentation/docs/backup/mongodb-backup/mongodb_limitations.md @@ -1,7 +1,16 @@ -# MongoDB Backup and Restore support matrix +# MongoDB backup and restore support matrix -!!! note "PBM version compatibility" - PMM is not compatible with Percona Backup for MongoDB (PBM) version 2.10 and above. Make sure to use PBM version 2.0.1 to 2.9.x. +## PBM version compatibility + +PMM requires Percona Backup for MongoDB (PBM) 2.0.1 or later: + +- PBM earlier than 2.0.1: not supported +- PBM 2.0.1 to 2.9.x: supported +- PBM 2.10.0 and later: supported, but requires PMM 3.9.0 or later + +To find a PBM version compatible with your MongoDB or Percona Server for MongoDB version, see the [PBM compatibility matrix](https://docs.percona.com/percona-backup-mongodb/details/versions.html). + +## Limitations and requirements Creating and restoring MongoDB backups in PMM currently has the following limitations and requirements: @@ -9,9 +18,10 @@ Creating and restoring MongoDB backups in PMM currently has the following limita - Physical restores are not supported for deployments with arbiter nodes. For more information, see the [Percona Backup for MongoDB documentation](https://docs.percona.com/percona-backup-mongodb/usage/restore.html#physical-restore-known-limitations). - Creating backups for sharded clusters is available straight from the UI. However, restoring these backup artifacts is only possible via the CLI, using Percona Backup for MongoDB. For information on restoring sharded backups, check the [PBM documentation](https://docs.percona.com/percona-backup-mongodb/usage/restore.html). - Retention policy is supported only for snapshot types of scheduled backups and for the S3-compatible storage type. +- PMM can restore a backup only when the target service runs the same MongoDB version recorded in the backup artifact. - Before restoring, make sure to prevent clients from accessing the database. -## Support matrix +## Backup and restore support matrix ## Backup: Logical diff --git a/documentation/docs/backup/mongodb-backup/restore_MongoDB_backups.md b/documentation/docs/backup/mongodb-backup/restore_MongoDB_backups.md index 02771a026f7..531446b77e3 100644 --- a/documentation/docs/backup/mongodb-backup/restore_MongoDB_backups.md +++ b/documentation/docs/backup/mongodb-backup/restore_MongoDB_backups.md @@ -1,13 +1,13 @@ # Restore a MongoDB backup -MongoDB backups can only be restored to the same service they were created from. +MongoDB backups can only be restored to the same service they were created from. The target MongoDB version must match the version recorded in the backup artifact. To restore a backup: {.power-number} 1. Go to **Backup > All backups** and find the backup that you want to restore. 2. Click the arrow in the **Actions** column to check all the information for the backup, then click ![](../../images/dots-three-vertical.png) **Restore from backup**. -This opens the **Restore from backup** dialog, with the **Same service** option automatically preselected. This is because, currently, MongoDB backups can only be restored to a service with identical properties. +This opens the **Restore from backup** dialog, with the **Same service** option automatically preselected. This is because MongoDB backups can only be restored to the originating service, and only if the MongoDB version has not changed since the backup was created. 3. If you are restoring a PITR backup, select the point for the date and time that you want to restore the database to. 4. Click **Restore** then go to the **Restores** tab to check the status of the restored backup. @@ -20,7 +20,7 @@ This opens the **Restore from backup** dialog, with the **Same service** option To restore to a new cluster manually: {.power-number} -1. Install MongoDB and Percona Backup for MongoDB. Pay attention to the versions. To minimize potential incompatibility, use the same versions that were used for taking backups. +1. Install MongoDB and Percona Backup for MongoDB 2.0.1 or later. Pay attention to the versions. To minimize potential incompatibility, use the same versions that were used for taking backups. For instructions, see the [PBM install documentation](https://docs.percona.com/percona-backup-mongodb/installation.html). 2. Configure your environment: - to restore to a new environment with the same replica set name, make sure that the replica set name in your new destination cluster use the same name as that in the cluster that was backed up.
@@ -108,7 +108,7 @@ To restore to a new cluster manually: ``` b) provide the timestamp from one of the PITR ranges to the `pbm` command: - `pbm restore --time="2022-11-23T19:40:26` + `pbm restore --time="2022-11-23T19:40:26"` For more information, see the [Point-in-time Recovery topic in the PBM documentation](https://docs.percona.com/percona-backup-mongodb/features/point-in-time-recovery.html?h=point). diff --git a/documentation/docs/images/ExportRTA.png b/documentation/docs/images/ExportRTA.png new file mode 100644 index 00000000000..31fcc4f7aa1 Binary files /dev/null and b/documentation/docs/images/ExportRTA.png differ diff --git a/documentation/docs/images/PMM-manage-users.png b/documentation/docs/images/PMM-manage-users.png deleted file mode 100644 index 59047a9aec5..00000000000 Binary files a/documentation/docs/images/PMM-manage-users.png and /dev/null differ diff --git a/documentation/docs/images/PMM_Environment_Overview_Dashboard.jpg b/documentation/docs/images/PMM_Environment_Overview_Dashboard.jpg deleted file mode 100644 index 662ca5b7814..00000000000 Binary files a/documentation/docs/images/PMM_Environment_Overview_Dashboard.jpg and /dev/null differ diff --git a/documentation/docs/images/PMM_Explore_metrics_drilldown.jpg b/documentation/docs/images/PMM_Explore_metrics_drilldown.jpg deleted file mode 100644 index 31fa4dea763..00000000000 Binary files a/documentation/docs/images/PMM_Explore_metrics_drilldown.jpg and /dev/null differ diff --git a/documentation/docs/images/PMM_Inventory_Service_Selection.png b/documentation/docs/images/PMM_Inventory_Service_Selection.png deleted file mode 100644 index b73de5dee3d..00000000000 Binary files a/documentation/docs/images/PMM_Inventory_Service_Selection.png and /dev/null differ diff --git a/documentation/docs/images/PMM_MongoDB_InMemory_Details_dashboard.jpg b/documentation/docs/images/PMM_MongoDB_InMemory_Details_dashboard.jpg deleted file mode 100644 index 5f42f57517b..00000000000 Binary files a/documentation/docs/images/PMM_MongoDB_InMemory_Details_dashboard.jpg and /dev/null differ diff --git a/documentation/docs/images/PMM_PXC_Galera_Cluster_Summary._Experimental.jpg b/documentation/docs/images/PMM_PXC_Galera_Cluster_Summary._Experimental.jpg deleted file mode 100644 index cb6dbe17cc8..00000000000 Binary files a/documentation/docs/images/PMM_PXC_Galera_Cluster_Summary._Experimental.jpg and /dev/null differ diff --git a/documentation/docs/images/PMM_PostgreSQL_Checkpoints_Buffers_WAL.png b/documentation/docs/images/PMM_PostgreSQL_Checkpoints_Buffers_WAL.png deleted file mode 100644 index d81bc1c77ff..00000000000 Binary files a/documentation/docs/images/PMM_PostgreSQL_Checkpoints_Buffers_WAL.png and /dev/null differ diff --git a/documentation/docs/images/PMM_PostgreSQL_Instance_Summary.jpg b/documentation/docs/images/PMM_PostgreSQL_Instance_Summary.jpg deleted file mode 100644 index 2f9e640200e..00000000000 Binary files a/documentation/docs/images/PMM_PostgreSQL_Instance_Summary.jpg and /dev/null differ diff --git a/documentation/docs/images/PMM_PostgreSQL_Patroni_Details.png b/documentation/docs/images/PMM_PostgreSQL_Patroni_Details.png deleted file mode 100644 index 60fdb9e7c08..00000000000 Binary files a/documentation/docs/images/PMM_PostgreSQL_Patroni_Details.png and /dev/null differ diff --git a/documentation/docs/images/PMM_PostgreSQL_vacuum_monitor-experimental.png b/documentation/docs/images/PMM_PostgreSQL_vacuum_monitor-experimental.png deleted file mode 100644 index ceffcf0b091..00000000000 Binary files a/documentation/docs/images/PMM_PostgreSQL_vacuum_monitor-experimental.png and /dev/null differ diff --git a/documentation/docs/images/pg-panels.png b/documentation/docs/images/pg-panels.png new file mode 100644 index 00000000000..aab4a25ddf6 Binary files /dev/null and b/documentation/docs/images/pg-panels.png differ diff --git a/documentation/docs/install-pmm/index.md b/documentation/docs/install-pmm/index.md index 08e84bfe975..c56c513f3ea 100644 --- a/documentation/docs/install-pmm/index.md +++ b/documentation/docs/install-pmm/index.md @@ -23,9 +23,9 @@ Before ou install PMM, ensure your environment is properly prepared: ### PMM Server deployment options -Compare the available deployment methods to choose what works best for your setup. For a fast evaluation setup, Docker is the quickest option. For production environments, consider your existing infrastructure stack and operational preferences when choosing between Docker, Kubernetes (Helm), or Virtual Appliance deployments: +Compare the available deployment methods to choose what works best for your setup. For a fast evaluation setup, Docker is the quickest option. For production environments, consider your existing infrastructure stack and operational preferences when choosing between Docker or Kubernetes (Helm) deployments: -| Deployment Method | Best for | Advantages | Considerations | +| Deployment method | Best for | Advantages | Considerations | |-------------------|----------|------------|----------------| | [Docker](../install-pmm/install-pmm-server/deployment-options/docker/index.md) | Quick setup, development environments | • Fast deployment
• Easy to manage
• Runs without root privileges
• Minimal resource overhead | • Requires Docker knowledge
• May need additional network configuration | | [Podman](../install-pmm/install-pmm-server/deployment-options/podman/index.md) | Security-conscious environments | • Rootless by default
• Enhanced security
• Docker-compatible commands
• No daemon required | • Requires Podman installation
• Less common than Docker | diff --git a/documentation/docs/install-pmm/install-pmm-client/connect-database/linux.md b/documentation/docs/install-pmm/install-pmm-client/connect-database/linux.md index 05f78dfc38f..4d5eb3ccbb9 100644 --- a/documentation/docs/install-pmm/install-pmm-client/connect-database/linux.md +++ b/documentation/docs/install-pmm/install-pmm-client/connect-database/linux.md @@ -7,7 +7,7 @@ PMM Client supports collecting system metrics from various Linux distributions: - Red Hat/CentOS/Oracle Linux 8, 9 and 10 - Amazon Linux 2023 (native support added in PMM 3.2.0) - Debian 11 (Bullseye), 12 (Bookworm) and 13 (Trixie) -- Ubuntu 22.04 (Jammy) and 24.04 (Noble) +- Ubuntu 22.04 (Jammy), 24.04 (Noble) and 26.04 (Resolute) ## Add Linux monitoring diff --git a/documentation/docs/install-pmm/install-pmm-client/connect-database/mongodb.md b/documentation/docs/install-pmm/install-pmm-client/connect-database/mongodb.md index 19d49f15f9f..fa3c8267b03 100644 --- a/documentation/docs/install-pmm/install-pmm-client/connect-database/mongodb.md +++ b/documentation/docs/install-pmm/install-pmm-client/connect-database/mongodb.md @@ -44,7 +44,7 @@ db.getSiblingDB("admin").createRole({ }, { "resource": { "db": "", "collection": "system.profile" }, - "actions": [ "dbStats", "collStats", "indexStats" ] + "actions": [ "find", "dbStats", "collStats", "indexStats" ] } ], "roles": [ ] @@ -398,6 +398,8 @@ After configuring your database server, add a MongoDB service using either the u !!! hint alert alert-success "Tips" - When adding members of a replica set or sharded cluster, ensure to add each node using the same `--cluster my_cluster_or_rs_name`. This allows the [MongoDB Cluster Summary](../../../reference/dashboards/dashboard-mongodb-cluster-summary.md) and [MongoDB ReplSetSummary](../../../reference/dashboards/dashboard-mongodb-replset-summary.md) dashboards to populate correctly. + - Some dashboard panels, such as **Total data size** on the [MongoDB ReplSet Summary](../../../reference/dashboards/dashboard-mongodb-replset-summary.md) and [MongoDB Sharded Cluster Summary](../../../reference/dashboards/dashboard-mongodb-cluster-summary.md) dashboards, require the `dbstats` collector. Pass [`--enable-all-collectors`](../../../use/commands/pmm-admin/add.md#collector-options) when adding the service to enable it. + - To collect histogram metrics from MongoDB's diagnostic data, pass `--enable-diagnostic-data-histograms`. This option is not included in `--enable-all-collectors` and must be set explicitly. Enabling it may significantly increase `mongodb_exporter` memory usage. - PMM does not gather collection and index metrics if it detects you have more than 200 collections, in order to limit the resource consumption. Check the [advanced options](../../../use/commands/pmm-admin/add.md#collector-options) section if you want to modify this behaviour. - When running mongos routers in containers, specify the `diagnosticDataCollectionDirectoryPath` to ensure that pmm-agent can properly capture mongos metrics. For example: `mongos --setParameter diagnosticDataCollectionDirectoryPath=/var/log/mongo/mongos.diagnostic.data/` diff --git a/documentation/docs/install-pmm/install-pmm-client/connect-database/mysql/custom_queries.md b/documentation/docs/install-pmm/install-pmm-client/connect-database/mysql/custom_queries.md new file mode 100644 index 00000000000..464e0321739 --- /dev/null +++ b/documentation/docs/install-pmm/install-pmm-client/connect-database/mysql/custom_queries.md @@ -0,0 +1,68 @@ +# Use custom queries on MySQL + +Run custom SQL queries to collect metrics that PMM does not monitor by default, such as internal statistics, application-level data, or business metrics. + +The MySQL exporter automatically reads query definitions from YAML files placed in a specific directory on the PMM Client host. The subdirectory you place the file in determines how often the query runs. + +To set up a custom query: +{.power-number} + +1. Place your query file in one of the following directories. The MySQL exporter reads files from these directories automatically, and the subdirectory you choose sets the collection frequency. Since all queries in a directory run sequentially, keep them fast to avoid missing the collection window:    + + - `/usr/local/percona/pmm/collectors/custom-queries/mysql/high-resolution/` — every 5 seconds + - `/usr/local/percona/pmm/collectors/custom-queries/mysql/medium-resolution/` — every 10 seconds + - `/usr/local/percona/pmm/collectors/custom-queries/mysql/low-resolution/` — every 60 seconds + + +2. In the directory you chose, create a .yaml file to define the custom query the MySQL exporter will run. The file specifies the SQL query, a metric namespace to group the results under, and how each returned column maps to a metric. PMM builds the metric name by combining the namespace with the column name, for example `metric_namespace_col2`: + + ```yaml + metric_namespace: + query: "SELECT col1, col2 FROM your_table" + metrics: + - col1: + usage: "LABEL" + description: "Description of col1" + - col2: + usage: "GAUGE" + description: "Description of col2" + ``` + + ??? example "Example: Collecting InnoDB index statistics" + ```yaml + mysql_innodb_index_stats: + query: "SELECT database_name, table_name, index_name, stat_name, stat_value + FROM mysql.innodb_index_stats" + metrics: + - database_name: + usage: "LABEL" + description: "Database name" + - table_name: + usage: "LABEL" + description: "Table name" + - index_name: + usage: "LABEL" + description: "Index name" + - stat_name: + usage: "LABEL" + description: "Statistic name" + - stat_value: + usage: "GAUGE" + description: "Index statistic value in bytes" + ``` + + This produces metrics like `mysql_innodb_index_stats_stat_value{database_name="mydb", table_name="orders", ...}`. + +3. For each column returned by your query, assign a metric type in the `usage` field: + + | Type | Description | Use case | + |------|-------------|----------| + | `GAUGE` | A value that can go up or down | Connection count, buffer pool size | + | `COUNTER` | A cumulative value that only increases | Total queries executed, bytes written | + | `LABEL` | A string dimension, not plotted as a metric | Database name, table name, status | + | `DURATION` | A time duration | Query execution time, lock wait time | + | `DISCARD` | Column is ignored and not exported | Columns returned by the query but not needed as metrics | + +## Related topics + +- [Running custom MySQL queries in PMM](https://www.percona.com/blog/running-custom-queries-in-percona-monitoring-and-management/) diff --git a/documentation/docs/install-pmm/install-pmm-client/connect-database/mysql/mysql.md b/documentation/docs/install-pmm/install-pmm-client/connect-database/mysql/mysql.md index 1749796ecdf..c55a8b75661 100644 --- a/documentation/docs/install-pmm/install-pmm-client/connect-database/mysql/mysql.md +++ b/documentation/docs/install-pmm/install-pmm-client/connect-database/mysql/mysql.md @@ -655,6 +655,10 @@ Once the service is confirmed as active, verify that metrics are being properly 2. Select your cluster service from the dropdown. 3. Verify that cluster-specific metrics are being displayed. +### Running custom queries + +To collect metrics beyond what PMM provides by default, you can define custom SQL queries for the MySQL exporter. See [Running custom queries in MySQL](custom_queries.md). + ## Related topics - [Percona Server for MySQL -- slow query log extended][ps_slow_query_ext] diff --git a/documentation/docs/install-pmm/install-pmm-client/package_manager.md b/documentation/docs/install-pmm/install-pmm-client/package_manager.md index b448f918df0..291df71db6e 100644 --- a/documentation/docs/install-pmm/install-pmm-client/package_manager.md +++ b/documentation/docs/install-pmm/install-pmm-client/package_manager.md @@ -24,7 +24,7 @@ PMM Client supports: - Red Hat/CentOS/Oracle Linux 8, 9 and 10 - Debian 11 (Bullseye), 12 (Bookworm) and 13 (Trixie) - - Ubuntu 22.04 (Jammy) and 24.04 (Noble) + - Ubuntu 22.04 (Jammy), 24.04 (Noble) and 26.04 (Resolute) - Amazon Linux 2023 The package manager will automatically select the appropriate version for your system architecture. diff --git a/documentation/docs/install-pmm/install-pmm-server/deployment-options/docker/env_var.md b/documentation/docs/install-pmm/install-pmm-server/deployment-options/docker/env_var.md index 6726c53cf2c..6036dd97063 100644 --- a/documentation/docs/install-pmm/install-pmm-server/deployment-options/docker/env_var.md +++ b/documentation/docs/install-pmm/install-pmm-server/deployment-options/docker/env_var.md @@ -166,14 +166,13 @@ Control how PMM Server presents itself on the network: | Variable | Description | |----------|-------------| -| `PMM_PUBLIC_ADDRESS` | External DNS/IP for PMM server | +| `PMM_PUBLIC_ADDRESS` | External DNS/IP for PMM Server. Also required for Nomad to start. Setting `PMM_ENABLE_NOMAD=1` without this variable has no effect. | | `PMM_INTERFACE_TO_BIND` | Network interface binding | ### Database connections Configure connections to external database services: | Variable | Purpose | -|----------|---------| | `PMM_CLICKHOUSE_CONFIG` | Set to `low-memory` to activate the built-in ClickHouse profile optimized for hosts with less than 16 GB RAM. Omit or set to `default` for standard deployments. See [ClickHouse memory issues](../../../../troubleshoot/qan_issues.md#clickhouse-memory-issues-in-low-memory-environments). | | `PMM_CLICKHOUSE_*` | ClickHouse connection settings | | `PMM_POSTGRES_*` | PostgreSQL connection settings | diff --git a/documentation/docs/install-pmm/install-pmm-server/deployment-options/docker/index.md b/documentation/docs/install-pmm/install-pmm-server/deployment-options/docker/index.md index 44fc028314b..efb19e7547c 100644 --- a/documentation/docs/install-pmm/install-pmm-server/deployment-options/docker/index.md +++ b/documentation/docs/install-pmm/install-pmm-server/deployment-options/docker/index.md @@ -1,10 +1,6 @@ # Install PMM Server with Docker -Deploy PMM Server as a Docker container for a fast, flexible and isolated setup. - -While PMM Server runs independently, we highly recommend that you streamline [upgrades via the PMM user interface](../../../../pmm-upgrade/ui_upgrade.md) by installing [Watchtower](https://containrrr.dev/watchtower/) alongside PMM Server. - -With Watchtower installed, you can easily update PMM Server directly from the **Upgrade** page or by clicking the **Upgrade Now** button on the **Home** dashboard. +Deploy PMM Server as a Docker container for a fast, flexible and isolated setup. ## Prerequisites Before installation, ensure you have: @@ -13,17 +9,6 @@ Before installation, ensure you have: - CPU with `x86-64-v2` support - [Sufficient system resources](../../../plan-pmm-installation/hardware_and_system.md) (recommended: 2+ CPU cores, 4+ GB RAM, 100+ GB disk space) -### Watchtower security requirements - -Watchtower requires access to the Docker socket to monitor and update containers. Since the Docker socket provides root-level access to the host system, it's critical to limit Watchtower's exposure to prevent potential security vulnerabilities. - -To ensure a secure setup when using Watchtower: - - - limit Watchtower's access to Docker network or localhost to prevent unauthorized external connections. See [Container network isolation guide](https://docs.docker.com/network/drivers/bridge/#use-user-defined-bridge-networks). - - configure network to ensure only PMM Server is exposed externally. See [Docker networking best practices](https://docs.docker.com/network/bridge/#manage-a-user-defined-bridge). - - secure Docker socket access for Watchtower. See [Docker socket security](https://docs.docker.com/engine/security/security/#docker-daemon-attack-surface). - - place both Watchtower and PMM Server on the same Docker network. See [Watchtower network configuration](https://containrrr.dev/watchtower/usage-overview/#docker_host). - ## Installation options ### Container setup summary @@ -35,14 +20,13 @@ To ensure a secure setup when using Watchtower: - **Access the UI**: Navigate to `https://SERVER_IP_ADDRESS` in your browser - **Log in**: Default credentials `admin` / `admin` -### Install PMM Server + Watchtower - -You can install PMM Server with Watchtower using one of two methods: +### Install PMM Server +You can install PMM Server using one of two methods: === "Easy-install script (Recommended for simplicity)" - The [Easy-install script](../docker/easy-install.md) simplifies setup by including Watchtower commands, enabling a one-step installation of PMM with Watchtower. Run the following command: + The [Easy-install script](../docker/easy-install.md) provides a one-step installation of PMM Server. Run the following command: ```sh curl -fsSL https://www.percona.com/get/pmm | /bin/bash @@ -51,36 +35,8 @@ You can install PMM Server with Watchtower using one of two methods: === "Manual installation (For customization)" For a more customizable setup, follow these steps: {.power-number} - - 1. Create a Docker network for PMM and Watchtower: - ```sh - docker network create pmm-network - ``` - - 2. (Optional but recommended) Install Watchtower to enable PMM Server upgrades via the UI: - - - Create a user-defined token to secure Watchtower's HTTP API. You can use any value or generate a secure token using `openssl` or another method. Ensure the same token is used in both the Watchtower and PMM Server configurations: - - ```sh - openssl rand -hex 16 - # Example output: - e09541c81e672bf0e48dbc72d4f92790 - ``` - - - Install Watchtower using your token: - - ```sh - docker run --detach \ - --restart always \ - --network=pmm-network \ - -e WATCHTOWER_HTTP_API_TOKEN=your_token \ - -e WATCHTOWER_HTTP_API_UPDATE=1 \ - --volume /var/run/docker.sock:/var/run/docker.sock \ - --name watchtower \ - percona/watchtower:latest - ``` - - 3. Run PMM Server with Docker based on your preferred data storage method: + + 1. Run PMM Server with Docker based on your preferred data storage method: - [Run Docker with host directory](../docker/run_with_host_dir.md) - [Run Docker with volume](../docker/run_with_vol.md) @@ -110,7 +66,7 @@ You can install PMM Server with Watchtower using one of two methods: |----------|---------|-------------| | `PMM_DATA_RETENTION` | `30d` | Duration to retain metrics data | | `PMM_METRICS_RESOLUTION` | `1s` | Base metrics collection interval | - | `PMM_ENABLE_UPDATES` | `true` | Allow version checks and UI updates | + | `PMM_ENABLE_UPDATES` | `true` | Allow version checks | | `PMM_ENABLE_TELEMETRY` | `true` | Send usage statistics | For a complete list, see the [environment variables](../docker/env_var.md). diff --git a/documentation/docs/install-pmm/install-pmm-server/deployment-options/docker/upgrade_container.md b/documentation/docs/install-pmm/install-pmm-server/deployment-options/docker/upgrade_container.md index 603c72619ef..0e84d1cdacd 100644 --- a/documentation/docs/install-pmm/install-pmm-server/deployment-options/docker/upgrade_container.md +++ b/documentation/docs/install-pmm/install-pmm-server/deployment-options/docker/upgrade_container.md @@ -8,8 +8,6 @@ Upgrade your PMM Server Docker container to the latest version, ensuring you ben Before you start upgrading, check current PMM Server version: -=== "Via command line" - ```sh docker exec -it pmm-server \ curl -ku admin:admin https://localhost/v1/version @@ -17,10 +15,6 @@ Before you start upgrading, check current PMM Server version: For remote access, replace `localhost` with your PMM Server's address. -=== "Via web UI" - - Use the **PMM Upgrade** panel on the **Home Dashboard** to check for available updates. - ## Upgrade procedure To upgrade the container: @@ -85,10 +79,6 @@ If you encounter issues after upgrading: docker rename pmm-server-backup pmm-server docker start pmm-server ``` -## Automated upgrades with Watchtower - -If you installed [PMM Server with Watchtower](../docker/index.md#install-pmm-server--watchtower), you can [upgrade directly from the PMM UI](../../../../pmm-upgrade/ui_upgrade.md). This method handles the entire upgrade process automatically, including pulling the new image and restarting the container. - ## Related topics - [Create a backup](../docker/backup_container.md) before upgrading diff --git a/documentation/docs/install-pmm/plan-pmm-installation/choose-deployment.md b/documentation/docs/install-pmm/plan-pmm-installation/choose-deployment.md index 56c9cceb147..530eca83850 100644 --- a/documentation/docs/install-pmm/plan-pmm-installation/choose-deployment.md +++ b/documentation/docs/install-pmm/plan-pmm-installation/choose-deployment.md @@ -35,7 +35,7 @@ For information on PMM's architecture, see [PMM architecture](../../reference/in ## PMM Server deployment options | **Method** | **Best for** | **Advantages** | **Considerations** | -|-----------|------------|---------------|--------------------| +|-----------|------------|---------------|-----------------| | [**:material-docker: Docker**](../install-pmm-server/deployment-options/docker/index.md) | Development, testing & production | ✔ Quick setup
✔ Simple upgrades
✔ Works in various environments | ⚠ Requires Docker knowledge
⚠ May need additional configuration for production | | [**:material-shield-lock: Podman**](../install-pmm-server/deployment-options/podman/index.md) | Security-focused setups | ✔ Rootless containers
✔ Enhanced security
✔ OCI-compatible | ⚠ Requires Podman installation & knowledge | | [**:material-kubernetes: Helm**](../install-pmm-server/deployment-options/helm/index.md) | Cloud-native environments | ✔ Scalable & high availability
✔ Kubernetes-native | ⚠ Requires existing Kubernetes cluster
⚠ More complex setup | @@ -56,7 +56,7 @@ Based on the scale and environment of your monitoring needs, we recommend differ === "Small-scale (1-30 database instances)" - - **PMM Server**: Docker or Virtual Appliance + - **PMM Server**: Docker - **PMM Client**: Package Manager - **Implementation tips**: - for Docker, use the easy install script for quick setup @@ -121,4 +121,3 @@ Review this checklist to help you plan and size your monitoring environment and [Hardware and system requirements](../plan-pmm-installation/hardware_and_system.md){.md-button} - diff --git a/documentation/docs/pmm-upgrade/index.md b/documentation/docs/pmm-upgrade/index.md index 466ca8379e7..c517cd9f268 100644 --- a/documentation/docs/pmm-upgrade/index.md +++ b/documentation/docs/pmm-upgrade/index.md @@ -3,8 +3,6 @@ !!! caution alert alert-warning "Upgrade PMM Server before Clients" - When upgrading PMM, always upgrade the PMM Server before upgrading any PMM Clients. - Make sure that the PMM Server version is higher than or equal to the PMM Client version. Mismatched versions can lead to configuration issues and failures in Client-Server communication, as the PMM Server may not recognize all parameters in the client configuration. - - For the UI upgrade option, Watchtower must be installed with PMM Server - ## Available upgrade methods Choose your preferred upgrade method based on your setup: @@ -12,5 +10,4 @@ Choose your preferred upgrade method based on your setup: * [Upgrade PMM Client](upgrade_client.md) * [Upgrade PMM Server using Docker](upgrade_docker.md) * [Upgrade PMM Server using Helm](upgrade_helm.md) -* [Upgrade PMM Server from the UI](ui_upgrade.md) (deprecated) * [Migrate from PMM 2](migrating_from_pmm_2.md) (direct migration deprecated) \ No newline at end of file diff --git a/documentation/docs/pmm-upgrade/migrating_from_pmm_2.md b/documentation/docs/pmm-upgrade/migrating_from_pmm_2.md index 6cee79cf1a3..a8182e80b91 100644 --- a/documentation/docs/pmm-upgrade/migrating_from_pmm_2.md +++ b/documentation/docs/pmm-upgrade/migrating_from_pmm_2.md @@ -434,7 +434,7 @@ The following table lists all the environment variable changes between PMM v2 an #### ClickHouse configuration | PMM 2 | PMM 3 | Comments | - |-------------------------------------|------------------------------------|--------------------------| + |-------------------------------------|------------------------------------|---------------------------| | `PERCONA_TEST_PMM_CLICKHOUSE_ADDR` | `PMM_CLICKHOUSE_ADDR` | | | `PERCONA_TEST_PMM_CLICKHOUSE_DATABASE` | `PMM_CLICKHOUSE_DATABASE` | | | `PERCONA_TEST_PMM_CLICKHOUSE_DATASOURCE` | `PMM_CLICKHOUSE_DATASOURCE` | | diff --git a/documentation/docs/pmm-upgrade/ui_upgrade.md b/documentation/docs/pmm-upgrade/ui_upgrade.md deleted file mode 100644 index 3da96971db1..00000000000 --- a/documentation/docs/pmm-upgrade/ui_upgrade.md +++ /dev/null @@ -1,37 +0,0 @@ -# Upgrade PMM Server from the UI - -!!! warning "GUI-based upgrades ending in PMM 3.9.0" - GUI-based upgrades are deprecated and will be removed in PMM 3.9.0 (end of July 2026). - - To continue upgrading PMM after version 3.9.0, use [Docker](upgrade_docker.md) (recommended), [Podman](upgrade_podman.md), or [Helm](upgrade_helm.md). - -PMM Server and Client components are installed and updated separately. - -PMM 3 Server can run natively, as a Docker image, a virtual appliance, or an AWS cloud instance. While each environment has its own specific installation and update steps, you can also upgrade from the PMM web interface using Watchtower. - -However, since this method is deprecated, we recommend switching to a manual upgrade workflow as described above. - -## Prerequisites - -To use the UI upgrade feature, you must have Watchtower installed and properly configured with your PMM Server. - -If Watchtower is not installed, the UI upgrade options will not be available. See [Running PMM Server with Watchtower](../install-pmm/install-pmm-server/deployment-options/docker/index.md) for setup instructions. - -!!! note - Since Watchtower is no longer actively maintained, new installations should use CLI or container-based upgrade methods instead. - -## Upgrade process - -1. Go to **Configuration > Updates** in your PMM web interface. Here you can check the current PMM Server version, the timestamp of the last update check, and whether your instance is up to date. -2. Click **Check Updates now**. If an update is available, click the **Update now** button to install the latest version. - -![Update page](../images/Update_page.png) - -## Quick upgrade check - -For a quick overview of your PMM v3 Server's update status, you can also check the **Upgrade** panel on the **Home** page. - -![PMM Home Dashboard Upgrade Panel](../images/PMM_Home_Dashboard_Panels_Upgrade.png) - -!!! note - The **Upgrade** panel on the Home dashboard will be removed when GUI upgrades are removed in PMM 3.9.0. After that, use `docker pull` or your container runtime's equivalent to check for updates. \ No newline at end of file diff --git a/documentation/docs/pmm-upgrade/upgrade_docker.md b/documentation/docs/pmm-upgrade/upgrade_docker.md index 35418a8bb27..df1fc3c13cb 100644 --- a/documentation/docs/pmm-upgrade/upgrade_docker.md +++ b/documentation/docs/pmm-upgrade/upgrade_docker.md @@ -5,11 +5,9 @@ Before starting the upgrade, complete these preparation steps to ensure you can recover your system if needed and confirm compatibility with the new version: {.power-number} -1. If you are switching from [UI-based upgrades](ui_upgrade.md), stop and remove the Watchtower container before moving to manual Docker upgrades. UI-based upgrades used Watchtower to apply PMM images automatically. If Watchtower is still running, it may update PMM during your manual upgrade and cause conflicts. +1. [Create a backup](../install-pmm/install-pmm-server/deployment-options/docker/backup_container.md) before upgrading, as downgrades are not possible. Therefore, reverting to a previous version requires a backup made prior to the upgrade. -2. [Create a backup](../install-pmm/install-pmm-server/deployment-options/docker/backup_container.md) before upgrading, as downgrades are not possible. Therefore, reverting to a previous version requires an backup made prior to the upgrade. - -3. Verify your current PMM version: Check your current PMM version by navigating to **Configuration > Updates** or by running the following command: +2. Verify your current PMM version: Check your current PMM version by navigating to **Configuration > Updates** or by running the following command: ```sh docker exec -it pmm-server curl -ku admin:admin https://localhost:8443/v1/version diff --git a/documentation/docs/pmm-upgrade/upgrade_podman.md b/documentation/docs/pmm-upgrade/upgrade_podman.md index c9a504e3035..8348e1c3103 100644 --- a/documentation/docs/pmm-upgrade/upgrade_podman.md +++ b/documentation/docs/pmm-upgrade/upgrade_podman.md @@ -5,11 +5,9 @@ Before starting the upgrade, complete these preparation steps to ensure you can recover your system if needed and confirm compatibility with the new version: {.power-number} -1. If you are switching from [UI-based upgrades](ui_upgrade.md), stop and remove the Watchtower container before moving to manual Podman upgrades. UI-based upgrades used Watchtower to apply PMM images automatically. If Watchtower is still running, it may update PMM during your manual upgrade and cause conflicts. +1. [Create a backup](../install-pmm/install-pmm-server/deployment-options/podman/backup_container_podman.md) before upgrading, as downgrades are not possible. Therefore, reverting to a previous version requires a backup made prior to the upgrade. -2. [Create a backup](../install-pmm/install-pmm-server/deployment-options/podman/backup_container_podman.md) before upgrading, as downgrades are not possible. Therefore, reverting to a previous version requires an backup made prior to the upgrade. - -3. Verify your current PMM version: Check your current PMM version by navigating to **Configuration > Updates** or by running the following command: +2. Verify your current PMM version: Check your current PMM version by navigating to **Configuration > Updates** or by running the following command: ```sh podman exec -it pmm-server \ diff --git a/documentation/docs/quickstart/quickstart.md b/documentation/docs/quickstart/quickstart.md index 9af18a73cdf..c5d7f96c3a0 100644 --- a/documentation/docs/quickstart/quickstart.md +++ b/documentation/docs/quickstart/quickstart.md @@ -1,6 +1,6 @@ # Get started with PMM -To get up and running with Percona Monitoring and Management (PMM) in no time, install PMM on Bare Metal/Virtual using the Easy-install script for Docker. +To get up and running with Percona Monitoring and Management (PMM) in no time, install PMM on Bare Metal using the Easy-install script for Docker. This is the simplest and most efficient way to install PMM with Docker. @@ -255,7 +255,7 @@ Once PMM is set up, choose the database or the application that you want it to m }, { "resource": { "db": "", "collection": "system.profile" }, - "actions": [ "dbStats", "collStats", "indexStats" ] + "actions": [ "find", "dbStats", "collStats", "indexStats" ] } ], "roles": [] diff --git a/documentation/docs/reference/dashboards/dashboard-postgresql-topqueries.md b/documentation/docs/reference/dashboards/dashboard-postgresql-topqueries.md index 3b85ecbe2be..b56110cb6b8 100644 --- a/documentation/docs/reference/dashboards/dashboard-postgresql-topqueries.md +++ b/documentation/docs/reference/dashboards/dashboard-postgresql-topqueries.md @@ -4,7 +4,6 @@ This dashboard analyzes query performance across your PostgreSQL instances, help ![PMM PostgreSQL Top Queries](../../images/PMM_PostgreSQL_Top_Queries.png) - ### Transactions per Second Shows the rate of committed transactions for each PostgreSQL instance. The metric combines both regular and replicated transactions, displayed as operations per second with step interpolation for accurate counting between data points. @@ -48,4 +47,28 @@ Investigate these queries for potential optimization because they represent the ### Top 10 User Executed the most queries Shows which database users generated the most query activity across your PostgreSQL infrastructure. -Use this to identify heavy database users and understand usage patterns that may require capacity planning or access optimization. \ No newline at end of file +Use this to identify heavy database users and understand usage patterns that may require capacity planning or access optimization. + +### Top 10 CPU Intensive Queries + +Shows queries that consumed the most total CPU time (user + system) across your PostgreSQL services. Requires `pg_stat_monitor`. + +Use this to identify queries driving CPU pressure during high-load incidents. Focus optimization on the top entries, reducing CPU time for these queries will have the most direct impact on server headroom. + +### Top 10 Memory Intensive Queries + +Shows queries that wrote the most data to temporary blocks, indicating high memory spill to disk. High temp block usage means the query exceeded available `work_mem` and had to offload intermediate results to disk. Requires `pg_stat_statements` or `pg_stat_monitor`. + +Use this to find queries that would benefit from increased `work_mem` or query restructuring to reduce sort and hash operations. + +### Top 10 Queries by I/O Wait + +Shows queries that spent the most time waiting on disk reads and writes. High I/O wait time indicates queries that are bottlenecked on storage rather than CPU or memory. Requires `track_io_timing = on`. + +Use this to identify candidates for indexing, partition pruning, or caching improvements. + +### Top 10 Queries by Shared Block Reads (Sequential Scan Indicator) + +Shows queries with the highest average shared block reads per execution, serving as a sequential scan indicator. A high value suggests the query is reading large portions of a table rather than using an index. Requires `pg_stat_statements` or `pg_stat_monitor`. + +Use this to find queries that are likely missing indexes or that would benefit from query restructuring to avoid full table scans. \ No newline at end of file diff --git a/documentation/docs/reference/nomad.md b/documentation/docs/reference/nomad.md index 1c753271c62..650b12d635e 100644 --- a/documentation/docs/reference/nomad.md +++ b/documentation/docs/reference/nomad.md @@ -10,12 +10,20 @@ Percona Monitoring and Management (PMM) includes HashiCorp Nomad to enable futur Nomad is **disabled by default** in PMM and has no impact on system performance when not enabled. -## Prerequisites +## Set a public address + +Before enabling Nomad, set a public address for PMM Server. Nomad won't start without it, even if `PMM_ENABLE_NOMAD=1` is set. + +Set the public address using either: + +- **Environment variable**: pass `-e PMM_PUBLIC_ADDRESS=` when starting the container +- **UI**: go to **Configuration > Settings > Advanced settings** and set the public address, then restart PMM Server. + Nomad requires **both** of the following to start: -- `PMM_ENABLE_NOMAD=1` — enables the Nomad feature flag -- `PMM_PUBLIC_ADDRESS=` — the publicly reachable address of your PMM Server +- `PMM_ENABLE_NOMAD=1`: enables the Nomad feature flag +- `PMM_PUBLIC_ADDRESS=`: the publicly reachable address of your PMM Server Setting `PMM_ENABLE_NOMAD=1` alone is not sufficient. If `PMM_PUBLIC_ADDRESS` is not set, PMM silently skips starting the Nomad server process with no error or warning. @@ -26,10 +34,10 @@ You can set the public address either as an environment variable at container st If you're an advanced user who needs Nomad for specific use cases, follow these steps to enable Nomad in PMM: { .power-number } -1. Start PMM Server with the `PMM_ENABLE_NOMAD` and `PMM_PUBLIC_ADDRESS` environment variables: +1. Start PMM Server with both `PMM_PUBLIC_ADDRESS` and `PMM_ENABLE_NOMAD` set: ``` - -e PMM_ENABLE_NOMAD=1 \ - -e PMM_PUBLIC_ADDRESS= + -e PMM_PUBLIC_ADDRESS= \ + -e PMM_ENABLE_NOMAD=1 ``` 2. Expose the Nomad port: @@ -41,6 +49,7 @@ If you're an advanced user who needs Nomad for specific use cases, follow these ``` docker run -d \ + -e PMM_PUBLIC_ADDRESS= \ -e PMM_ENABLE_NOMAD=1 \ -e PMM_PUBLIC_ADDRESS= \ -p 4647:4647 \ diff --git a/documentation/docs/reference/ui/ui_components.md b/documentation/docs/reference/ui/ui_components.md index b5a82c026d5..51d3d61daf4 100644 --- a/documentation/docs/reference/ui/ui_components.md +++ b/documentation/docs/reference/ui/ui_components.md @@ -18,7 +18,7 @@ You'll find these options in the left-side menu: | Icon | Name | What you can do | |:----:|------|-----------------| -| :material-home-outline: | Home | Access the main dashboard with overview panels for database connections, queries, anomaly detection, and upgrade status. | +| :material-home-outline: | Home | Access the main dashboard with overview panels for database connections, queries, and anomaly detection. | | :simple-mysql: | MySQL | View specialized dashboards for MySQL database performance monitoring. | | :simple-postgresql: | PostgreSQL | Access PostgreSQL-specific monitoring dashboards and metrics. | | :material-monitor-dashboard:| Operating System | Monitor server-level metrics including CPU, memory, disk, and network performance. | @@ -80,4 +80,4 @@ Explore metrics lets you visually browse and filter available metrics without wr This adds the **Explore metrics** option under **Explore** in the left sidebar. For more information, see [Grafana Metrics Drilldown](https://grafana.com/docs/grafana-cloud/visualizations/simplified-exploration/metrics). -![Explore metrics in the PMM sidebar](../../images/PMM_Explore_metrics.jpg) +![Explore metrics in the PMM sidebar](../../images/PMM_Explore_metrics.png) diff --git a/documentation/docs/release-notes/3.5.0.md b/documentation/docs/release-notes/3.5.0.md index 3ec47449237..f21cd591f78 100644 --- a/documentation/docs/release-notes/3.5.0.md +++ b/documentation/docs/release-notes/3.5.0.md @@ -52,7 +52,7 @@ For this, PMM includes ten dedicated Valkey/Redis dashboards that help you monit To get started, see [Connect Valkey and Redis databases to PMM](../install-pmm/install-pmm-client/connect-database/valkey-redis.md). -![Valkey Overview Dashboard](Valkey_Overview_Dashboard.png) +![Valkey Overview Dashboard](../images/Valkey_Overview_Dashboard.png) ### PostgreSQL 18 Community support PMM now supports PostgreSQL 18 Community Edition, with full compatibility for dashboards and Query Analytics. diff --git a/documentation/docs/release-notes/3.7.0.md b/documentation/docs/release-notes/3.7.0.md index f92c7c1660c..fa63c40ea8d 100644 --- a/documentation/docs/release-notes/3.7.0.md +++ b/documentation/docs/release-notes/3.7.0.md @@ -267,7 +267,7 @@ To lower risk further, Percona recommends that you: - [PMM-14412](https://perconadev.atlassian.net/browse/PMM-14412): Added `pmm-admin inventory change agent` command to update MongoDB agent configurations without removing and re-adding services. -- [PMM-14722](https://perconadev.atlassian.net/browse/PMM-14722): Added a low-memory ClickHouse configuration for PMM Server environments with less than 16 GB RAM. If you see "memory limit exceeded" errors in ClickHouse logs or experience performance issues when working with QAN, you can switch to the optimized configuration using the `switch-config.sh` script. See [ClickHouse memory issues](../troubleshoot/qan_issues.md#clickhouse-memory-issues-in-low-memory-environments) for details. +- [PMM-14722](https://perconadev.atlassian.net/browse/PMM-14722): Added a low-memory ClickHouse configuration for PMM Server environments with less than 16 GB RAM. If you see "memory limit exceeded" errors in ClickHouse logs or experience performance issues when working with QAN, you can switch to the optimized configuration using the `switch-config.sh` script. See [ClickHouse memory issues](../troubleshoot/qan_issues.md#clickhouse-memory-issues-in-low-memory-environments) for details. As of PMM 3.9.0, use the `PMM_CLICKHOUSE_CONFIG` environment variable instead. The `switch-config.sh` script is deprecated. - [PMM-14818](https://perconadev.atlassian.net/browse/PMM-14818): Improved performance for PostgreSQL instances with many databases (multitenant designs). The `pg_custom_database_size_custom` query now runs at low resolution (60 seconds by default) instead of high resolution (5 seconds). This significantly reduces CPU usage on servers with hundreds of databases. diff --git a/documentation/docs/release-notes/3.9.0.md b/documentation/docs/release-notes/3.9.0.md new file mode 100644 index 00000000000..65fc5985b01 --- /dev/null +++ b/documentation/docs/release-notes/3.9.0.md @@ -0,0 +1,262 @@ +# Percona Monitoring and Management 3.9.0 + +**Release date**: 30 July 2026 + +Percona Monitoring and Management (PMM) is an open source database monitoring, management, and observability solution for MySQL, PostgreSQL, MongoDB, Valkey and Redis. PMM empowers you to: + +- monitor the health and performance of your database systems +- identify patterns and trends in database behavior +- diagnose and resolve issues faster with actionable insights +- manage databases across on-premises, cloud, and hybrid environments + +## 📋 Release summary + +PMM 3.9.0 introduces the **Alert Status** page for viewing all active alerts by node or service, new MongoDB and PostgreSQL dashboard panels, and CSV export for Real-Time Analytics data. + +This release also removes the provisioned PostgreSQL datasource as a security measure, adds Ubuntu 26.04 LTS support for PMM Client, and includes a large number of dashboard, UI, and stability fixes. + +### Alert Status page: view alerts by node or service + +You can now check the full alert picture for any node or service in a single view. Go to **Alerts > Status** and filter by service or group by node to see every associated alert rule and its current state, so you don't have to piece together the situation from alerts grouped by alert name. + +All built-in PMM alert templates work with this view automatically. If you use custom templates, you can add `node_name` and `service_name` labels to make your alerts appear here too. To learn how, see [View alert status by node or service](../alert/alert_status.md). + +### Removed provisioned PostgreSQL datasource + +PMM no longer includes a preconfigured PostgreSQL datasource for internal dashboard panels. + +This change prevents authenticated users, including users with the **Viewer** role, from using the datasource to run arbitrary or destructive SQL queries against PMM's internal database. + +Since the Grafana PostgreSQL datasource does not support a read-only mode, removing the provisioned datasource is the most effective way to eliminate this risk. If you need it, you can [add it manually](../admin/security/index.md#postgresql-datasource). + +This update completes the security hardening that began in [PMM 3.7.0](3.7.0.md), which addressed a remote code execution vulnerability in the same datasource ([CVE-2026-25212](https://nvd.nist.gov/vuln/detail/CVE-2026-25212)). + +### Data size monitoring for MongoDB replica sets and sharded clusters + +You can now monitor data growth across your MongoDB deployments and plan capacity from the [MongoDB ReplSet Summary](https://docs.percona.com/percona-monitoring-and-management/3/reference/dashboards/dashboard-mongodb-replset-summary.html) and [MongoDB Sharded Cluster Summary](https://docs.percona.com/percona-monitoring-and-management/3/reference/dashboards/dashboard-mongodb-cluster-summary.html) dashboards. Each dashboard includes two new panels for tracking data size: + +- **Total data size**: shows how much space your data and indexes currently occupy, so you know exactly where your deployment stands at any point in time. +- **Data size over time**: plots the same total over the selected time range, so you can spot growth trends and make informed capacity decisions. + +These panels require the `dbstats` collector on the MongoDB exporter. To enable it, pass [`--enable-all-collectors`](https://docs.percona.com/percona-monitoring-and-management/3/use/commands/pmm-admin/add.html) when adding your MongoDB service with `pmm-admin add mongodb`, or update an existing service with `pmm-admin inventory change agent`. + +### Disable individual metric collectors per service + +PMM 3.9.0 adds a **Disable collectors** field to the Add service form for MySQL, PostgreSQL, MongoDB, and ProxySQL. You can now exclude specific metric collectors from collection without removing the service or modifying the exporter configuration. + +This is useful when certain collectors generate metrics you don't need, add overhead on resource-constrained hosts, or cause issues with specific database configurations. + +![Disable collectors field in Additional options](../images/PMM_disable_collectors.png) + +To use it, go to **PMM Configuration > Add Service**, expand **Additional options**, and enter a comma-separated list of collector names in the **Disable collectors** field. + +For the full list of available collectors per database type, see [Connect MySQL databases to PMM](../install-pmm/install-pmm-client/connect-database/mysql/mysql.md) and [Connect PostgreSQL databases to PMM](../install-pmm/install-pmm-client/connect-database/postgresql.md). + +### New panels on the PostgreSQL Top Queries dashboard + +The [PostgreSQL Top Queries](../reference/dashboards/dashboard-postgresql-topqueries.md)dashboard now includes four new panels to help you pinpoint queries that are putting the most pressure on your database: + +- **Top 10 CPU Intensive Queries**: identifies queries consuming the most CPU time (requires pg_stat_monitor) +- **Top 10 Memory Intensive Queries**: surfaces queries that write the most to temporary blocks (requires pg_stat_statements or `pg_stat_monitor`) +- **Top 10 Queries by I/O Wait**: highlights queries spending the most time waiting on disk reads and writes (requires track_io_timing = on) +- **Top 10 Queries by Shared Block Reads**: ranks queries by average shared blocks read per execution, serving as a sequential scan indicator (requires `pg_stat_statements` or `pg_stat_monitor`) + +![New panels on PostgreSQL Top Queries dashboard](../images/pg-panels.png) + +### Export Real-Time Analytics (RTA) data to CSV + +You can now export a snapshot of the RTA view to a CSV file. Because QAN only records queries after they complete, this gives you a way to preserve data from long-running queries that are killed before finishing. + +![Export RTA button](../images/ExportRTA.png) + +See [Export RTA data](../use/qan/QAN-realtime-analytics.md#export-data) for step-by-step instructions and a reference of all exported fields. + +### PMM Server UI upgrade removed + +As announced in [PMM 3.7.0](../release-notes/3.7.0.md#added-support-and-deprecations), PMM 3.9.0 removes the **Upgrade Now** button, UI-based upgrade functionality, and Watchtower from the PMM Server image. + +PMM still notifies you when a new version is available, but you must now upgrade from the command line using one of the supported methods: + +* **[Docker upgrade](../pmm-upgrade/upgrade_docker.md) (recommended)**: pull the latest image and restart the container +* [Podman upgrade](../pmm-upgrade/upgrade_podman.md): same container workflow with rootless execution +* [Helm upgrade](../pmm-upgrade/upgrade_helm.md): Kubernetes-native upgrade path + +If you were running Watchtower as a standalone container, you can remove it. + +### Added support and deprecations + +#### Ubuntu 26.04 LTS support for PMM Client + +PMM Client now supports Ubuntu 26.04 LTS (Resolute) on AMD64 and ARM64. You can use PMM to monitor Percona Distribution for PostgreSQL 18, Percona Server for MySQL 8.4, and Valkey 9.1 databases running on Ubuntu 26.04. + +To get started, [install PMM Client](../install-pmm/install-pmm-client/package_manager.md) on your Ubuntu 26.04 system. + +## 🔒 Security updates + +### Go standard library symlink traversal vulnerability ([CVE-2026-39822](https://nvd.nist.gov/vuln/detail/CVE-2026-39822)) + +HIGH severity. Fixed in `percona-telemetry-agent` by rebuilding on Go 1.26.5. + +### Remaining third-party security risks + +PMM, like all complex software, includes third-party components. Some vulnerabilities in those components couldn't be fixed in this release because upstream fixes weren't yet available. + +Percona assessed each one and considers the risk low for typical PMM deployments. Affected dependencies will be updated as fixes become available. + +### gRPC-Go xDS RBAC and HTTP/2 vulnerabilities ([GHSA-hrxh-6v49-42gf](https://github.com/advisories/GHSA-hrxh-6v49-42gf)) + +#### Affected components +Nomad, VictoriaMetrics, Grafana, and Grafana ClickHouse Datasource plugin (third-party dependencies using `google.golang.org/grpc` < 1.82.1). + +#### Why this is hard to exploit in PMM +This advisory covers three issues: an xDS RBAC authorization bypass, an HTTP/2 Rapid Reset DoS bypass, and an xDS RBAC panic via crafted policies. The two xDS issues require an xDS management server delivering RBAC policies — PMM does not use xDS service discovery or RBAC policies in any component, so those attack paths do not exist in a PMM deployment. The HTTP/2 DoS requires direct access to a gRPC server port. In PMM, all affected components communicate internally within the PMM Server container and are not directly exposed to external networks. Nomad is disabled by default. + +#### Mitigating factors +- PMM does not configure xDS or xDS-based RBAC policies in any component. +- All affected components are bound to internal interfaces within the PMM Server container. +- Nomad is disabled by default and requires explicit enablement. + +#### Risk decision +This will be addressed in a future dependency update once upstream ships the fix. + +### kin-openapi authentication bypass ([GHSA-r277-6w6q-xmqw](https://github.com/advisories/GHSA-r277-6w6q-xmqw)) + +#### Affected component +Grafana binary (third-party dependency, `github.com/getkin/kin-openapi` v0.133.0, fixed in v0.144.0). + +#### Why this is hard to exploit in PMM +This vulnerability causes `ValidationHandler.Load()` to fail open, defaulting to `NoopAuthenticationFunc` when loading OpenAPI specs, potentially bypassing authentication. In PMM, Grafana's OpenAPI validation is not exposed as a standalone endpoint. Access to Grafana requires PMM authentication, and the vulnerable code path is not reachable without prior authenticated access. + +#### Mitigating factors +- PMM authentication is required before any Grafana endpoint is reachable. +- The vulnerable `ValidationHandler.Load()` path is not invoked by PMM's Grafana configuration. + +#### Risk decision +This will be addressed in a future dependency update once upstream ships the fix. + +### Go standard library symlink traversal in ClickHouse Datasource ([CVE-2026-39822](https://nvd.nist.gov/vuln/detail/CVE-2026-39822)) + +#### Affected component +Grafana ClickHouse Datasource plugin (third-party, not Percona-maintained). Built on Go 1.26.4. Fix requires Go 1.26.5 or later. + +#### Why this is hard to exploit in PMM +The plugin only connects to PMM's internal ClickHouse instance over localhost. No external or user-controlled file paths reach this code path in a standard PMM deployment. + +#### Mitigating factors +- The plugin only connects to ClickHouse within the PMM Server container. +- No untrusted external input reaches the ClickHouse datasource without prior PMM authentication. + +#### Risk decision +This will be addressed once the upstream plugin is rebuilt with Go 1.26.5 or later. + +### Grafana Tempo denial of service and information disclosure ([CVE-2026-21728](https://nvd.nist.gov/vuln/detail/CVE-2026-21728) & [CVE-2026-28377](https://nvd.nist.gov/vuln/detail/CVE-2026-28377)) + +#### Affected component +Grafana binary (Tempo is compiled into Grafana as an optional datasource plugin). + +#### Why this is hard to exploit in PMM +Tempo is a distributed tracing backend. PMM does not use Tempo, does not configure a Tempo datasource, and does not accept tracing data. The denial of service via large queries and S3 encryption key disclosure via status endpoint cannot be triggered in a PMM deployment. + +#### Mitigating factors +- PMM does not configure or enable the Tempo datasource. +- No PMM component sends or receives tracing data through Tempo. +- The vulnerable endpoints are not exposed in PMM's Grafana configuration. + +#### Risk decision +This will be addressed in a future dependency update once upstream ships the fix. + +### Prometheus library information disclosure ([CVE-2026-42151](https://nvd.nist.gov/vuln/detail/CVE-2026-42151)) + +#### Affected component +Affects the Prometheus library embedded in Grafana for PromQL evaluation. + +#### Why this is hard to exploit in PMM +PMM uses VictoriaMetrics as its metrics backend, not Prometheus. This CVE discloses Azure OAuth client secrets via the Prometheus config API. PMM does not use Azure OAuth for Prometheus, and the config API is not exposed externally. + +#### Mitigating factors +- PMM authentication is required to access Grafana and execute queries. +- PMM does not use Azure OAuth or Prometheus remote read. + +#### Risk decision +This will be addressed in a future dependency update once upstream ships the fix. + +### How to reduce risk + +To lower your exposure in the meantime: + +- restrict network access to PMM Server to trusted networks and users. +- keep the number of PMM admins small and enforce strong authentication. +- apply resource limits to PMM Server containers where possible. + +## 📈 Improvements + +- [PMM-14931](https://perconadev.atlassian.net/browse/PMM-14931): You can now set ClickHouse memory configuration using the `PMM_CLICKHOUSE_CONFIG` environment variable instead of running `switch-config.sh` manually after each restart or upgrade. The `switch-config.sh` script is now deprecated. +- [PMM-14502](https://perconadev.atlassian.net/browse/PMM-14502): Added a dedicated topic for [running custom queries on MySQL](../install-pmm/install-pmm-client/connect-database/mysql/custom_queries.md) so that you can collect any MySQL metric accessible via SQL and monitor it in PMM alongside your standard dashboards. +- [PMM-14610](https://perconadev.atlassian.net/browse/PMM-14610): You can now export a snapshot of the Real-Time Analytics (RTA) view to a CSV file. This lets you preserve data from long-running queries that are killed before finishing, which QAN would otherwise not record. +- [PMM-13306](https://perconadev.atlassian.net/browse/PMM-13306): Added data size panels to the **MongoDB ReplSet Summary** and **MongoDB Sharded Cluster Summary** dashboards to help you monitor data growth and plan capacity. +- [PMM-14618](https://perconadev.atlassian.net/browse/PMM-14618): Added a **Disable collectors** field to the **Add service** page for MySQL, PostgreSQL, MongoDB, ProxySQL, and RDS instances. You can now exclude specific metric collectors without modifying the exporter configuration. +- [PMM-15082](https://perconadev.atlassian.net/browse/PMM-15082): Added PMM Client support for Ubuntu 26.04 LTS (Resolute) on AMD64 and ARM64, including monitoring support for Percona Distribution for PostgreSQL 18, Percona Server for MySQL 8.4, and Valkey 9.1. +- [PMM-15139](https://perconadev.atlassian.net/browse/PMM-15139): PMM no longer ships a provisioned PostgreSQL datasource. Viewer-role users could use it to run arbitrary SQL against PMM's internal database. You can still [add the datasource manually](../admin/security/index.md#postgresql-datasource) if you need it. +- [PMM-14076](https://perconadev.atlassian.net/browse/PMM-14076): Added four new panels to the **PostgreSQL Top Queries** dashboard to help you identify queries causing high CPU, memory, and I/O pressure: **Top 10 CPU Intensive Queries** (requires `pg_stat_monitor`), **Top 10 Memory Intensive Queries**, **Top 10 Queries by I/O Wait** (requires `track_io_timing = on`), and **Top 10 Queries by Shared Block Reads** as a sequential scan indicator. +- [PMM-14969](https://perconadev.atlassian.net/browse/PMM-14969): Removed the UI-based upgrade functionality and Watchtower from PMM Server. PMM Server must be upgraded via CLI or container runtime. +- [PMM-15246](https://perconadev.atlassian.net/browse/PMM-15246): MongoDB diagnostic data histograms are now disabled by default to reduce `mongodb_exporter` memory usage. If you were relying on these metrics, enable them explicitly with `--enable-diagnostic-data-histograms` when adding or updating a MongoDB service. Make sure to set this option separately, as `--enable-all-collectors` does not include it. +- [PMM-15095](https://perconadev.atlassian.net/browse/PMM-15095): The `get-pmm.sh` migration script now detects your installed PMM version. If you are running PMM 2, it downloads PMM 3.8.1, the last version that supports migration from PMM 2, after which you can upgrade to the latest PMM 3 using the standard upgrade method. If you are already on PMM 3, it downloads the latest release. +- [PMM-14895](https://perconadev.atlassian.net/browse/PMM-14895): Updated the **Replication Roles** section of the [Valkey/Redis Cluster Details](../reference/dashboards/dashboard-valkey-redis-cluster-details.md) dashboard to use `Primary` and `Replica` instead of the outdated `master`/`slave` terminology. +- [PMM-14896](https://perconadev.atlassian.net/browse/PMM-14896): Valkey dashboards now show PMM event annotations on graphs, consistent with MySQL, MongoDB, and PostgreSQL dashboards. +- [PMM-14911](https://perconadev.atlassian.net/browse/PMM-14911): Added the **Alert Status** page (**Alerts > Status**) for viewing all active alerts grouped by node or service. Use it to see every alert affecting a specific node or service in a single view, filter by state, and silence alerts directly from the table. + +## ✅ Fixed issues + +- [PMM-14717](https://perconadev.atlassian.net/browse/PMM-14717): Fixed a documentation issue in the [MongoDB connection guide](../install-pmm/install-pmm-client/connect-database/mongodb.md) where the `createRole` command was missing the `find` permission on `system.profile`, causing QAN to show no query data. If you set up MongoDB monitoring using the previous instructions, re-run the role creation with the corrected command. +- [PMM-15130](https://perconadev.atlassian.net/browse/PMM-15130): Fixed an issue where `pmm-admin inventory change agent` would save new database credentials without validating them. When rotating credentials from the command line, PMM now returns an error if the credentials are invalid. To bypass validation when the database is temporarily unreachable, use [--skip-connection-check](../use/commands/pmm-admin/inventory.md#connection-and-authentication). +- [PMM-14921](https://perconadev.atlassian.net/browse/PMM-14921): Clarified the [Configure Nomad](../reference/nomad.md) instructions. Nomad won't start if `PMM_ENABLE_NOMAD=1` is set without `PMM_PUBLIC_ADDRESS`. The prerequisites section and Docker examples now show that both variables are required together. + +- [PMM-14661](https://perconadev.atlassian.net/browse/PMM-14661): Fixed PMM Server becoming unresponsive when viewing stored metrics in Query Analytics for data older than one week. + +- [PMM-15029](https://perconadev.atlassian.net/browse/PMM-15029): Fixed an issue where the auto-generated PostgreSQL password for PMM HA could contain `:` or `@` characters, producing an invalid URI and preventing Grafana from connecting to the database on startup. + +- [PMM-15030](https://perconadev.atlassian.net/browse/PMM-15030): Fixed missing metrics data when PMM is configured to use an external VictoriaMetrics instance via `PMM_VM_URL`. If you saw gaps in your dashboards or `vmagent` errors after setting this variable, this fix resolves the issue. + +- [PMM-14576](https://perconadev.atlassian.net/browse/PMM-14576): Fixed an issue where MongoDB backups completed successfully in PBM but PMM failed to detect this, reporting them as failed in the **Status** column on the **Backup > All Backups** page. + +- [PMM-14193](https://perconadev.atlassian.net/browse/PMM-14193), [PMM-15145](https://perconadev.atlassian.net/browse/PMM-15145): Fixed the built-in **MySQL Down**, **MongoDB Down**, **PostgreSQL Down**, **Valkey Down**, and **Redis Down** alerts incorrectly resolving to **Normal** when both the database and its PMM agent go down at the same time. The alert now correctly stays in **Firing** state even when metrics stop being reported. + +- [PMM-14519](https://perconadev.atlassian.net/browse/PMM-14519): Fixed MySQL services failing to connect when `--tls-skip-verify` was set on a database server with TLS disabled. PMM incorrectly treated `tls_skip_verify: true` as a request to use TLS, causing the agent to report `TLS requested but server does not support TLS` and stop collecting metrics. + +- [PMM-13910](https://perconadev.atlassian.net/browse/PMM-13910): Fixed **Top Hottest Collections by Read** and **Top Hottest Collections by Write** panels in the **MongoDB Sharded Cluster Summary** and **MongoDB Collections Overview** dashboards showing only internal collections instead of the busiest user collections. + +- [PMM-15118](https://perconadev.atlassian.net/browse/PMM-15118): Fixed the **Oplog GB/Hour** panels in the **MongoDB ReplSet Summary**, **MongoDB Sharded Cluster Summary**, and **MongoDB Oplog Details** dashboards showing an empty metric name in the legend instead of the service name. + +- [PMM-15114](https://perconadev.atlassian.net/browse/PMM-15114): Fixed the **Scanned and Moved Objects** panel in the **MongoDB Instance Summary** dashboard showing blank labels in the legend instead of the operation type (`scanned`, `scanned_objects`). + +- [PMM-15242](https://perconadev.atlassian.net/browse/PMM-15242): When you ran `pmm-admin` on the command line without any arguments, PMM Client crashed or showed nothing instead of displaying the available commands. This is now fixed. + +- [PMM-15200](https://perconadev.atlassian.net/browse/PMM-15200): PMM Client now automatically reconnects to PMM Server after a silent network drop, instead of staying disconnected until you restart it manually. + +- [PMM-15174](https://perconadev.atlassian.net/browse/PMM-15174): Fixed broken **Read more** links in advisor check results that were returning 404 errors. + +- [PMM-15165](https://perconadev.atlassian.net/browse/PMM-15165): The **Cluster** filter in the [MongoDB Router Summary](../reference/dashboards/dashboard-mongodb-router-summary.md) dashboard was empty and returned no data. This is now fixed. +- [PMM-15164](https://perconadev.atlassian.net/browse/PMM-15164): The left navigation menu was missing when accessing PMM in anonymous mode. This is now fixed. + +- [PMM-15163](https://perconadev.atlassian.net/browse/PMM-15163): MongoDB physical backup restores failed because PMM could not restart the mongod service after restoring, leaving the replica set down. This is now fixed. + +- [PMM-15155](https://perconadev.atlassian.net/browse/PMM-15155): After upgrading PMM, the [PostgreSQL Overview](../reference/dashboards/dashboard-postgresql-instances-overview.md) dashboard showed a `Datasource not found` error. This is now fixed. + +- [PMM-15138](https://perconadev.atlassian.net/browse/PMM-15138): Users with the **Viewer** role could create, update, and delete alert templates, which is an Admin-only operation. This is now fixed. +- [PMM-15076](https://perconadev.atlassian.net/browse/PMM-15076): The [NUMA Details dashboard](../reference/dashboards/dashboard-numa-details.md) only showed NUMA Node 0 instead of all available nodes. You can now select individual nodes or view all nodes at once from the **Node** dropdown. +- [PMM-15074](https://perconadev.atlassian.net/browse/PMM-15074): Custom labels added to an existing service through the PMM UI were not saved or visible in metrics, Explore, or QAN. This is now fixed. +- [PMM-15050](https://perconadev.atlassian.net/browse/PMM-15050): Large PMM deployments could not be restarted or upgraded without causing a flood of buffered data from reconnecting agents, overwhelming the server. You can now control the ingestion rate by setting the `VM_maxIngestionRate` environment variable on PMM Server. +- [PMM-14971](https://perconadev.atlassian.net/browse/PMM-14971): After changing a user's password, the left navigation menu remained visible on the login page instead of PMM redirecting you to a full-screen login page. This is now fixed. + +- [PMM-14947](https://perconadev.atlassian.net/browse/PMM-14947): Typing in the search filter on the **Nodes** or **Services** page caused records to flicker and the page to become unresponsive. This is now fixed. +- [PMM-14885](https://perconadev.atlassian.net/browse/PMM-14885): The **Replicas** panel in the [PostgreSQL Replication Overview](../reference/dashboards/dashboard-postgresql-replication.md) dashboard showed no data due to an invalid query. This is now fixed. +- [PMM-14734](https://perconadev.atlassian.net/browse/PMM-14734): The HA status badge in the navigation always showed **Healthy** even when nodes were down. It now correctly shows **Degraded**, **Critical**, or **Down** based on the actual number of available nodes. +- [PMM-14360](https://perconadev.atlassian.net/browse/PMM-14360): The **Disk I/O Total** panel on MongoDB dashboards showed only disk writes instead of the sum of disk reads, disk writes, swap in, and swap out. This is now fixed. +- [PMM-15079](https://perconadev.atlassian.net/browse/PMM-15079): Graph panel legends were no longer sorted by average by default after a Grafana plugin update. This is now fixed. + +## 🚀 Ready to upgrade to PMM 3.9.0? + +- [New installation](../quickstart/quickstart.md) +- [Upgrading from PMM 3](../pmm-upgrade/index.md) +- [Upgrading from PMM 2](../pmm-upgrade/migrating_from_pmm_2.md) + diff --git a/documentation/docs/release-notes/index.md b/documentation/docs/release-notes/index.md index fa0a3b98b33..6facb302a98 100644 --- a/documentation/docs/release-notes/index.md +++ b/documentation/docs/release-notes/index.md @@ -1,4 +1,5 @@ # Release notes +- [Percona Monitoring and Management 3.9.0](3.9.0.md) - [Percona Monitoring and Management 3.8.1](3.8.1.md) - [Percona Monitoring and Management 3.8.0](3.8.0.md) - [Percona Monitoring and Management 3.7.1](3.7.1.md) diff --git a/documentation/docs/troubleshoot/qan_issues.md b/documentation/docs/troubleshoot/qan_issues.md index a15f27a1944..f3a174d0aef 100644 --- a/documentation/docs/troubleshoot/qan_issues.md +++ b/documentation/docs/troubleshoot/qan_issues.md @@ -85,24 +85,34 @@ This happens when the ClickHouse schema migration is interrupted during the upgr If you're running PMM Server with less than 16 GB RAM and seeing "memory limit exceeded" errors in ClickHouse logs, switch to the low-memory configuration. -PMM includes two ClickHouse profiles: +PMM includes two built-in ClickHouse profiles: -- **default**: optimized for performance (16 GB+ RAM) +- **default**: optimized for performance on hosts with 16 GB RAM or more - **low-memory**: optimized for constrained environments, based on [ClickHouse recommendations](https://clickhouse.com/docs/operations/tips#using-less-than-16gb-of-ram) ### Switch to low-memory configuration -Select the profile with the `PMM_CLICKHOUSE_CONFIG` environment variable when you create the container: +Set the `PMM_CLICKHOUSE_CONFIG` environment variable when starting PMM Server: -```bash -docker run -e PMM_CLICKHOUSE_CONFIG=low-memory ... percona/pmm-server:3 -``` +=== "Docker" + ```bash + docker run ... -e PMM_CLICKHOUSE_CONFIG=low-memory percona/pmm-server:3 + ``` + +=== "Podman" + ```bash + podman run ... -e PMM_CLICKHOUSE_CONFIG=low-memory percona/pmm-server:3 + ``` + +The setting persists across container restarts and upgrades without any additional steps. + +To switch back to the default profile, set `PMM_CLICKHOUSE_CONFIG=default` or remove the variable. !!! note "Configuration details" Both configuration files are located in `/etc/clickhouse-server/` inside the PMM Server container: - `default-config.xml`: default profile - `low-memory-config.xml`: low-memory profile - -The `switch-config.sh` script is deprecated and will be removed in a future PMM release; use `PMM_CLICKHOUSE_CONFIG` instead. +!!! warning "Deprecated: switch-config.sh" + The `switch-config.sh` script previously used to switch profiles is deprecated as of PMM 3.9.0 and will be removed in a future release. Use `PMM_CLICKHOUSE_CONFIG` instead. \ No newline at end of file diff --git a/documentation/docs/troubleshoot/upgrade_issues.md b/documentation/docs/troubleshoot/upgrade_issues.md index 87c816804dd..0ab554edcf3 100644 --- a/documentation/docs/troubleshoot/upgrade_issues.md +++ b/documentation/docs/troubleshoot/upgrade_issues.md @@ -2,38 +2,10 @@ ## PMM Server not updating correctly -If the automatic update process isn't working, you can force an update using the API: -{.power-number} +If PMM Server is not updating correctly, check the container logs for errors: -1. Open your terminal. -2. Run the update command, replacing : with your credentials and with your PMM server address: ```sh -curl -X POST \ - --user : \ - 'http:///v1/server/updates:start' \ - -H 'Content-Type: application/json' +docker logs pmm-server ``` -3. Wait 2-5 minutes and refresh the PMM Home page to verify the update. -## Watchtower fails with "client version is too old" error - -When upgrading PMM Server via the UI, Watchtower may fail with the following error: - -``` -client version X.XX is too old. Minimum supported API version is X.XX, please upgrade your client to a newer version -``` - -This occurs when your Docker installation requires a newer API version than Watchtower supports. - -**Solution** -To resolve this issue: -{.power-number} - -1. Update to the latest Watchtower image: -``` -docker pull percona/watchtower:latest -``` -2. If the error persists, add the `DOCKER_API_VERSION` environment variable matching your Docker's minimum API version: -``` --e DOCKER_API_VERSION=1.45 -``` \ No newline at end of file +If the issue persists, restore from a backup and retry the upgrade. See [Restore PMM Server](../install-pmm/install-pmm-server/deployment-options/docker/restore_container.md). diff --git a/documentation/docs/use/commands/pmm-admin/add.md b/documentation/docs/use/commands/pmm-admin/add.md index 59277fa1041..7b1f42230c7 100644 --- a/documentation/docs/use/commands/pmm-admin/add.md +++ b/documentation/docs/use/commands/pmm-admin/add.md @@ -358,6 +358,11 @@ Control which metrics PMM collects: - `--enable-all-collectors`: Enable all collectors. By default, PMM enables only `diagnosticdata` and `replicasetstatus`. This flag also enables `collstats`, `dbstats`, `indexstats`, and `topmetrics`. +- `--enable-diagnostic-data-histograms`: Enable histogram metrics from MongoDB's `getDiagnosticData` command. Disabled by default. This option is not included in `--enable-all-collectors` and must be set explicitly. + + !!! warning + Enabling diagnostic data histograms may significantly increase `mongodb_exporter` memory usage, depending on the number of histogram buckets returned by MongoDB. The underlying exporter flag is `--collector.diagnosticdata-histograms`. + - `--disable-collectors`: Comma-separated list of collectors to exclude. - `--max-collections-limit`: Maximum number of collections to monitor. Set to `-1` to let PMM decide (default), or `0` for unlimited. A very high value can impact CPU and memory usage. diff --git a/documentation/docs/use/commands/pmm-admin/inventory.md b/documentation/docs/use/commands/pmm-admin/inventory.md index f189051c830..7b0896e68e2 100644 --- a/documentation/docs/use/commands/pmm-admin/inventory.md +++ b/documentation/docs/use/commands/pmm-admin/inventory.md @@ -144,6 +144,9 @@ You can also use `pmm-admin list` to see agents alongside their services. - `--enable-all-collectors` : Enable all collectors +- `--enable-diagnostic-data-histograms` +: Enable histogram metrics from MongoDB's `getDiagnosticData` command. Not included in `--enable-all-collectors`. Enabling this may significantly increase `mongodb_exporter` memory usage. + - `--disable-collectors` : Comma-separated list of collectors to disable diff --git a/documentation/docs/use/qan/QAN-realtime-analytics.md b/documentation/docs/use/qan/QAN-realtime-analytics.md index 5de7155f4fa..e8d008bf637 100644 --- a/documentation/docs/use/qan/QAN-realtime-analytics.md +++ b/documentation/docs/use/qan/QAN-realtime-analytics.md @@ -7,7 +7,7 @@ While [Query Analytics (QAN) Stored metrics](../qan/QAN-stored-metrics.md) captu RTA displays live query data, updated every 1-5 seconds. Data is held in memory only and refreshes with each update. -Use the **Pause** button to freeze the view for investigation. +Use the **Pause** button to freeze the view for investigation or to export a snapshot of the current data. ## Before you start @@ -52,11 +52,48 @@ Click **Pause** to freeze the current view. This lets you investigate a specific While paused, the display stops updating but the RTA agent continues collecting data in the background. Click **Resume** or use **Auto-refresh** for a one-time update while staying paused. +Pausing also makes the **Export** button available, so you can export data as a snapshot of the current operations to CSV. + +### Export RTA data + +You can export a snapshot of the current RTA view to a CSV file. This is useful for capturing query data that is still in progress and may never appear in QAN. + +For example, a long-running query that is killed before it completes will never appear in QAN, because QAN only records queries that finish. Exporting the RTA view captures its data at the moment of the snapshot, before it disappears. + +The **Export** button is hidden while auto-refresh is active and only appears once you pause. + +To export data: +{.power-number} + +1. Go to **Query Analytics > Real-time**. +2. Click **Pause** to freeze the live feed. +3. Apply any filters or sort order you want reflected in the export. +4. Click **Export** to download the file. + +The export includes all records across all pages, respects active filters and sort order, and is saved as `mongodb_rta_export_{timestamp}.csv`. + +#### Exported fields + +- `operation_id`: unique identifier for the operation +- `elapsed_exec_time_sec`: how long the operation has been running, in seconds +- `db_instance_address`: address of the MongoDB instance +- `client_address`: address of the client that sent the query +- `database_name`: database the operation is running against +- `service`: PMM service name +- `user_name`: MongoDB user who issued the query +- `collection`: collection the operation is targeting +- `operation`: type of operation (query, insert, update, command) +- `plan_summary`: query plan summary (for example, `COLLSCAN` or `IXSCAN`) +- `client_app_name`: name of the application that sent the query +- `operation_start_time`: when the database started executing this operation +- `data_capture_time`: when PMM captured this snapshot +- `raw_query`: reconstructed query text + ### Share your view Click the **Share** icon to copy a link to your clipboard. The link preserves your selected cluster or service filter. -When someone opens your link, they see live data with your filters applied—not the exact operations you were viewing, since RTA data updates continuously. +When someone opens your link, they see live data with your filters applied, not the exact operations you were viewing, since RTA data updates continuously. ### View all sessions Click **All sessions** to see and manage all running RTA sessions. From here you can stop individual sessions or stop all sessions at once: @@ -71,7 +108,7 @@ To identify operations that are taking too long: {.power-number} 1. Click the **Elapsed time** column header to sort by duration, longest first. -2. Click an operation to open the **Details** tab, then check **Plan summary** for `COLLSCAN`. This means the query scanned the entire collection—often a sign that an index is missing. +2. Click an operation to open the **Details** tab, then check **Plan summary** for `COLLSCAN`. This means the query scanned the entire collection, often a sign that an index is missing. ![RTA Details tab](../../images/RTA_Details_tab.png) diff --git a/documentation/mkdocs-base.yml b/documentation/mkdocs-base.yml index d626b0d44d8..e54700f791f 100644 --- a/documentation/mkdocs-base.yml +++ b/documentation/mkdocs-base.yml @@ -203,7 +203,9 @@ nav: - Configure monitoring: - Database monitoring: - Overview: install-pmm/install-pmm-client/connect-database/index.md - - MySQL: install-pmm/install-pmm-client/connect-database/mysql/mysql.md + - MySQL: + - Connect MySQL: install-pmm/install-pmm-client/connect-database/mysql/mysql.md + - Running custom queries: install-pmm/install-pmm-client/connect-database/mysql/custom_queries.md - MongoDB: install-pmm/install-pmm-client/connect-database/mongodb.md - PostgreSQL: install-pmm/install-pmm-client/connect-database/postgresql.md - Valkey/Redis: install-pmm/install-pmm-client/connect-database/valkey-redis.md @@ -446,7 +448,6 @@ nav: - Upgrade: - Upgrade PMM Server: - pmm-upgrade/index.md - - pmm-upgrade/ui_upgrade.md - pmm-upgrade/external_postgres_pmm_upgrade.md - Manual upgrade: - pmm-upgrade/upgrade_docker.md @@ -598,4 +599,4 @@ nav: - reference/glossary.md - reference/faq.md - reference/trademark-policy.md - - reference/copyright.md + - reference/copyright.md \ No newline at end of file diff --git a/documentation/mkdocs-pdf.yml b/documentation/mkdocs-pdf.yml index 22bdb67ca39..b6d07f9d1db 100644 --- a/documentation/mkdocs-pdf.yml +++ b/documentation/mkdocs-pdf.yml @@ -7,9 +7,9 @@ plugins: version_selector: false # https://github.com/orzih/mkdocs-with-pdf with-pdf: - output_path: "pdf/PerconaMonitoringAndManagement-3.8.0.pdf" + output_path: "pdf/PerconaMonitoringAndManagement-3.9.0.pdf" cover_title: "Percona Monitoring and Management Documentation" - cover_subtitle: 3.8.1 (June 16, 2026) + cover_subtitle: 3.9.0 (July 30, 2026) author: "Percona Technical Documentation Team" cover_logo: docs/images/Percona_Logo_Color.png custom_template_path: resources/templates diff --git a/documentation/variables.yml b/documentation/variables.yml index fb48225699b..cb960ba943e 100644 --- a/documentation/variables.yml +++ b/documentation/variables.yml @@ -1,6 +1,6 @@ # PMM Version for HTML # See also mkdocs.yml plugins.with-pdf.cover_subtitle and output_path -release: '3.8.1' -version: '3.8.1' -release_date: 2026-06-16 +release: '3.9.0' +version: '3.9.0' +release_date: 2026-07-30