[DOCS] Histograms for MongoDB exporter (PMM-15246)

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

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

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).

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?
 

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}

documentation/docs/backup/mongodb-backup/mongodb_limitations.md

@@ -1,17 +1,27 @@
-# 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:
 
 - Physical backups and restores are supported only for **Percona Server for MongoDB**.
 - 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
 

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 <i class="uil uil-history"></i> **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.<br/>
@@ -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).
 

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<br>• Easy to manage<br>• Runs without root privileges<br>• Minimal resource overhead | • Requires Docker knowledge<br>• May need additional network configuration |
 | [Podman](../install-pmm/install-pmm-server/deployment-options/podman/index.md) | Security-conscious environments | • Rootless by default<br>• Enhanced security<br>• Docker-compatible commands<br>• No daemon required | • Requires Podman installation<br>• Less common than Docker |

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
 

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/`
 

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/)

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]

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.

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 |