parent
56e7668c78
commit
b8e7f5069d
|
@ -4,8 +4,9 @@
|
||||||
<titleabbrev>cat recovery</titleabbrev>
|
<titleabbrev>cat recovery</titleabbrev>
|
||||||
++++
|
++++
|
||||||
|
|
||||||
Returns information about ongoing and completed index shard recoveries, similar
|
|
||||||
to the <<indices-recovery, index recovery>> API.
|
Returns information about ongoing and completed shard recoveries,
|
||||||
|
similar to the <<indices-recovery, index recovery>> API.
|
||||||
|
|
||||||
|
|
||||||
[[cat-recovery-api-request]]
|
[[cat-recovery-api-request]]
|
||||||
|
@ -19,15 +20,11 @@ to the <<indices-recovery, index recovery>> API.
|
||||||
[[cat-recovery-api-desc]]
|
[[cat-recovery-api-desc]]
|
||||||
==== {api-description-title}
|
==== {api-description-title}
|
||||||
|
|
||||||
The cat recovery API returns information about index shard recoveries, both
|
The cat recovery API returns information about shard recoveries, both
|
||||||
ongoing and completed. It is a more compact view of the JSON
|
ongoing and completed. It is a more compact view of the JSON
|
||||||
<<indices-recovery,index recovery>> API.
|
<<indices-recovery,index recovery>> API.
|
||||||
|
|
||||||
A recovery event occurs anytime an index shard moves to a different node in the
|
include::{docdir}/indices/recovery.asciidoc[tag=shard-recovery-desc]
|
||||||
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]]
|
[[cat-recovery-path-params]]
|
||||||
|
|
|
@ -165,14 +165,31 @@ There are two types of queries: _scoring queries_ and _filters_. For more
|
||||||
information about query types, see <<query-filter-context>>.
|
information about query types, see <<query-filter-context>>.
|
||||||
|
|
||||||
[[glossary-recovery]] recovery ::
|
[[glossary-recovery]] recovery ::
|
||||||
The process of syncing a shard copy from a source shard. Upon completion, the recovery process makes the shard copy available for queries.
|
|
||||||
+
|
+
|
||||||
Recovery automatically occurs anytime a shard moves to a different node in the same cluster, including:
|
--
|
||||||
|
Shard recovery is the process
|
||||||
|
of syncing a <<glossary-replica-shard,replica shard>>
|
||||||
|
from a <<glossary-primary-shard,primary shard>>.
|
||||||
|
Upon completion,
|
||||||
|
the replica shard is available for search.
|
||||||
|
|
||||||
* Node startup
|
// tag::recovery-triggers[]
|
||||||
* Node failure
|
Recovery automatically occurs
|
||||||
* Index shard replication
|
during the following processes:
|
||||||
* Snapshot restoration
|
|
||||||
|
* Node startup or failure.
|
||||||
|
This type of recovery is called a *local store recovery*.
|
||||||
|
* <<glossary-replica-shard,Primary shard replication>>.
|
||||||
|
* Relocation of a shard to a different node in the same cluster.
|
||||||
|
* {ref}/modules-snapshots.html#restore-snapshot[Snapshot restoration].
|
||||||
|
// end::recovery-triggers[]
|
||||||
|
--
|
||||||
|
|
||||||
|
[[glossary-reindex]] reindex ::
|
||||||
|
|
||||||
|
// tag::reindex-def[]
|
||||||
|
To cycle through some or all documents in one or more indices, re-writing them into the same or new index in a local or remote cluster. This is most commonly done to update mappings, or to upgrade Elasticsearch between two incompatible index versions.
|
||||||
|
// end::reindex-def[]
|
||||||
|
|
||||||
[[glossary-replica-shard]] replica shard ::
|
[[glossary-replica-shard]] replica shard ::
|
||||||
|
|
||||||
|
|
|
@ -4,10 +4,168 @@
|
||||||
<titleabbrev>Index recovery</titleabbrev>
|
<titleabbrev>Index recovery</titleabbrev>
|
||||||
++++
|
++++
|
||||||
|
|
||||||
The index recovery API provides insight into on-going index shard recoveries.
|
|
||||||
Recovery status may be reported for specific indices, or cluster-wide.
|
|
||||||
|
|
||||||
For example, the following command would show recovery information for the indices "index1" and "index2".
|
Returns information about ongoing and completed shard recoveries.
|
||||||
|
|
||||||
|
[source,console]
|
||||||
|
----
|
||||||
|
GET /twitter/_recovery
|
||||||
|
----
|
||||||
|
// TEST[setup:twitter]
|
||||||
|
|
||||||
|
|
||||||
|
[[index-recovery-api-request]]
|
||||||
|
==== {api-request-title}
|
||||||
|
|
||||||
|
`GET /<index>/_recovery`
|
||||||
|
|
||||||
|
`GET /_recovery`
|
||||||
|
|
||||||
|
|
||||||
|
[[index-recovery-api-desc]]
|
||||||
|
==== {api-description-title}
|
||||||
|
|
||||||
|
Use the index recovery API
|
||||||
|
to get information about ongoing and completed shard recoveries.
|
||||||
|
|
||||||
|
// tag::shard-recovery-desc[]
|
||||||
|
Shard recovery is the process
|
||||||
|
of syncing a replica shard from a primary shard.
|
||||||
|
Upon completion,
|
||||||
|
the replica shard is available for search.
|
||||||
|
|
||||||
|
include::{docdir}/glossary.asciidoc[tag=recovery-triggers]
|
||||||
|
|
||||||
|
// end::shard-recovery-desc[]
|
||||||
|
|
||||||
|
[[index-recovery-api-path-params]]
|
||||||
|
==== {api-path-parms-title}
|
||||||
|
|
||||||
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
|
||||||
|
+
|
||||||
|
Use a value of `_all` to retrieve information for all indices in the cluster.
|
||||||
|
|
||||||
|
|
||||||
|
[[index-recovery-api-query-params]]
|
||||||
|
==== {api-query-parms-title}
|
||||||
|
|
||||||
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=active-only]
|
||||||
|
|
||||||
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=detailed]
|
||||||
|
|
||||||
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=index-query-parm]
|
||||||
|
|
||||||
|
|
||||||
|
[[index-recovery-api-response-body]]
|
||||||
|
==== {api-response-body-title}
|
||||||
|
|
||||||
|
`id`::
|
||||||
|
(Integer)
|
||||||
|
ID of the shard.
|
||||||
|
|
||||||
|
`type`::
|
||||||
|
+
|
||||||
|
--
|
||||||
|
(String)
|
||||||
|
Recovery type.
|
||||||
|
Returned values include:
|
||||||
|
|
||||||
|
`STORE`::
|
||||||
|
The recovery is related to
|
||||||
|
a node startup or failure.
|
||||||
|
This type of recovery is called a local store recovery.
|
||||||
|
|
||||||
|
`SNAPSHOT`::
|
||||||
|
The recovery is related to
|
||||||
|
a <<restore-snapshot,snapshot restoration>>.
|
||||||
|
|
||||||
|
`REPLICA`::
|
||||||
|
The recovery is related to
|
||||||
|
a <<glossary-replica-shard,primary shard replication>>.
|
||||||
|
|
||||||
|
`RELOCATING`::
|
||||||
|
The recovery is related to
|
||||||
|
the relocation of a shard
|
||||||
|
to a different node in the same cluster.
|
||||||
|
--
|
||||||
|
|
||||||
|
`STAGE`::
|
||||||
|
+
|
||||||
|
--
|
||||||
|
(String)
|
||||||
|
Recovery stage.
|
||||||
|
Returned values include:
|
||||||
|
|
||||||
|
`DONE`::
|
||||||
|
Complete.
|
||||||
|
|
||||||
|
`FINALIZE`::
|
||||||
|
Cleanup.
|
||||||
|
|
||||||
|
`INDEX`::
|
||||||
|
Reading index metadata and copying bytes from source to destination.
|
||||||
|
|
||||||
|
`INIT`::
|
||||||
|
Recovery has not started.
|
||||||
|
|
||||||
|
`START`::
|
||||||
|
Starting the recovery process; opening the index for use.
|
||||||
|
|
||||||
|
`TRANSLOG`::
|
||||||
|
Replaying transaction log .
|
||||||
|
--
|
||||||
|
|
||||||
|
`primary`::
|
||||||
|
(Boolean)
|
||||||
|
If `true`,
|
||||||
|
the shard is a primary shard.
|
||||||
|
|
||||||
|
`start_time`::
|
||||||
|
(String)
|
||||||
|
Timestamp of recovery start.
|
||||||
|
|
||||||
|
`stop_time`::
|
||||||
|
(String)
|
||||||
|
Timestamp of recovery finish.
|
||||||
|
|
||||||
|
`total_time_in_millis`::
|
||||||
|
(String)
|
||||||
|
Total time to recover shard in milliseconds.
|
||||||
|
|
||||||
|
`source`::
|
||||||
|
+
|
||||||
|
--
|
||||||
|
(Object)
|
||||||
|
Recovery source.
|
||||||
|
This can include:
|
||||||
|
|
||||||
|
* A repository description if recovery is from a snapshot
|
||||||
|
* A description of source node
|
||||||
|
--
|
||||||
|
|
||||||
|
`target`::
|
||||||
|
(Object)
|
||||||
|
Destination node.
|
||||||
|
|
||||||
|
`index`::
|
||||||
|
(Object)
|
||||||
|
Statistics about physical index recovery.
|
||||||
|
|
||||||
|
`translog`::
|
||||||
|
(Object)
|
||||||
|
Statistics about translog recovery.
|
||||||
|
|
||||||
|
`start`::
|
||||||
|
(Object)
|
||||||
|
Statistics about time to open and start the index.
|
||||||
|
|
||||||
|
|
||||||
|
[[index-recovery-api-example]]
|
||||||
|
==== {api-examples-title}
|
||||||
|
|
||||||
|
|
||||||
|
[[index-recovery-api-multi-ex]]
|
||||||
|
===== Get recovery information for several indices
|
||||||
|
|
||||||
[source,console]
|
[source,console]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
@ -15,10 +173,11 @@ GET index1,index2/_recovery?human
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
// TEST[s/^/PUT index1\nPUT index2\n/]
|
// TEST[s/^/PUT index1\nPUT index2\n/]
|
||||||
|
|
||||||
To see cluster-wide recovery status simply leave out the index names.
|
|
||||||
|
[[index-recovery-api-all-ex]]
|
||||||
|
===== Get segment information for all indices
|
||||||
|
|
||||||
//////////////////////////
|
//////////////////////////
|
||||||
|
|
||||||
Here we create a repository and snapshot index1 in
|
Here we create a repository and snapshot index1 in
|
||||||
order to restore it right after and prints out the
|
order to restore it right after and prints out the
|
||||||
index recovery result.
|
index recovery result.
|
||||||
|
@ -61,7 +220,6 @@ POST /_snapshot/my_repository/snap_1/_restore?wait_for_completion=true
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
|
||||||
//////////////////////////
|
//////////////////////////
|
||||||
|
|
||||||
[source,console]
|
[source,console]
|
||||||
|
@ -70,7 +228,7 @@ GET /_recovery?human
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
// TEST[continued]
|
// TEST[continued]
|
||||||
|
|
||||||
Response:
|
The API returns the following response:
|
||||||
|
|
||||||
[source,console-result]
|
[source,console-result]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
@ -149,12 +307,20 @@ The TESTRESPONSE above replace all the fields values by the expected ones in the
|
||||||
because we don't really care about the field values but we want to check the fields names.
|
because we don't really care about the field values but we want to check the fields names.
|
||||||
////
|
////
|
||||||
|
|
||||||
The above response shows a single index recovering a single shard. In this case, the source of the recovery is a snapshot repository
|
This response includes information
|
||||||
and the target of the recovery is the node with name "my_es_node".
|
about a single index recovering a single shard.
|
||||||
|
The source of the recovery is a snapshot repository
|
||||||
|
and the target of the recovery is the `my_es_node` node.
|
||||||
|
|
||||||
Additionally, the output shows the number and percent of files recovered, as well as the number and percent of bytes recovered.
|
The response also includes the number
|
||||||
|
and percentage of files and bytes recovered.
|
||||||
|
|
||||||
In some cases a higher level of detail may be preferable. Setting "detailed=true" will present a list of physical files in recovery.
|
|
||||||
|
[[index-recovery-api-detailed-ex]]
|
||||||
|
===== Get detailed recovery information
|
||||||
|
|
||||||
|
To get a list of physical files in recovery,
|
||||||
|
set the `detailed` query parameter to `true`.
|
||||||
|
|
||||||
[source,console]
|
[source,console]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
@ -162,7 +328,7 @@ GET _recovery?human&detailed=true
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
// TEST[s/^/PUT index1\n{"settings": {"index.number_of_shards": 1}}\n/]
|
// TEST[s/^/PUT index1\n{"settings": {"index.number_of_shards": 1}}\n/]
|
||||||
|
|
||||||
Response:
|
The API returns the following response:
|
||||||
|
|
||||||
[source,console-result]
|
[source,console-result]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
@ -258,43 +424,22 @@ because we don't really care about the field values but we want to check the fie
|
||||||
It also removes the "details" part which is important in this doc but really hard to test.
|
It also removes the "details" part which is important in this doc but really hard to test.
|
||||||
////
|
////
|
||||||
|
|
||||||
This response shows a detailed listing (truncated for brevity) of the actual files recovered and their sizes.
|
The response includes a listing
|
||||||
|
of any physical files recovered
|
||||||
|
and their sizes.
|
||||||
|
|
||||||
Also shown are the timings in milliseconds of the various stages of recovery: index retrieval, translog replay, and index start time.
|
The response also includes timings in milliseconds
|
||||||
|
of the various stages of recovery:
|
||||||
|
|
||||||
Note that the above listing indicates that the recovery is in stage "done". All recoveries, whether on-going or complete, are kept in
|
* Index retrieval
|
||||||
cluster state and may be reported on at any time. Setting "active_only=true" will cause only on-going recoveries to be reported.
|
* Translog replay
|
||||||
|
* Index start time
|
||||||
|
|
||||||
Here is a complete list of options:
|
This response indicates the recovery is `done`.
|
||||||
|
All recoveries,
|
||||||
|
whether ongoing or complete,
|
||||||
|
are kept in the cluster state
|
||||||
|
and may be reported on at any time.
|
||||||
|
|
||||||
[horizontal]
|
To only return information about ongoing recoveries,
|
||||||
`detailed`:: Display a detailed view. This is primarily useful for viewing the recovery of physical index files. Default: false.
|
set the `active_only` query parameter to `true`.
|
||||||
`active_only`:: Display only those recoveries that are currently on-going. Default: false.
|
|
||||||
|
|
||||||
Description of output fields:
|
|
||||||
|
|
||||||
[horizontal]
|
|
||||||
`id`:: Shard ID
|
|
||||||
`type`:: Recovery type:
|
|
||||||
* store
|
|
||||||
* snapshot
|
|
||||||
* replica
|
|
||||||
* relocating
|
|
||||||
`stage`:: Recovery stage:
|
|
||||||
* init: Recovery has not started
|
|
||||||
* index: Reading index meta-data and copying bytes from source to destination
|
|
||||||
* start: Starting the engine; opening the index for use
|
|
||||||
* translog: Replaying transaction log
|
|
||||||
* finalize: Cleanup
|
|
||||||
* done: Complete
|
|
||||||
`primary`:: True if shard is primary, false otherwise
|
|
||||||
`start_time`:: Timestamp of recovery start
|
|
||||||
`stop_time`:: Timestamp of recovery finish
|
|
||||||
`total_time_in_millis`:: Total time to recover shard in milliseconds
|
|
||||||
`source`:: Recovery source:
|
|
||||||
* repository description if recovery is from a snapshot
|
|
||||||
* description of source node otherwise
|
|
||||||
`target`:: Destination node
|
|
||||||
`index`:: Statistics about physical index recovery
|
|
||||||
`translog`:: Statistics about translog recovery
|
|
||||||
`start`:: Statistics about time to open and start the index
|
|
||||||
|
|
|
@ -1,4 +1,5 @@
|
||||||
|
|
||||||
|
|
||||||
tag::actions[]
|
tag::actions[]
|
||||||
`actions`::
|
`actions`::
|
||||||
+
|
+
|
||||||
|
|
Loading…
Reference in New Issue