honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOCS] Reformats cat recovery API (#45345)

This commit is contained in:
James Rodewig 2019-08-12 08:17:01 -04:00
parent 499be8398f
commit 4e79e04c0e
1 changed files with 74 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
docs/reference/cat/recovery.asciidoc
View File

@ -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 <<indices-recovery,recovery>> API.
Returns information about ongoing and completed index shard recoveries, similar
to the <<indices-recovery, indices 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.
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
<<indices-recovery,indices 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.
[[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 <<modules-snapshots,snapshot and restore>>
API.
[[cat-recovery-api-ex-snapshot]]
===== Example with a snapshot recovery
You can restore backups of an index using the <<modules-snapshots,snapshot and
restore>> 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]