[DOCs] Add custom queries for MySQL (PMM-14502)

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/release-notes/3.9.0.md

@@ -49,7 +49,9 @@ For the full list of available collectors per database type, see [Connect MySQL
 
 ## 📈 Improvements
 
-([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-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-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.
 
 ## ✅ Fixed issues
 

documentation/mkdocs-base.yml

@@ -195,7 +195,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