From 4e79e04c0e818b26bb68c0d50f8d6adad369c5e9 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 12 Aug 2019 08:17:01 -0400 Subject: [PATCH] [DOCS] Reformats cat recovery API (#45345) --- docs/reference/cat/recovery.asciidoc | 97 +++++++++++++++++++++------- 1 file changed, 74 insertions(+), 23 deletions(-) diff --git a/docs/reference/cat/recovery.asciidoc b/docs/reference/cat/recovery.asciidoc index 4f7f153a155..ab7f6fbe7f1 100644 --- a/docs/reference/cat/recovery.asciidoc +++ b/docs/reference/cat/recovery.asciidoc @@ -1,16 +1,61 @@ [[cat-recovery]] === cat recovery -The `recovery` command is a view of index shard recoveries, both on-going and previously -completed. It is a more compact view of the JSON <> API. +Returns information about ongoing and completed index shard recoveries, similar +to the <> 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. -As an example, here is what the recovery state of a cluster may look like when there -are no shards in transit from one node to another: +[[cat-recovery-api-request]] +==== {api-request-title} + +`GET /_cat/recovery/{index}` + + +[[cat-recovery-api-desc]] +==== {api-description-title} + +The cat recovery API returns information about index shard recoveries, both +ongoing and completed. It is a more compact view of the JSON +<> 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. + + +[[cat-recovery-path-params]] +==== {api-path-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index] + + +[[cat-recovery-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=bytes] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=help] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=local] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v] + + +[[cat-recovery-api-example]] +==== {api-examples-title} + +[[cat-recovery-api-ex-dead]] +===== Example with no ongoing recoveries [source,js] ---------------------------------------------------------------------------- @@ -19,7 +64,7 @@ GET _cat/recovery?v // CONSOLE // TEST[setup:twitter] -The response of this request will be something like: +The API returns the following response: [source,txt] --------------------------------------------------------------------------- @@ -32,12 +77,15 @@ twitter 0 13ms store done n/a n/a 127.0.0.1 node-0 n // TESTRESPONSE[s/13ms/[0-9.]+m?s/] // TESTRESPONSE[s/13/\\d+/ non_json] -In the above case, the source and target nodes are the same because the recovery -type was store, i.e. they were read from local storage on node start. +In this example response, the source and target nodes are the same because the +recovery type is `store`, meaning they were read from local storage on node +start. -Now let's see what a live recovery looks like. By increasing the replica count -of our index and bringing another node online to host the replicas, we can see -what a live shard recovery looks like. +[[cat-recovery-api-ex-live]] +===== Example with a live shard recovery + +By increasing the replica count of an index and bringing another node online to +host the replicas, you can retrieve information about an ongoing recovery. [source,js] ---------------------------------------------------------------------------- @@ -46,7 +94,7 @@ GET _cat/recovery?v&h=i,s,t,ty,st,shost,thost,f,fp,b,bp // CONSOLE // TEST[setup:twitter] -This will return a line like: +The API returns the following response: [source,txt] ---------------------------------------------------------------------------- @@ -59,13 +107,16 @@ twitter 0 1252ms peer done 192.168.1.1 192.168.1.2 0 100.0% 0 100.0% // TESTRESPONSE[s/100.0%/0.0%/] // TESTRESPONSE[s/1252ms/[0-9.]+m?s/ non_json] -We can see in the above listing that our thw twitter shard was recovered from another node. -Notice that the recovery type is shown as `peer`. The files and bytes copied are -real-time measurements. +In this example response, the recovery type is `peer`, meaning the shard +recovered from another node. The returned files and bytes are real-time +measurements. -Finally, let's see what a snapshot recovery looks like. Assuming I have previously -made a backup of my index, I can restore it using the <> -API. +[[cat-recovery-api-ex-snapshot]] +===== Example with a snapshot recovery + +You can restore backups of an index using the <> API. You can use the cat recovery API retrieve information about a +snapshot recovery. [source,js] -------------------------------------------------------------------------------- @@ -74,11 +125,11 @@ GET _cat/recovery?v&h=i,s,t,ty,st,rep,snap,f,fp,b,bp // CONSOLE // TEST[skip:no need to execute snapshot/restore here] -This will show a recovery of type snapshot in the response +The API returns the following response with a recovery type of `snapshot`: [source,txt] -------------------------------------------------------------------------------- i s t ty st rep snap f fp b bp twitter 0 1978ms snapshot done twitter snap_1 79 8.0% 12086 9.0% -------------------------------------------------------------------------------- -// TESTRESPONSE[non_json] +// TESTRESPONSE[non_json] \ No newline at end of file