[DOCS] Reformat index recovery API docs (#46493)

Author: jrodewig

docs/reference/cat/recovery.asciidoc

@@ -4,8 +4,9 @@
 <titleabbrev>cat recovery</titleabbrev>
 ++++
 
-Returns information about ongoing and completed index shard recoveries, similar
-to the <<indices-recovery, index recovery>> API.
+
+Returns information about ongoing and completed shard recoveries,
+similar to the <<indices-recovery, index recovery>> API.
 
 
 [[cat-recovery-api-request]]
@@ -19,15 +20,11 @@ to the <<indices-recovery, index recovery>> API.
 [[cat-recovery-api-desc]]
 ==== {api-description-title}
 
-The cat recovery API returns information about index shard recoveries, both
+The cat recovery API returns information about shard recoveries, both
 ongoing and completed. It is a more compact view of the JSON
 <<indices-recovery,index recovery>> API.
 
-A recovery event occurs anytime an index shard moves to a different node in the
-cluster. This can happen during a snapshot recovery, a change in replication
-level, node failure, or on node startup. This last type is called a local store
-recovery and is the normal way for shards to be loaded from disk when a node
-starts up.
+include::{docdir}/indices/recovery.asciidoc[tag=shard-recovery-desc]
 
 
 [[cat-recovery-path-params]]

docs/reference/glossary.asciidoc

@@ -209,14 +209,22 @@ see {ref}/query-filter-context.html[Query and filter context].
 +
 --
 // tag::recovery-def[]
-The process of syncing a shard copy from a source shard. Upon completion, the recovery process makes the shard copy available for queries.
-
-Recovery automatically occurs anytime a shard moves to a different node in the same cluster, including:
-
-* Node startup
-* Node failure
-* Index shard replication
-* Snapshot restoration
+Shard recovery is the process
+of syncing a <<glossary-replica-shard,replica shard>>
+from a <<glossary-primary-shard,primary shard>>.
+Upon completion,
+the replica shard is available for search.
+
+// tag::recovery-triggers[]
+Recovery automatically occurs
+during the following processes:
+
+* Node startup or failure.
+  This type of recovery is called a *local store recovery*.
+* <<glossary-replica-shard,Primary shard replication>>.
+* Relocation of a shard to a different node in the same cluster.
+* {ref}/modules-snapshots.html#restore-snapshot[Snapshot restoration].
+// end::recovery-triggers[]
 // end::recovery-def[]
 --
 

docs/reference/indices/recovery.asciidoc

@@ -4,21 +4,180 @@
 <titleabbrev>Index recovery</titleabbrev>
 ++++
 
-The index recovery API provides insight into on-going index shard recoveries.
-Recovery status may be reported for specific indices, or cluster-wide.
 
-For example, the following command would show recovery information for the indices "index1" and "index2".
+Returns information about ongoing and completed shard recoveries.
+
+[source,console]
+----
+GET /twitter/_recovery
+----
+// TEST[setup:twitter]
+
+
+[[index-recovery-api-request]]
+==== {api-request-title}
+
+`GET /<index>/_recovery`
+
+`GET /_recovery`
+
+
+[[index-recovery-api-desc]]
+==== {api-description-title}
+
+Use the index recovery API
+to get information about ongoing and completed shard recoveries.
+
+// tag::shard-recovery-desc[]
+Shard recovery is the process
+of syncing a replica shard from a primary shard.
+Upon completion,
+the replica shard is available for search.
+
+include::{docdir}/glossary.asciidoc[tag=recovery-triggers]
+
+// end::shard-recovery-desc[]
+
+[[index-recovery-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
++
+Use a value of `_all` to retrieve information for all indices in the cluster.
+
+
+[[index-recovery-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=active-only]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=detailed]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-query-parm]
+
+
+[[index-recovery-api-response-body]]
+==== {api-response-body-title}
+
+`id`::
+(Integer)
+ID of the shard.
+
+`type`::
++
+--
+(String)
+Recovery type.
+Returned values include:
+
+`STORE`::
+The recovery is related to
+a node startup or failure.
+This type of recovery is called a local store recovery.
+
+`SNAPSHOT`::
+The recovery is related to
+a <<restore-snapshot,snapshot restoration>>.
+
+`REPLICA`::
+The recovery is related to
+a <<glossary-replica-shard,primary shard replication>>.
+
+`RELOCATING`::
+The recovery is related to
+the relocation of a shard
+to a different node in the same cluster.
+--
+
+`STAGE`::
++
+--
+(String)
+Recovery stage.
+Returned values include:
+
+`DONE`::
+Complete.
+
+`FINALIZE`::
+Cleanup.
+
+`INDEX`::
+Reading index metadata and copying bytes from source to destination.
+
+`INIT`::
+Recovery has not started.
+
+`START`::
+Starting the recovery process; opening the index for use.
+
+`TRANSLOG`::
+Replaying transaction log .
+--
+
+`primary`::
+(Boolean)
+If `true`,
+the shard is a primary shard.
+
+`start_time`::
+(String)
+Timestamp of recovery start.
+
+`stop_time`::
+(String)
+Timestamp of recovery finish.
+
+`total_time_in_millis`::
+(String)
+Total time to recover shard in milliseconds.
+
+`source`::
++
+--
+(Object)
+Recovery source.
+This can include:
+
+  * A repository description if recovery is from a snapshot
+  * A description of source node
+--
+
+`target`::
+(Object)
+Destination node.
+
+`index`::
+(Object)
+Statistics about physical index recovery.
+
+`translog`::
+(Object)
+Statistics about translog recovery.
+
+`start`::
+(Object)
+Statistics about time to open and start the index.
+
+
+[[index-recovery-api-example]]
+==== {api-examples-title}
+
+
+[[index-recovery-api-multi-ex]]
+===== Get recovery information for several indices
 
 [source,console]
 --------------------------------------------------
 GET index1,index2/_recovery?human
 --------------------------------------------------
 // TEST[s/^/PUT index1\nPUT index2\n/]
 
-To see cluster-wide recovery status simply leave out the index names.
 
-//////////////////////////
+[[index-recovery-api-all-ex]]
+===== Get segment information for all indices
 
+//////////////////////////
 Here we create a repository and snapshot index1 in
 order to restore it right after and prints out the
 index recovery result.
@@ -61,7 +220,6 @@ POST /_snapshot/my_repository/snap_1/_restore?wait_for_completion=true
   }
 }
 --------------------------------------------------
