[DOCS] Reformats cat recovery API (#45345)
This commit is contained in:
James Rodewig
parent
499be8398f
commit
4e79e04c0e
|
|
@ -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,7 +125,7 @@ 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]
|
||||
--------------------------------------------------------------------------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue