WT-2734 Improve documentation of eviction configuration settings. (#2937)

1 files changed, 32 insertions, 18 deletions

diff --git a/src/docs/tune-cache.dox b/src/docs/tune-cache.dox
index 505da436277..fc42fc80046 100644
--- a/src/docs/tune-cache.dox
+++ b/src/docs/tune-cache.dox
@@ -60,24 +60,38 @@ WiredTiger eviction tuning options can be configured when first opening
 a database via ::wiredtiger_open, or changed after open with
 WT_CONNECTION::reconfigure.
 
-The \c eviction_trigger configuration value is the occupied percentage
-of the total cache size that causes eviction to start.  By default,
-WiredTiger begins evicting pages when the cache is 95% full. An
-application concerned about a latency spike as the cache becomes full
-might want to begin eviction earlier.
-
-The \c eviction_target configuration value is the overall target for
-eviction, expressed as a percentage of total cache size; that is, once
-eviction begins, it will proceed until the target percentage of bytes
-in the cache is reached.  Note the \c eviction_target configuration
-value is ignored until eviction is triggered.
-
-The \c eviction_dirty_target configuration value is the overall dirty
-byte target for eviction, expressed as a percentage of total cache size;
-that is, once eviction begins, it will proceed until the target
-percentage of dirty bytes in the cache is reached.  Note the
-\c eviction_dirty_target configuration value is ignored until eviction
-is triggered.
+The \c eviction_target configuration value (default 80%) is the level at
+which WiredTiger attempts to keep the overall cache usage.  Eviction worker
+threads are active when the cache contains at least this much content,
+expressed as a percentage of the total cache size.
+
+The \c eviction_trigger configuration value (default 95%) is the level at
+which application threads start to perform eviction.  This will throttle
+application operations, increasing operation latency, usually resulting in
+the cache usage staying at this level when there is more cache pressure
+than eviction worker threads can handle in the background.
+
+Operations will stall when the cache reaches 100% of the cache size.
+Application may want to change these settings from their defaults to either
+increase the range in which worker threads operate before application
+threads are throttled, or to use a larger proportion of RAM, if eviction
+worker threads have no difficulty handling the cache pressure generated by
+the application.
+
+The \c eviction_dirty_target (default 5%) and \c eviction_dirty_trigger
+(default 20%) operate in a similar way to the overall targets, but only
+apply to dirty data in cache.  In particular, application threads will be
+throttled if the percentage of dirty data reaches the
+\c eviction_dirty_trigger. Any page that has been modified since it was
+read from disk is considered dirty.
+
+The dirty eviction  settings control how much work checkpoints have to do
+in the worst case, and also limit how much memory fragmentation is likely
+for memory allocations related to the cache.  Most memory fragmentation is
+caused by workloads that generate a mix of updates (small allocations) with
+cache misses (large allocations).  Limiting the percentage of cache that
+can be dirty limits the worst case fragmentation to the approximately the
+same level.
 
 @snippet ex_all.c Eviction configuration