James Rodewig
GitHub
parent
56e7668c78
commit
b8e7f5069d
|
|
@ -4,8 +4,9 @@
|
|||
<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]]
|
||||
|
|
@ -19,15 +20,11 @@ to the <<indices-recovery, index recovery>> API.
|
|||
[[cat-recovery-api-desc]]
|
||||
==== {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
|
||||
<<indices-recovery,index 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.
|
||||
include::{docdir}/indices/recovery.asciidoc[tag=shard-recovery-desc]
|
||||
|
||||
|
||||
[[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>>.
|
||||
|
||||
[[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
|
||||
* Node failure
|
||||
* Index shard replication
|
||||
* Snapshot restoration
|
||||
// tag::recovery-triggers[]
|
||||
Recovery automatically occurs
|
||||
during the following processes:
|
||||
|
||||
* 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 ::
|
||||
|
||||
|
|
|
|||
|
|
@ -4,10 +4,168 @@
|
|||
<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]
|
||||
--------------------------------------------------
|
||||
|
|
@ -15,10 +173,11 @@ GET index1,index2/_recovery?human
|
|||
--------------------------------------------------
|
||||
// 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
|
||||
order to restore it right after and prints out the
|
||||
index recovery result.
|
||||
|
|
@ -61,7 +220,6 @@ POST /_snapshot/my_repository/snap_1/_restore?wait_for_completion=true
|
|||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
//////////////////////////
|
||||
|
||||
[source,console]
|
||||
|
|
@ -70,7 +228,7 @@ GET /_recovery?human
|
|||
--------------------------------------------------
|
||||
// TEST[continued]
|
||||
|
||||
Response:
|
||||
The API returns the following response:
|
||||
|
||||
[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.
|
||||
////
|
||||
|
||||
The above response shows a single index recovering a single shard. In this case, the source of the recovery is a snapshot repository
|
||||
and the target of the recovery is the node with name "my_es_node".
|
||||
This response includes information
|
||||
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]
|
||||
--------------------------------------------------
|
||||
|
|
@ -162,7 +328,7 @@ GET _recovery?human&detailed=true
|
|||
--------------------------------------------------
|
||||
// TEST[s/^/PUT index1\n{"settings": {"index.number_of_shards": 1}}\n/]
|
||||
|
||||
Response:
|
||||
The API returns the following response:
|
||||
|
||||
[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.
|
||||
////
|
||||
|
||||
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
|
||||
cluster state and may be reported on at any time. Setting "active_only=true" will cause only on-going recoveries to be reported.
|
||||
* Index retrieval
|
||||
* 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]
|
||||
`detailed`:: Display a detailed view. This is primarily useful for viewing the recovery of physical index files. Default: false.
|
||||
`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
|
||||
To only return information about ongoing recoveries,
|
||||
set the `active_only` query parameter to `true`.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
|
||||
|
||||
tag::actions[]
|
||||
`actions`::
|
||||
+
|
||||
|
|
|
|||
Loading…
Reference in New Issue