7.0.37-20 PSMDB-2038

docs/ldap-conf-parameters.md

@@ -36,5 +36,62 @@ The cache is automatically invalidated when any of the following parameters chan
 | `ldapUserToDNCacheTTLSeconds` | No       | Changing the TTL value clears the cache.                   |
 | `ldapUserToDNCacheSize`     | No       | Changing the cache size clears the cache.                  |
 | `ldapServers`               | Yes      | Comma-separated list of LDAP servers to connect to.         |
-| `ldapQueryUser`             | No       | Distinguished Name (DN) of the user used to perform LDAP queries, when authenticated queries are required. |
+| `ldapQueryUser`             | No       | Username of the account used to connect to and query the LDAP server.|
 | `ldapQueryPassword`         | No       | Password for the query user, when authenticated queries are required. |
+
+## Monitor userToDNCache
+
+Percona Server for MongoDB exposes LDAP userToDN cache statistics in the `db.serverStatus()` output when the server is configured to use LDAP authentication with `--ldapServers`.
+
+The `ldap.userToDNCache` document reports the status and performance of the in-memory Least Recently Used (LRU) cache that maps LDAP usernames to Distinguished Names (DNs). You can use this information to verify whether the cache is enabled, monitor cache usage, and identify whether LDAP lookups are being served from cache or sent to the LDAP server.
+
+### View LDAP userToDN cache statistics
+
+Run the following command:
+
+```javascript
+db.serverStatus().ldap.userToDNCache
+```
+
+??? example "Output"
+    ```{.json .no-copy}
+    {
+      "enabled": true,
+      "maxSize": 10000,
+      "currentSize": 42,
+      "ttlSeconds": 30,
+      "hits": 1847,
+      "misses": 63,
+      "invalidations": 2
+    }
+    ```
+
+The following table describes the fields returned in the `ldap.userToDNCache` document.
+
+| **Field** | **Description** |
+|-------|-------------|
+| `enabled` | Indicates whether the LDAP user-to-DN cache is active.<br><br>The cache is disabled when either `ldapUserToDNCacheTTLSeconds` or `ldapUserToDNCacheSize` is set to `0`.<br><br>When disabled, all user-to-DN lookups are sent directly to the LDAP server. |
+| `maxSize` | The maximum number of `username-to-DN mappings` that can be stored in the cache.<br><br>Corresponds to the `ldapUserToDNCacheSize` server parameter.<br><br>When the cache reaches this limit, the least recently used entry is evicted.|
+| `currentSize` | The current number of `username-to-DN` mappings stored in the cache. |
+| `ttlSeconds` | The time-to-live (TTL) for cache entries, in seconds.<br><br>Corresponds to the `ldapUserToDNCacheTTLSeconds` server parameter.<br><br>Entries older than this value are treated as expired and are not served from the cache. |
+| `hits` | The number of `mapUserToDN` lookups served from the cache since the last cache invalidation.|
+| `misses` | The number of `mapUserToDN` lookups not served from the cache since the last cache invalidation.<br><br>A miss occurs when an entry is missing or has expired.|
+| `invalidations` | The total number of cache invalidations since server startup.<br><br>Unlike `hits` and `misses`, this counter does not reset. |
+
+!!! note
+    The `hits` and `misses` counters reset to `0` on each cache invalidation. `invalidations` never resets.
+
+### Calculate the cache hit rate
+
+You can calculate the hit rate for the current cache generation using the following command:
+
+```javascript
+var c = db.serverStatus().ldap.userToDNCache;
+var total = c.hits + c.misses;
+var hitRate = total > 0 ? c.hits / total : null;
+```
+
+A higher hit rate means more LDAP `userToDN` lookups are served from cache, reducing requests to the LDAP server.
+
+!!! note
+    If `hits` and `misses` drop sharply and `invalidations` increases, an LDAP-related runtime parameter was likely changed. This does not necessarily indicate degraded cache performance.