[DOC] PMM Mysql AHI Efficiency advisor check

documentation/docs/advisors/checks/mysql-ahi-efficiency-performance-basic-check.md

@@ -0,0 +1,50 @@
+# InnoDB Adaptive Hash Index (AHI) efficiency check
+
+## Description
+
+MySQL's InnoDB engine can automatically build a hash index in memory on frequently accessed data, this is called the Adaptive Hash Index (AHI). When it works well, the AHI lets MySQL answer queries with a fast hash lookup instead of traversing the full B-tree index, which means lower CPU usage and faster queries.
+
+This check looks at two things:
+
+- **how often the AHI is actually helping** (hit ratio): if most lookups still fall back to the B-tree, the AHI isn't doing much.
+- **whether the AHI is causing contention** (latch wait load): under heavy concurrent workloads, multiple threads competing for the AHI's internal lock can slow things down more than the AHI speeds them up.
+
+You'll see different alert levels depending on what's found:
+
+- **Notice**: AHI is working normally, or it's disabled.
+- **Warning**: contention is building up and starting to affect performance.
+- **Error**: contention is high enough that the AHI is likely hurting more than helping. Increase AHI partitions or disable AHI altogether.
+
+## Resolution
+
+### If you're seeing Warning or Error alerts
+
+Increase the number of AHI partitions. This splits the internal lock across more structures, reducing contention:
+
+```sql
+SET GLOBAL innodb_adaptive_hash_index_parts = 16;
+```
+
+To make it permanent, add it to your MySQL configuration file and restart:
+
+```ini
+[mysqld]
+innodb_adaptive_hash_index_parts = 16
+```
+
+If contention is still high after increasing partitions, disabling the AHI entirely is worth testing:
+
+```sql
+SET GLOBAL innodb_adaptive_hash_index = OFF;
+```
+
+Benchmark your workload with it off to see if performance improves.
+
+### If the AHI is disabled
+
+Consider turning it on and watching the **InnoDB Adaptive Hash Index** panel on the [MySQL InnoDB Details](../../reference/dashboards/dashboard-mysql-innodb-details.md) dashboard. The AHI is most useful for read-heavy workloads that repeatedly access the same index data.
+
+## Need more support from Percona?
+
+Percona experts bring years of experience in tackling tough database performance issues and design challenges.
+

documentation/mkdocs-base.yml

@@ -343,6 +343,7 @@ nav:
               - Performance advisors:
                   - Generic performance checks:
                       - advisors/checks/multiple-mongod-running-in-a-node.md
+                      - advisors/checks/mysql-ahi-efficiency-performance-basic-check.md
                       - advisors/checks/performance-pg-low-cache-hit-ratio.md
                       - advisors/checks/configuration-pg-settings-changed.md
                       - advisors/checks/postgresql-tmpfiles-check.md

managed/data/checks/mysql_ahi_efficiency_performance_basic_check.yml

@@ -120,7 +120,7 @@ checks:
                    else:  # loadAvg > thresholdB
                        summary = "AHI is likely experiencing contention"
                        description = "{}. You should consider increasing the number of AHI partitions (currently operating with {}) or disable it altogether.".format(btrWaitLoadHitRatioMsg,ahi_parts)
-                       severity = "major"
+                       severity = "error"
 
                else:
                    summary = "AHI is operating with no contention detected"