Defrag: document the feature in redis.conf.

1 files changed, 49 insertions, 6 deletions

diff --git a/redis.conf b/redis.conf
index 18ba9fb3f..c54dba392 100644
--- a/redis.conf
+++ b/redis.conf
@@ -1230,21 +1230,64 @@ aof-rewrite-incremental-fsync yes
 # lfu-decay-time 1
 
 ########################### ACTIVE DEFRAGMENTATION #######################
+#
+# WARNING THIS FEATURE IS EXPERIMENTAL. However it was stress tested
+# even in production and manually tested by multiple engineers for some
+# time.
+#
+# What is active defragmentation?
+# -------------------------------
+#
+# Active (online) defragmentation allows a Redis server to compact the
+# spaces left between small allocations and deallocations of data in memory,
+# thus allowing to reclaim back memory.
+#
+# Fragmentation is a natural process that happens with every allocator (but
+# less so with Jemalloc, fortunately) and certain workloads. Normally a server
+# restart is needed in order to lower the fragmentation, or at least to flush
+# away all the data and create it again. However thanks to this feature
+# implemented by Oran Agra for Redis 4.0 this process can happen at runtime
+# in an "hot" way, while the server is running.
+#
+# Basically when the fragmentation is over a certain level (see the
+# configuration options below) Redis will start to create new copies of the
+# values in contiguous memory regions by exploiting certain specific Jemalloc
+# features (in order to understand if an allocation is causing fragmentation
+# and to allocate it in a better place), and at the same time, will release the
+# old copies of the data. This process, repeated incrementally for all the keys
+# will cause the fragmentation to drop back to normal values.
+#
+# Important things to understand:
+#
+# 1. This feature is disabled by default, and only works if you compiled Redis
+#    to use the copy of Jemalloc we ship with the source code of Redis.
+#    This is the default with Linux builds.
+#
+# 2. You never need to enable this feature if you don't have fragmentation
+#    issues.
+#
+# 3. Once you experience fragmentation, you can enable this feature when
+#    needed with the command "CONFIG SET activedefrag yes".
+#
+# The configuration parameters are able to fine tune the behavior of the
+# defragmentation process. If you are not sure about what they mean it is
+# a good idea to leave the defaults untouched.
 
-# enabled active defragmentation
+# Enabled active defragmentation
 # activedefrag yes
 
-# minimum amount of fragmentation waste to start active defrag
+# Minimum amount of fragmentation waste to start active defrag
 # active-defrag-ignore-bytes 100mb
 
-# minimum percentage of fragmentation to start active defrag
+# Minimum percentage of fragmentation to start active defrag
 # active-defrag-threshold-lower 10
 
-# maximum percentage of fragmentation at which we use maximum effort
+# Maximum percentage of fragmentation at which we use maximum effort
 # active-defrag-threshold-upper 100
 
-# minimal effort for defrag in CPU percentage
+# Minimal effort for defrag in CPU percentage
 # active-defrag-cycle-min 25
 
-# maximal effort for defrag in CPU percentage
+# Maximal effort for defrag in CPU percentage
 # active-defrag-cycle-max 75
+