improve performance docs

Author: tillkruss

docs/1.x/configuration.md

@@ -35,11 +35,11 @@ To disable all in-memory caching and memory allocation `relay.maxmemory` can be
 | `relay.eviction_policy`           | `noeviction`     | How should relay evict keys. This has been designed to mirror Redis’ options. Supported values: `noeviction`, `lru`, and `random` |
 | `relay.eviction_sample_keys`      | `128`            | How many keys should we scan each time we process evictions. |
 | `relay.databases`                 | `16`             | The number of databases Relay will create per in-memory cache. This setting should match the `databases` setting in your `redis.conf`. |
-| `relay.max_endpoint_dbs`          | `32`             | The maximum number of PHP workers that will have their own in-memory cache. This setting is per connection endpoint (distinct Redis connections). See [Performance](/docs/1.x/performance) section. |
-| `relay.max_db_writers`            | `4`              | The maximum number of writers for a given cache. Writers are PHP workers with a persistent connection to Redis that can write to the cache and manage their own invalidations. Any number of workers can read from any cache. |
-| `relay.cap_endpoint_dbs`          | `On`             | Whether Relay should cap `max_endpoint_dbs` to the number of detected CPU cores. |
-| `relay.locks.allocator`           | `adaptive-mutex` | Locking mechanism used for the allocator. Supported values: `spinlock`, `mutex`, `adaptive-mutex` |
-| `relay.locks.cache`               | `adaptive-mutex` | Locking mechanism used for the in-memory cache (databases). Supported values: `spinlock`, `mutex`, `adaptive-mutex` |
+| `relay.max_endpoint_dbs`          | `32`             | The maximum number of PHP workers that will have their own in-memory cache. This setting is per connection endpoint (distinct Redis connections), e.g. connecting to two separate instances will double the workers. See [Performance](/docs/1.x/performance). |
+| `relay.max_db_writers`            | `4`              | The maximum number of writers for a given cache. Writers are PHP workers with a persistent connection to Redis that can write to the cache and manage their own invalidations. Any number of workers can read from any cache. See [Performance](/docs/1.x/performance). |
+| `relay.cap_endpoint_dbs`          | `On`             | Whether Relay should cap `max_endpoint_dbs` to the number of detected CPU cores. See [Performance](/docs/1.x/performance). |
+| `relay.locks.allocator`           | `adaptive-mutex` | Locking mechanism used for the allocator. Supported values: `spinlock`, `mutex`, `adaptive-mutex`. See [Performance](/docs/1.x/performance). |
+| `relay.locks.cache`               | `adaptive-mutex` | Locking mechanism used for the in-memory cache (databases). Supported values: `spinlock`, `mutex`, `adaptive-mutex`. See [Performance](/docs/1.x/performance). |
 | `relay.default_pconnect`          | `1`              | Default to using a persistent connection when calling `connect()`. |
 | `relay.initial_readers`           | `128`            | The number of epoch readers allocated on startup. |
 | `relay.invalidation_poll_freq`    | `5`              | How often (in microseconds) Relay should proactively check the connection for invalidation messages from Redis/Valkey. |

docs/1.x/performance.md

@@ -6,6 +6,24 @@ title: Performance
 
 For Relay to perform at its peak, some configuration directives might need to be adjusted to match your system.
 
+## `relay.max_endpoint_dbs`
+
+This directive determines the maximum number of PHP workers that will have their own in-memory cache. Not all workers need their own cache — workers without one become read-only workers that read from the shared memory pool. Giving too many workers an in-memory cache can negatively impact performance.
+
+The default of `32` should be tuned to the number of CPU cores or maximum workers, whichever is lower:
+
+```
+max_endpoint_dbs = min(vCPUs, pm.max_children)
+```
+
+This setting is per connection endpoint (distinct Redis connections), meaning connecting to two separate Redis instances will double the number of workers that have their own cache. See also [`relay.cap_endpoint_dbs`](#relaycap_endpoint_dbs).
+
+## `relay.max_db_writers`
+
+This directive determines the maximum number of writers for a given cache. Writers are PHP workers with a persistent connection to Redis that can write to the cache and manage their own invalidations. Any number of workers can read from any cache.
+
+The default of `4` is a good starting point for most setups. This value should not be larger than the number of cores on the machine.
+
 ## `relay.locks.*`
 
 The default locking mechanism used for the in-memory cache and allocator is `adaptive-mutex` with a fallback to `mutex` if glibc is not available on the system. 
@@ -14,14 +32,8 @@ The default locking mechanism used for the in-memory cache and allocator is `ada
 - `mutex`: When contention is detected, this lock will sleep until it is available. It has higher latency than a spinlock but uses far less CPU. On machines with many cores it is likely the right choice.
 - `adaptive-mutex`: This lock is a hybrid of the two above. When contention is detected it will first spin waiting for the lock to free and then sleep if the lock is still not available. Each time it spins it will update its strategy depending on how long it took. Requires glibc and will fallback to `mutex` if glibc is not available.
 
-## `relay.max_endpoint_dbs`
-
-This directive determines the maximum number of PHP workers with their own in-memory cache. While each PHP worker will have its own connection to Redis, not all workers need their own in-memory cache, and can be read-only workers that read from the shared memory pool. Giving too many workers an in-memory cache can negatively impact performance.
-
-The default of `32` should be adjusted to the number of cores or maximum workers, whichever is lower.
+## `relay.cap_endpoint_dbs`
 
-```
-max_endpoint_dbs = min(cores, pm.max_children)
-```
+When enabled (the default), Relay will cap `max_endpoint_dbs` to the number of detected CPU cores. This is a sensible safeguard that prevents over-allocation on systems where `pm.max_children` exceeds the core count.
 
-By default `cap_endpoint_dbs` is enabled which will cap `max_endpoint_dbs` to the number of detected CPU cores. When using `spinlock` on a machine with few cores a lower number like `4` will likely perform well.
+When using `spinlock` on a machine with few cores, a lower `max_endpoint_dbs` value like `4` will likely perform well.