From d2e8e10233b4e2d25a10b12cbc9e916bc52300f1 Mon Sep 17 00:00:00 2001
From: Andrzej Bialecki <ab@apache.org>
Date: Wed, 7 Feb 2018 14:43:50 -0800
Subject: [PATCH] Add documentation for searchRate trigger.

---
 .../src/solrcloud-autoscaling-triggers.adoc   | 51 +++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/solr/solr-ref-guide/src/solrcloud-autoscaling-triggers.adoc b/solr/solr-ref-guide/src/solrcloud-autoscaling-triggers.adoc
index 5a986576e4a..a7a8d520c9f 100644
--- a/solr/solr-ref-guide/src/solrcloud-autoscaling-triggers.adoc
+++ b/solr/solr-ref-guide/src/solrcloud-autoscaling-triggers.adoc
@@ -35,6 +35,7 @@ Currently the following event types (and corresponding trigger implementations)
 * `nodeAdded` - generated when a new node joins the cluster
 * `nodeLost` - generated when a node leaves the cluster
 * `metric` - generated when the configured metric crosses a configured lower or upper threshold value
+* `searchRate` - generated when the 1 min average search rate exceeds configured upper threshold
 
 Events are not necessarily generated immediately after the corresponding state change occurred - the
 maximum rate of events is controlled by the `waitFor` configuration parameter (see below).
@@ -87,6 +88,56 @@ This trigger supports the following configuration:
 }
 ----
 
+== Search Rate trigger
+
+The search rate trigger can be used for monitoring 1-min average search rates in a selected
+collection, and request that either replicas be moved to different nodes or new replicas be added
+to reduce the per-replica search rate for a collection / shard with search rate hot spots.
+(Note: future versions of Solr will also be able to automatically remove some replicas
+when search rate falls below the configured lower threshold).
+
+This trigger support the following configuration:
+
+* `collection` - (string, optional) collection name to monitor, or any collection if empty
+* `shard` - (string, optional) shard name within the collection (requires `collection` to be set), or any shard if empty
+* `node` - (string, optional) node name to monitor, or any if empty
+* `handler` - (string, optional) handler name whose request rate represents the search rate
+(default is `/select`). This name is used for creating the full metric key, in
+this case `solr.core.<coreName>:QUERY./select.requestTimes:1minRate`
+* `rate` - (double, required) the upper bound for the request rate metric value.
+
+If a rate is exceeded for a node (but not for individual replicas placed on this node) then
+the action requested by this event is to move one replica (with the highest rate) to another
+node. If a rate is exceeded for a collection / shard then the action requested is to add some
+replicas - currently at least 1 and at most 3, depending on how much the rate is exceeded, proportional to
+the threshold rate and the current request rate.
+
+.Example: a trigger configuration that monitors collection "test" and adds new replicas if 1-min average request rate of "/select" handler exceeds 100 reqs/sec:
+[source,json]
+----
+{
+ "set-trigger": {
+  "name" : "search_rate_trigger",
+  "event" : "searchRate",
+  "collection" : "test",
+  "handler" : "/select",
+  "rate" : 100.0,
+  "waitFor" : "1m",
+  "enabled" : true,
+  "actions" : [
+   {
+    "name" : "compute_plan",
+    "class": "solr.ComputePlanAction"
+   },
+   {
+    "name" : "execute_plan",
+    "class": "solr.ExecutePlanAction"
+   }
+  ]
+ }
+}
+----
+
 == Trigger Configuration
 Trigger configurations are managed using the Autoscaling Write API and the commands `set-trigger`, `remove-trigger`,
 `suspend-trigger`, and `resume-trigger`.