-
 //////////////////////////
 
 [source,console]
@@ -70,7 +228,7 @@ GET /_recovery?human
 --------------------------------------------------
 // TEST[continued]
 
-Response:
+The API returns the following response:
 
 [source,console-result]
 --------------------------------------------------
@@ -149,20 +307,28 @@ The TESTRESPONSE above replace all the fields values by the expected ones in the
 because we don't really care about the field values but we want to check the fields names.
 ////
 
-The above response shows a single index recovering a single shard. In this case, the source of the recovery is a snapshot repository
-and the target of the recovery is the node with name "my_es_node".
+This response includes information
+about a single index recovering a single shard.
+The source of the recovery is a snapshot repository
+and the target of the recovery is the `my_es_node` node.
+
+The response also includes the number
+and percentage of files and bytes recovered.
 
-Additionally, the output shows the number and percent of files recovered, as well as the number and percent of bytes recovered.
 
-In some cases a higher level of detail may be preferable. Setting "detailed=true" will present a list of physical files in recovery.
+[[index-recovery-api-detailed-ex]]
+===== Get detailed recovery information
+
+To get a list of physical files in recovery,
+set the `detailed` query parameter to `true`.
 
 [source,console]
 --------------------------------------------------
 GET _recovery?human&detailed=true
 --------------------------------------------------
 // TEST[s/^/PUT index1\n{"settings": {"index.number_of_shards": 1}}\n/]
 
-Response:
+The API returns the following response:
 
 [source,console-result]
 --------------------------------------------------
@@ -258,43 +424,22 @@ because we don't really care about the field values but we want to check the fie
 It also removes the "details" part which is important in this doc but really hard to test.
 ////
 
-This response shows a detailed listing (truncated for brevity) of the actual files recovered and their sizes.
-
-Also shown are the timings in milliseconds of the various stages of recovery: index retrieval, translog replay, and index start time.
-
-Note that the above listing indicates that the recovery is in stage "done". All recoveries, whether on-going or complete, are kept in
-cluster state and may be reported on at any time. Setting "active_only=true" will cause only on-going recoveries to be reported.
-
-Here is a complete list of options:
-
-[horizontal]
-`detailed`::        Display a detailed view. This is primarily useful for viewing the recovery of physical index files. Default: false.
-`active_only`::     Display only those recoveries that are currently on-going. Default: false.
-
-Description of output fields:
-
-[horizontal]
-`id`::              Shard ID
-`type`::            Recovery type:
-                        * store
-                        * snapshot
-                        * replica
-                        * relocating
-`stage`::           Recovery stage:
-                        * init:     Recovery has not started
-                        * index:    Reading index meta-data and copying bytes from source to destination
-                        * start:    Starting the engine; opening the index for use
-                        * translog: Replaying transaction log
-                        * finalize: Cleanup
-                        * done:     Complete
-`primary`::         True if shard is primary, false otherwise
-`start_time`::      Timestamp of recovery start
-`stop_time`::       Timestamp of recovery finish
-`total_time_in_millis`::    Total time to recover shard in milliseconds
-`source`::          Recovery source:
-                        * repository description if recovery is from a snapshot
-                        * description of source node otherwise
-`target`::          Destination node
-`index`::           Statistics about physical index recovery
-`translog`::        Statistics about translog recovery
-`start`::           Statistics about time to open and start the index
+The response includes a listing
+of any physical files recovered
+and their sizes.
+
+The response also includes timings in milliseconds
+of the various stages of recovery:
+
+* Index retrieval
+* Translog replay
+* Index start time
+
+This response indicates the recovery is `done`.
+All recoveries,
+whether ongoing or complete,
+are kept in the cluster state
+and may be reported on at any time.
+
+To only return information about ongoing recoveries,
+set the `active_only` query parameter to `true`.

docs/reference/rest-api/common-parms.asciidoc

@@ -1,4 +1,5 @@
 
+
 tag::actions[]
 `actions`::
 +