RS: Explained replication_oom_threshold_percent in A-A memory limits docs

content/operate/rs/databases/active-active/planning.md

@@ -48,6 +48,33 @@ It's also important to know Active-Active databases have a lower threshold for a
 
 For more information on memory limits, see [Memory and performance]({{< relref "/operate/rs/databases/memory-performance/" >}}) or [Database memory limits]({{< relref "/operate/rs/databases/memory-performance/memory-limit.md" >}}).
 
+### Replication OOM protection
+
+When a shard in an Active-Active database reaches an out-of-memory (OOM) condition:
+
+1. Replication between that shard and its peers stops immediately.
+
+1. The syncer process sends commands to the affected shard to trigger garbage collection and free memory.
+
+If the database has no [eviction policy]({{<relref "/operate/rs/databases/memory-performance/eviction-policy/">}}) and no keys with [expiration times (TTL)]({{<relref "/develop/using-commands/keyspace#key-expiration">}}), no memory can be freed, which can lead to persistent replication failure and data desynchronization.
+
+To reduce this risk, Active-Active databases running Redis version 8.4 or later support a configurable memory buffer through the `replication_oom_threshold_percent` setting. This setting reserves a percentage of memory below `maxmemory` for internal replication operations.
+
+The `replication_oom_threshold_percent` setting works as follows:
+
+- If memory usage is below the threshold, all client writes proceed normally.
+
+- If memory usage exceeds the threshold, Redis blocks external client write commands with an out-of-memory error, but internal replication and garbage collection continue in the reserved buffer.
+
+- If memory reaches `maxmemory` despite the client block, the standard out-of-memory behavior applies to all operations, including replication.
+
+`replication_oom_threshold_percent` defaults to `5`, which means 5% of `maxmemory` is reserved. To adjust the reserved percentage, use an [update database configuration]({{<relref "operate/rs/references/rest-api/requests/bdbs#put-bdbs">}}) REST API request:
+
+```sh
+PUT https://<host>:<port>/v1/bdbs/<database_id>
+{ "replication_oom_threshold_percent": <integer from 0 to 20> }
+```
+
 ## Networking
 
 Network requirements for Active-Active databases include:

content/operate/rs/databases/memory-performance/memory-limit.md

@@ -67,6 +67,33 @@ but tries to avoid stopping primary shards.
 We recommend that you have a [monitoring platform]({{< relref "/operate/rs/monitoring/" >}}) that alerts you before a system gets low on RAM.
 You must maintain sufficient free memory to make sure that you have a healthy Redis Software installation.
 
+### Active-Active replication OOM protection
+
+When a shard in an Active-Active database reaches an out-of-memory (OOM) condition:
+
+1. Replication between that shard and its peers stops immediately.
+
+1. The syncer process sends commands to the affected shard to trigger garbage collection and free memory.
+
+If the database has no [eviction policy]({{<relref "/operate/rs/databases/memory-performance/eviction-policy/">}}) and no keys with [expiration times (TTL)]({{<relref "/develop/using-commands/keyspace#key-expiration">}}), no memory can be freed, which can lead to persistent replication failure and data desynchronization.
+
+To reduce this risk, Active-Active databases running Redis version 8.4 or later support a configurable memory buffer through the `replication_oom_threshold_percent` setting. This setting reserves a percentage of memory below `maxmemory` for internal replication operations.
+
+The `replication_oom_threshold_percent` setting works as follows:
+
+- If memory usage is below the threshold, all client writes proceed normally.
+
+- If memory usage exceeds the threshold, Redis blocks external client write commands with an out-of-memory error, but internal replication and garbage collection continue in the reserved buffer.
+
+- If memory reaches `maxmemory` despite the client block, the standard out-of-memory behavior applies to all operations, including replication.
+
+`replication_oom_threshold_percent` defaults to `5`, which means 5% of `maxmemory` is reserved. To adjust the reserved percentage, use an [update database configuration]({{<relref "operate/rs/references/rest-api/requests/bdbs#put-bdbs">}}) REST API request:
+
+```sh
+PUT https://<host>:<port>/v1/bdbs/<database_id>
+{ "replication_oom_threshold_percent": <integer from 0 to 20> }
+```
+
 ## Adaptive memory allocation
 
 In rare cases during high-velocity data ingestion, databases can temporarily reach up to 200% of their configured memory limit. This adaptive memory allocation strategy allows large amounts of data to be written to the database quickly without rejecting valid transactions.