mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-28 17:34:17 -04:00
33a71e3289
* Remove `es-test-dir` book-scoped variable * Remove `plugins-examples-dir` book-scoped variable * Remove `:dependencies-dir:` and `:xes-repo-dir:` book-scoped variables - In `index.asciidoc`, two variables (`:dependencies-dir:` and `:xes-repo-dir:`) were removed. - In `sql/index.asciidoc`, the `:sql-tests:` path was updated to fuller path - In `esql/index.asciidoc`, the `:esql-tests:` path was updated idem * Replace `es-repo-dir` with `es-ref-dir` * Move `:include-xpack: true` to few files that use it, remove from index.asciidoc
155 lines
No EOL
5.8 KiB
Text
155 lines
No EOL
5.8 KiB
Text
[[cat-recovery]]
|
|
=== cat recovery API
|
|
++++
|
|
<titleabbrev>cat recovery</titleabbrev>
|
|
++++
|
|
|
|
[IMPORTANT]
|
|
====
|
|
cat APIs are only intended for human consumption using the command line or {kib}
|
|
console. They are _not_ intended for use by applications. For application
|
|
consumption, use the <<indices-recovery,index recovery API>>.
|
|
====
|
|
|
|
Returns information about ongoing and completed shard recoveries,
|
|
similar to the <<indices-recovery, index recovery>> API.
|
|
|
|
For data streams, the API returns information about the stream's backing
|
|
indices.
|
|
|
|
[[cat-recovery-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_cat/recovery/<target>`
|
|
|
|
`GET /_cat/recovery`
|
|
|
|
[[cat-recovery-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have the `monitor` or
|
|
`manage` <<privileges-list-cluster,cluster privilege>> to use this API. You must
|
|
also have the `monitor` or `manage` <<privileges-list-indices,index privilege>>
|
|
for any data stream, index, or alias you retrieve.
|
|
|
|
[[cat-recovery-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
The cat recovery API returns information about shard recoveries, both
|
|
ongoing and completed. It is a more compact view of the JSON
|
|
<<indices-recovery,index recovery>> API.
|
|
|
|
include::{es-ref-dir}/indices/recovery.asciidoc[tag=shard-recovery-desc]
|
|
|
|
|
|
[[cat-recovery-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<target>`::
|
|
(Optional, string) Comma-separated list of data streams, indices, and aliases
|
|
used to limit the request. Supports wildcards (`*`). To target all data streams
|
|
and indices, omit this parameter or use `*` or `_all`.
|
|
|
|
[[cat-recovery-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=active-only]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=bytes]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=detailed]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=http-format]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=cat-h]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=help]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=index-query-parm]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=cat-s]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=time]
|
|
|
|
include::{es-ref-dir}/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,console]
|
|
----------------------------------------------------------------------------
|
|
GET _cat/recovery?v=true
|
|
----------------------------------------------------------------------------
|
|
// TEST[setup:my_index]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,txt]
|
|
---------------------------------------------------------------------------
|
|
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 0b 0b 100% 9928b 0 0 100.0%
|
|
---------------------------------------------------------------------------
|
|
// TESTRESPONSE[s/store/empty_store/]
|
|
// TESTRESPONSE[s/100%/0.0%/]
|
|
// TESTRESPONSE[s/9928b/0b/]
|
|
// TESTRESPONSE[s/13ms/[0-9.]+m?s/]
|
|
// TESTRESPONSE[s/13/\\d+/ non_json]
|
|
|
|
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.
|
|
|
|
[[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,console]
|
|
----------------------------------------------------------------------------
|
|
GET _cat/recovery?v=true&h=i,s,t,ty,st,shost,thost,f,fp,b,bp
|
|
----------------------------------------------------------------------------
|
|
// TEST[setup:my_index]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,txt]
|
|
----------------------------------------------------------------------------
|
|
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% 0b 100.0%
|
|
----------------------------------------------------------------------------
|
|
// 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%/]
|
|
// TESTRESPONSE[s/1252ms/[0-9.]+m?s/ non_json]
|
|
|
|
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
|
|
|
|
You can restore backups of an index using the <<snapshot-restore,snapshot and
|
|
restore>> API. You can use the cat recovery API retrieve information about a
|
|
snapshot recovery.
|
|
|
|
[source,console]
|
|
--------------------------------------------------------------------------------
|
|
GET _cat/recovery?v=true&h=i,s,t,ty,st,rep,snap,f,fp,b,bp
|
|
--------------------------------------------------------------------------------
|
|
// TEST[skip:no need to execute snapshot/restore here]
|
|
|
|
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
|
|
my-index-000001 0 1978ms snapshot done my-repo snap-1 79 8.0% 12086 9.0%
|
|
--------------------------------------------------------------------------------
|
|
// TESTRESPONSE[non_json] |