452 lines
11 KiB
Plaintext
452 lines
11 KiB
Plaintext
[[indices-recovery]]
|
|
=== Index recovery API
|
|
++++
|
|
<titleabbrev>Index recovery</titleabbrev>
|
|
++++
|
|
|
|
|
|
Returns information about ongoing and completed shard recoveries for one or more
|
|
indices. For data streams, the API returns information for the stream's backing
|
|
indices.
|
|
|
|
[source,console]
|
|
----
|
|
GET /my-index-000001/_recovery
|
|
----
|
|
// TEST[setup:my_index]
|
|
|
|
|
|
[[index-recovery-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /<target>/_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::{es-repo-dir}/glossary.asciidoc[tag=recovery-triggers]
|
|
|
|
// end::shard-recovery-desc[]
|
|
|
|
[[index-recovery-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<target>`::
|
|
(Optional, string)
|
|
Comma-separated list of data streams, indices, and index aliases used to limit
|
|
the request. Wildcard expressions (`*`) are supported.
|
|
+
|
|
To target all data streams and indices in a cluster, omit this parameter or use
|
|
`_all` or `*`.
|
|
|
|
|
|
[[index-recovery-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=active-only]
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=detailed]
|
|
|
|
include::{es-repo-dir}/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 <<snapshots-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 data streams and indices
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET index1,index2/_recovery?human
|
|
--------------------------------------------------
|
|
// TEST[s/^/PUT index1\nPUT index2\n/]
|
|
|
|
|
|
[[index-recovery-api-all-ex]]
|
|
===== Get segment information for all data streams and indices in a cluster
|
|
|
|
//////////////////////////
|
|
Here we create a repository and snapshot index1 in
|
|
order to restore it right after and prints out the
|
|
index recovery result.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
# create the index
|
|
PUT index1
|
|
{"settings": {"index.number_of_shards": 1}}
|
|
|
|
# create the repository
|
|
PUT /_snapshot/my_repository
|
|
{"type": "fs","settings": {"location": "recovery_asciidoc" }}
|
|
|
|
# snapshot the index
|
|
PUT /_snapshot/my_repository/snap_1?wait_for_completion=true
|
|
{"indices": "index1"}
|
|
|
|
# delete the index
|
|
DELETE index1
|
|
|
|
# and restore the snapshot
|
|
POST /_snapshot/my_repository/snap_1/_restore?wait_for_completion=true
|
|
|
|
--------------------------------------------------
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"snapshot": {
|
|
"snapshot": "snap_1",
|
|
"indices": [
|
|
"index1"
|
|
],
|
|
"shards": {
|
|
"total": 1,
|
|
"failed": 0,
|
|
"successful": 1
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
//////////////////////////
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /_recovery?human
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"index1" : {
|
|
"shards" : [ {
|
|
"id" : 0,
|
|
"type" : "SNAPSHOT",
|
|
"stage" : "INDEX",
|
|
"primary" : true,
|
|
"start_time" : "2014-02-24T12:15:59.716",
|
|
"start_time_in_millis": 1393244159716,
|
|
"stop_time" : "0s",
|
|
"stop_time_in_millis" : 0,
|
|
"total_time" : "2.9m",
|
|
"total_time_in_millis" : 175576,
|
|
"source" : {
|
|
"repository" : "my_repository",
|
|
"snapshot" : "my_snapshot",
|
|
"index" : "index1",
|
|
"version" : "{version}",
|
|
"restoreUUID": "PDh1ZAOaRbiGIVtCvZOMww"
|
|
},
|
|
"target" : {
|
|
"id" : "ryqJ5lO5S4-lSFbGntkEkg",
|
|
"host" : "my.fqdn",
|
|
"transport_address" : "my.fqdn",
|
|
"ip" : "10.0.1.7",
|
|
"name" : "my_es_node"
|
|
},
|
|
"index" : {
|
|
"size" : {
|
|
"total" : "75.4mb",
|
|
"total_in_bytes" : 79063092,
|
|
"reused" : "0b",
|
|
"reused_in_bytes" : 0,
|
|
"recovered" : "65.7mb",
|
|
"recovered_in_bytes" : 68891939,
|
|
"percent" : "87.1%"
|
|
},
|
|
"files" : {
|
|
"total" : 73,
|
|
"reused" : 0,
|
|
"recovered" : 69,
|
|
"percent" : "94.5%"
|
|
},
|
|
"total_time" : "0s",
|
|
"total_time_in_millis" : 0,
|
|
"source_throttle_time" : "0s",
|
|
"source_throttle_time_in_millis" : 0,
|
|
"target_throttle_time" : "0s",
|
|
"target_throttle_time_in_millis" : 0
|
|
},
|
|
"translog" : {
|
|
"recovered" : 0,
|
|
"total" : 0,
|
|
"percent" : "100.0%",
|
|
"total_on_start" : 0,
|
|
"total_time" : "0s",
|
|
"total_time_in_millis" : 0,
|
|
},
|
|
"verify_index" : {
|
|
"check_index_time" : "0s",
|
|
"check_index_time_in_millis" : 0,
|
|
"total_time" : "0s",
|
|
"total_time_in_millis" : 0
|
|
}
|
|
} ]
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/: (\-)?[0-9]+/: $body.$_path/]
|
|
// TESTRESPONSE[s/: "[^"]*"/: $body.$_path/]
|
|
////
|
|
The TESTRESPONSE above replace all the fields values by the expected ones in the test,
|
|
because we don't really care about the field values but we want to check the fields names.
|
|
////
|
|
|
|
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.
|
|
|
|
The response also includes the number
|
|
and percentage of files and bytes recovered.
|
|
|
|
|
|
[[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]
|
|
--------------------------------------------------
|
|
GET _recovery?human&detailed=true
|
|
--------------------------------------------------
|
|
// TEST[s/^/PUT index1\n{"settings": {"index.number_of_shards": 1}}\n/]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"index1" : {
|
|
"shards" : [ {
|
|
"id" : 0,
|
|
"type" : "STORE",
|
|
"stage" : "DONE",
|
|
"primary" : true,
|
|
"start_time" : "2014-02-24T12:38:06.349",
|
|
"start_time_in_millis" : "1393245486349",
|
|
"stop_time" : "2014-02-24T12:38:08.464",
|
|
"stop_time_in_millis" : "1393245488464",
|
|
"total_time" : "2.1s",
|
|
"total_time_in_millis" : 2115,
|
|
"source" : {
|
|
"id" : "RGMdRc-yQWWKIBM4DGvwqQ",
|
|
"host" : "my.fqdn",
|
|
"transport_address" : "my.fqdn",
|
|
"ip" : "10.0.1.7",
|
|
"name" : "my_es_node"
|
|
},
|
|
"target" : {
|
|
"id" : "RGMdRc-yQWWKIBM4DGvwqQ",
|
|
"host" : "my.fqdn",
|
|
"transport_address" : "my.fqdn",
|
|
"ip" : "10.0.1.7",
|
|
"name" : "my_es_node"
|
|
},
|
|
"index" : {
|
|
"size" : {
|
|
"total" : "24.7mb",
|
|
"total_in_bytes" : 26001617,
|
|
"reused" : "24.7mb",
|
|
"reused_in_bytes" : 26001617,
|
|
"recovered" : "0b",
|
|
"recovered_in_bytes" : 0,
|
|
"percent" : "100.0%"
|
|
},
|
|
"files" : {
|
|
"total" : 26,
|
|
"reused" : 26,
|
|
"recovered" : 0,
|
|
"percent" : "100.0%",
|
|
"details" : [ {
|
|
"name" : "segments.gen",
|
|
"length" : 20,
|
|
"recovered" : 20
|
|
}, {
|
|
"name" : "_0.cfs",
|
|
"length" : 135306,
|
|
"recovered" : 135306
|
|
}, {
|
|
"name" : "segments_2",
|
|
"length" : 251,
|
|
"recovered" : 251
|
|
}
|
|
]
|
|
},
|
|
"total_time" : "2ms",
|
|
"total_time_in_millis" : 2,
|
|
"source_throttle_time" : "0s",
|
|
"source_throttle_time_in_millis" : 0,
|
|
"target_throttle_time" : "0s",
|
|
"target_throttle_time_in_millis" : 0
|
|
},
|
|
"translog" : {
|
|
"recovered" : 71,
|
|
"total" : 0,
|
|
"percent" : "100.0%",
|
|
"total_on_start" : 0,
|
|
"total_time" : "2.0s",
|
|
"total_time_in_millis" : 2025
|
|
},
|
|
"verify_index" : {
|
|
"check_index_time" : 0,
|
|
"check_index_time_in_millis" : 0,
|
|
"total_time" : "88ms",
|
|
"total_time_in_millis" : 88
|
|
}
|
|
} ]
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/"source" : \{[^}]*\}/"source" : $body.$_path/]
|
|
// TESTRESPONSE[s/"details" : \[[^\]]*\]/"details" : $body.$_path/]
|
|
// TESTRESPONSE[s/: (\-)?[0-9]+/: $body.$_path/]
|
|
// TESTRESPONSE[s/: "[^"]*"/: $body.$_path/]
|
|
////
|
|
The TESTRESPONSE above replace all the fields values by the expected ones in the test,
|
|
because we don't really care about the field values but we want to check the fields names.
|
|
It also removes the "details" part which is important in this doc but really hard to test.
|
|
////
|
|
|
|
The response includes a listing
|
|
of any physical files recovered
|
|
and their sizes.
|
|
|
|
The response also includes timings in milliseconds
|
|
of the various stages of recovery:
|
|
|
|
* Index retrieval
|
|
* Translog replay
|
|
* Index start time
|
|
|
|
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.
|
|
|
|
To only return information about ongoing recoveries,
|
|
set the `active_only` query parameter to `true`.
|