Merge pull request #16971 from clintongormley/merge-settings-docs

Redocument the `index.merge.scheduler.max_thread_count` setting

docs/reference/index-modules.asciidoc

@@ -148,6 +148,10 @@ Other index settings are available in index modules:
 
     Enable or disable dynamic mapping for an index.
 
+<<index-modules-merge,Merging>>::
+
+    Control over how shards are merged by the background merge process.
+
 <<index-modules-similarity,Similarities>>::
 
     Configure custom similarity settings to customize how search results are
@@ -173,6 +177,8 @@ include::index-modules/allocation.asciidoc[]
 
 include::index-modules/mapper.asciidoc[]
 
+include::index-modules/merge.asciidoc[]
+
 include::index-modules/similarity.asciidoc[]
 
 include::index-modules/slowlog.asciidoc[]

docs/reference/index-modules/merge.asciidoc

@@ -0,0 +1,30 @@
+[[index-modules-merge]]
+== Merge
+
+A shard in elasticsearch is a Lucene index, and a Lucene index is broken down
+into segments. Segments are internal storage elements in the index where the
+index data is stored, and are immutable. Smaller segments are periodically
+merged into larger segments to keep the index size at bay and to expunge
+deletes.
+
+The merge process uses auto-throttling to balance the use of hardware
+resources between merging and other activities like search.
+
+[float]
+[[merge-scheduling]]
+=== Merge scheduling
+
+The merge scheduler (ConcurrentMergeScheduler) controls the execution of merge
+operations when they are needed.  Merges run in separate threads, and when the
+maximum number of threads is reached, further merges will wait until a merge
+thread becomes available.
+
+The merge scheduler supports the following _dynamic_ setting:
+
+`index.merge.scheduler.max_thread_count`::
+
+    The maximum number of threads that may be merging at once. Defaults to
+    `Math.max(1, Math.min(4, Runtime.getRuntime().availableProcessors() / 2))`
+    which works well for a good solid-state-disk (SSD).  If your index is on
+    spinning platter drives instead, decrease this to 1.
+