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-10-03 16:43:26 -04:00
|
|
|
|
|
|
|
|
Returns information about ongoing and completed shard recoveries,
|
|
|
|
|
similar to the <<indices-recovery, index recovery>> API.
|
2013-11-14 20:14:39 -05:00
|
|
|
|
2020-06-30 15:52:48 -04:00
|
|
|
For data streams, the API returns information about the stream's backing
|
|
|
|
|
indices.
|
2014-05-13 16:04:48 -04:00
|
|
|
|
2019-08-12 08:17:01 -04:00
|
|
|
[[cat-recovery-api-request]]
|
|
|
|
|
==== {api-request-title}
|
|
|
|
|
|
2020-06-30 15:52:48 -04:00
|
|
|
`GET /_cat/recovery/<target>`
|
2019-08-12 08:17:01 -04:00
|
|
|
|
2019-09-27 16:31:10 -04:00
|
|
|
`GET /_cat/recovery`
|
|
|
|
|
|
2019-08-12 08:17:01 -04:00
|
|
|
|
|
|
|
|
[[cat-recovery-api-desc]]
|
|
|
|
|
==== {api-description-title}
|
|
|
|
|
|
2019-10-03 16:43:26 -04:00
|
|
|
The cat recovery API returns information about shard recoveries, both
|
2019-08-12 08:17:01 -04:00
|
|
|
ongoing and completed. It is a more compact view of the JSON
|
2019-10-01 17:07:28 -04:00
|
|
|
<<indices-recovery,index recovery>> API.
|
2019-08-12 08:17:01 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/indices/recovery.asciidoc[tag=shard-recovery-desc]
|
2019-08-12 08:17:01 -04:00
|
|
|
|
|
|
|
|
|
|
|
|
|
[[cat-recovery-path-params]]
|
|
|
|
|
==== {api-path-parms-title}
|
|
|
|
|
|
2020-06-30 15:52:48 -04:00
|
|
|
`<target>`::
|
|
|
|
|
(Optional, string)
|
2020-06-30 15:55:37 -04:00
|
|
|
Comma-separated list of data streams, indices, and index aliases used to limit
|
|
|
|
|
the request. Wildcard expressions (`*`) are supported.
|
2020-06-30 15:52:48 -04:00
|
|
|
+
|
|
|
|
|
To target all data streams and indices in a cluster, omit this parameter or use
|
|
|
|
|
`_all` or `*`.
|
2019-08-12 08:17:01 -04:00
|
|
|
|
|
|
|
|
|
|
|
|
|
[[cat-recovery-query-params]]
|
|
|
|
|
==== {api-query-parms-title}
|
|
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=active-only]
|
2019-09-27 16:31:10 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=bytes]
|
2019-08-12 08:17:01 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=detailed]
|
2019-09-27 16:31:10 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=http-format]
|
2019-08-12 08:17:01 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-h]
|
2019-08-12 08:17:01 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=help]
|
2019-08-12 08:17:01 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-query-parm]
|
2019-09-27 16:31:10 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-s]
|
2019-08-12 08:17:01 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=time]
|
2019-10-10 09:48:40 -04:00
|
|
|
|
2020-06-01 19:42:53 -04:00
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-v]
|
2019-08-12 08:17:01 -04:00
|
|
|
|
|
|
|
|
|
|
|
|
|
[[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
|
|
|
----------------------------------------------------------------------------
|
2020-08-03 10:22:36 -04:00
|
|
|
// TEST[setup:my_index]
|
2017-02-22 03:18:10 -05:00
|
|
|
|
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
|
|
|
---------------------------------------------------------------------------
|
2020-08-03 10:22:36 -04: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
|
|
|
|
|
my-index-000001 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%
|
2017-02-22 03:18:10 -05:00
|
|
|
---------------------------------------------------------------------------
|
|
|
|
|
// 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
|
|
|
----------------------------------------------------------------------------
|
2020-08-03 10:22:36 -04:00
|
|
|
// TEST[setup:my_index]
|
2017-02-22 03:18:10 -05:00
|
|
|
|
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
|
|
|
----------------------------------------------------------------------------
|
2020-08-03 10:22:36 -04:00
|
|
|
i s t ty st shost thost f fp b bp
|
|
|
|
|
my-index-000001 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
|
|
|
--------------------------------------------------------------------------------
|
2020-08-03 10:22:36 -04:00
|
|
|
i s t ty st rep snap f fp b bp
|
|
|
|
|
my-index-000001 0 1978ms snapshot done my-repo snap_1 79 8.0% 12086 9.0%
|
2017-02-22 03:18:10 -05:00
|
|
|
--------------------------------------------------------------------------------
|
2019-08-12 08:17:01 -04:00
|
|
|
// TESTRESPONSE[non_json]
|
