2013-11-14 20:14:39 -05:00
|
|
|
[[cat-recovery]]
|
2019-08-13 08:35:08 -04:00
|
|
|
=== cat recovery API
|
|
|
|
|
++++
|
|
|
|
|
<titleabbrev>cat recovery</titleabbrev>
|
|
|
|
|
++++
|
2013-11-14 20:14:39 -05:00
|
|
|
|
2019-08-12 08:17:01 -04:00
|
|
|
Returns information about ongoing and completed index shard recoveries, similar
|
|
|
|
|
to the <<indices-recovery, indices recovery>> API.
|
2013-11-14 20:14:39 -05:00
|
|
|
|
2014-05-13 16:04:48 -04:00
|
|
|
|
2019-08-12 08:17:01 -04:00
|
|
|
[[cat-recovery-api-request]]
|
|
|
|
|
==== {api-request-title}
|
|
|
|
|
|
2019-08-23 10:57:20 -04:00
|
|
|
`GET /_cat/recovery/<index>`
|
2019-08-12 08:17:01 -04:00
|
|
|
|
|
|
|
|
|
|
|
|
|
[[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
|
2013-11-14 20:14:39 -05:00
|
|
|
|
2019-09-09 13:38:14 -04:00
|
|
|
[source,console]
|
2014-10-27 15:49:58 -04:00
|
|
|
----------------------------------------------------------------------------
|
2017-02-22 03:18:10 -05:00
|
|
|
GET _cat/recovery?v
|
2017-06-09 03:50:43 -04:00
|
|
|
----------------------------------------------------------------------------
|
2017-02-22 03:18:10 -05:00
|
|
|
// TEST[setup:twitter]
|
|
|
|
|
|
2019-08-12 08:17:01 -04:00
|
|
|
The API returns the following response:
|
2017-02-22 03:18:10 -05:00
|
|
|
|
Enforce that responses in docs are valid json (#26249)
All of the snippets in our docs marked with `// TESTRESPONSE` are
checked against the response from Elasticsearch but, due to the
way they are implemented they are actually parsed as YAML instead
of JSON. Luckilly, all valid JSON is valid YAML! Unfurtunately
that means that invalid JSON has snuck into the exmples!
This adds a step during the build to parse them as JSON and fail
the build if they don't parse.
But no! It isn't quite that simple. The displayed text of some of
these responses looks like:
```
{
...
"aggregations": {
"range": {
"buckets": [
{
"to": 1.4436576E12,
"to_as_string": "10-2015",
"doc_count": 7,
"key": "*-10-2015"
},
{
"from": 1.4436576E12,
"from_as_string": "10-2015",
"doc_count": 0,
"key": "10-2015-*"
}
]
}
}
}
```
Note the `...` which isn't valid json but we like it anyway and want
it in the output. We use substitution rules to convert the `...`
into the response we expect. That yields a response that looks like:
```
{
"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,
"aggregations": {
"range": {
"buckets": [
{
"to": 1.4436576E12,
"to_as_string": "10-2015",
"doc_count": 7,
"key": "*-10-2015"
},
{
"from": 1.4436576E12,
"from_as_string": "10-2015",
"doc_count": 0,
"key": "10-2015-*"
}
]
}
}
}
```
That is what the tests consume but it isn't valid JSON! Oh no! We don't
want to go update all the substitution rules because that'd be huge and,
ultimately, wouldn't buy much. So we quote the `$body.took` bits before
parsing the JSON.
Note the responses that we use for the `_cat` APIs are all converted into
regexes and there is no expectation that they are valid JSON.
Closes #26233
2017-08-17 09:02:10 -04:00
|
|
|
[source,txt]
|
2017-02-22 03:18:10 -05:00
|
|
|
---------------------------------------------------------------------------
|
|
|
|
|
index shard time type stage source_host source_node target_host target_node repository snapshot files files_recovered files_percent files_total bytes bytes_recovered bytes_percent bytes_total translog_ops translog_ops_recovered translog_ops_percent
|
|
|
|
|
twitter 0 13ms store done n/a n/a 127.0.0.1 node-0 n/a n/a 0 0 100% 13 0 0 100% 9928 0 0 100.0%
|
|
|
|
|
---------------------------------------------------------------------------
|
|
|
|
|
// TESTRESPONSE[s/store/empty_store/]
|
|
|
|
|
// TESTRESPONSE[s/100%/0.0%/]
|
|
|
|
|
// TESTRESPONSE[s/9928/0/]
|
2019-08-06 04:28:20 -04:00
|
|
|
// TESTRESPONSE[s/13ms/[0-9.]+m?s/]
|
2019-06-10 09:33:32 -04:00
|
|
|
// TESTRESPONSE[s/13/\\d+/ non_json]
|
2014-05-13 16:04:48 -04:00
|
|
|
|
2019-08-12 08:17:01 -04:00
|
|
|
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.
|
2014-05-13 16:04:48 -04:00
|
|
|
|
2019-08-12 08:17:01 -04:00
|
|
|
[[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.
|
2014-05-13 16:04:48 -04:00
|
|
|
|
2019-09-09 13:38:14 -04:00
|
|
|
[source,console]
|
2014-10-27 15:49:58 -04:00
|
|
|
----------------------------------------------------------------------------
|
2017-02-22 03:18:10 -05:00
|
|
|
GET _cat/recovery?v&h=i,s,t,ty,st,shost,thost,f,fp,b,bp
|
2017-06-09 03:50:43 -04:00
|
|
|
----------------------------------------------------------------------------
|
2017-02-22 03:18:10 -05:00
|
|
|
// TEST[setup:twitter]
|
|
|
|
|
|
2019-08-12 08:17:01 -04:00
|
|
|
The API returns the following response:
|
2017-02-22 03:18:10 -05:00
|
|
|
|
Enforce that responses in docs are valid json (#26249)
All of the snippets in our docs marked with `// TESTRESPONSE` are
checked against the response from Elasticsearch but, due to the
way they are implemented they are actually parsed as YAML instead
of JSON. Luckilly, all valid JSON is valid YAML! Unfurtunately
that means that invalid JSON has snuck into the exmples!
This adds a step during the build to parse them as JSON and fail
the build if they don't parse.
But no! It isn't quite that simple. The displayed text of some of
these responses looks like:
```
{
...
"aggregations": {
"range": {
"buckets": [
{
"to": 1.4436576E12,
"to_as_string": "10-2015",
"doc_count": 7,
"key": "*-10-2015"
},
{
"from": 1.4436576E12,
"from_as_string": "10-2015",
"doc_count": 0,
"key": "10-2015-*"
}
]
}
}
}
```
Note the `...` which isn't valid json but we like it anyway and want
it in the output. We use substitution rules to convert the `...`
into the response we expect. That yields a response that looks like:
```
{
"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,
"aggregations": {
"range": {
"buckets": [
{
"to": 1.4436576E12,
"to_as_string": "10-2015",
"doc_count": 7,
"key": "*-10-2015"
},
{
"from": 1.4436576E12,
"from_as_string": "10-2015",
"doc_count": 0,
"key": "10-2015-*"
}
]
}
}
}
```
That is what the tests consume but it isn't valid JSON! Oh no! We don't
want to go update all the substitution rules because that'd be huge and,
ultimately, wouldn't buy much. So we quote the `$body.took` bits before
parsing the JSON.
Note the responses that we use for the `_cat` APIs are all converted into
regexes and there is no expectation that they are valid JSON.
Closes #26233
2017-08-17 09:02:10 -04:00
|
|
|
[source,txt]
|
2017-06-09 03:50:43 -04:00
|
|
|
----------------------------------------------------------------------------
|
2017-02-22 03:18:10 -05:00
|
|
|
i s t ty st shost thost f fp b bp
|
|
|
|
|
twitter 0 1252ms peer done 192.168.1.1 192.168.1.2 0 100.0% 0 100.0%
|
2014-10-27 15:49:58 -04:00
|
|
|
----------------------------------------------------------------------------
|
2017-02-22 03:18:10 -05:00
|
|
|
// TESTRESPONSE[s/peer/empty_store/]
|
|
|
|
|
// TESTRESPONSE[s/192.168.1.2/127.0.0.1/]
|
|
|
|
|
// TESTRESPONSE[s/192.168.1.1/n\/a/]
|
|
|
|
|
// TESTRESPONSE[s/100.0%/0.0%/]
|
2019-08-06 04:28:20 -04:00
|
|
|
// TESTRESPONSE[s/1252ms/[0-9.]+m?s/ non_json]
|
2014-05-13 16:04:48 -04:00
|
|
|
|
2019-08-12 08:17:01 -04:00
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
[[cat-recovery-api-ex-snapshot]]
|
|
|
|
|
===== Example with a snapshot recovery
|
2014-05-13 16:04:48 -04:00
|
|
|
|
2019-08-12 08:17:01 -04:00
|
|
|
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.
|
2013-11-14 20:14:39 -05:00
|
|
|
|
2019-09-09 13:38:14 -04:00
|
|
|
[source,console]
|
2014-10-27 15:49:58 -04:00
|
|
|
--------------------------------------------------------------------------------
|
2017-02-22 03:18:10 -05:00
|
|
|
GET _cat/recovery?v&h=i,s,t,ty,st,rep,snap,f,fp,b,bp
|
2017-06-09 03:50:43 -04:00
|
|
|
--------------------------------------------------------------------------------
|
2017-02-22 03:18:10 -05:00
|
|
|
// TEST[skip:no need to execute snapshot/restore here]
|
2014-10-27 15:49:58 -04:00
|
|
|
|
2019-08-12 08:17:01 -04:00
|
|
|
The API returns the following response with a recovery type of `snapshot`:
|
2014-10-27 15:49:58 -04:00
|
|
|
|
Enforce that responses in docs are valid json (#26249)
All of the snippets in our docs marked with `// TESTRESPONSE` are
checked against the response from Elasticsearch but, due to the
way they are implemented they are actually parsed as YAML instead
of JSON. Luckilly, all valid JSON is valid YAML! Unfurtunately
that means that invalid JSON has snuck into the exmples!
This adds a step during the build to parse them as JSON and fail
the build if they don't parse.
But no! It isn't quite that simple. The displayed text of some of
these responses looks like:
```
{
...
"aggregations": {
"range": {
"buckets": [
{
"to": 1.4436576E12,
"to_as_string": "10-2015",
"doc_count": 7,
"key": "*-10-2015"
},
{
"from": 1.4436576E12,
"from_as_string": "10-2015",
"doc_count": 0,
"key": "10-2015-*"
}
]
}
}
}
```
Note the `...` which isn't valid json but we like it anyway and want
it in the output. We use substitution rules to convert the `...`
into the response we expect. That yields a response that looks like:
```
{
"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,
"aggregations": {
"range": {
"buckets": [
{
"to": 1.4436576E12,
"to_as_string": "10-2015",
"doc_count": 7,
"key": "*-10-2015"
},
{
"from": 1.4436576E12,
"from_as_string": "10-2015",
"doc_count": 0,
"key": "10-2015-*"
}
]
}
}
}
```
That is what the tests consume but it isn't valid JSON! Oh no! We don't
want to go update all the substitution rules because that'd be huge and,
ultimately, wouldn't buy much. So we quote the `$body.took` bits before
parsing the JSON.
Note the responses that we use for the `_cat` APIs are all converted into
regexes and there is no expectation that they are valid JSON.
Closes #26233
2017-08-17 09:02:10 -04:00
|
|
|
[source,txt]
|
2017-06-09 03:50:43 -04:00
|
|
|
--------------------------------------------------------------------------------
|
2017-02-22 03:18:10 -05:00
|
|
|
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%
|
|
|
|
|
--------------------------------------------------------------------------------
|
2019-08-12 08:17:01 -04:00
|
|
|
// TESTRESPONSE[non_json]
|
