From 88e37a49f65c550819f6e0b042a4c806e7877787 Mon Sep 17 00:00:00 2001 From: Rachel Elledge Date: Mon, 18 May 2026 16:24:11 -0500 Subject: [PATCH] DOC-6527 RS: Explained replication_oom_threshold_percent in A-A memory limits docs --- .../rs/databases/active-active/planning.md | 27 +++++++++++++++++++ .../memory-performance/memory-limit.md | 27 +++++++++++++++++++ 2 files changed, 54 insertions(+) diff --git a/content/operate/rs/databases/active-active/planning.md b/content/operate/rs/databases/active-active/planning.md index f4e90118c8..d2815fd92b 100644 --- a/content/operate/rs/databases/active-active/planning.md +++ b/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]({{}}) and no keys with [expiration times (TTL)]({{}}), 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]({{}}) REST API request: + +```sh +PUT https://:/v1/bdbs/ +{ "replication_oom_threshold_percent": } +``` + ## Networking Network requirements for Active-Active databases include: diff --git a/content/operate/rs/databases/memory-performance/memory-limit.md b/content/operate/rs/databases/memory-performance/memory-limit.md index 603824d048..c05489d9c1 100644 --- a/content/operate/rs/databases/memory-performance/memory-limit.md +++ b/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]({{}}) and no keys with [expiration times (TTL)]({{}}), 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]({{}}) REST API request: + +```sh +PUT https://:/v1/bdbs/ +{ "replication_oom_threshold_percent": } +``` + ## 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.