Skip to content

Commit

Permalink
[DOCS] Reformat index recovery API docs (#46493) (#47528)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jrodewig
jrodewig authored Oct 3, 2019
1 parent ee08db3 commit 4975748
Show file tree
Hide file tree
Showing 4 changed files with 234 additions and 78 deletions.
13 changes: 5 additions & 8 deletions docs/reference/cat/recovery.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand All @@ -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]]
Expand Down
29 changes: 23 additions & 6 deletions docs/reference/glossary.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

// 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 ::

* Node startup
* Node failure
* Index shard replication
* Snapshot restoration
// 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 ::

Expand Down
269 changes: 205 additions & 64 deletions docs/reference/indices/recovery.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,185 @@
<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,js]
[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]
--------------------------------------------------
GET index1,index2/_recovery?human
--------------------------------------------------
// CONSOLE
// 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.
[source,js]
[source,console]
--------------------------------------------------
# create the index
PUT index1
Expand All @@ -45,9 +203,8 @@ DELETE index1
POST /_snapshot/my_repository/snap_1/_restore?wait_for_completion=true
--------------------------------------------------
// CONSOLE
[source,js]
[source,console-result]
--------------------------------------------------
{
"snapshot": {
Expand All @@ -63,19 +220,17 @@ POST /_snapshot/my_repository/snap_1/_restore?wait_for_completion=true
}
}
--------------------------------------------------
// TESTRESPONSE
//////////////////////////

[source,js]
[source,console]
--------------------------------------------------
GET /_recovery?human
--------------------------------------------------
// CONSOLE
// TEST[continued]

Response:
[source,js]
The API returns the following response:

[source,console-result]
--------------------------------------------------
{
"index1" : {
Expand Down Expand Up @@ -152,23 +307,30 @@ 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.

The response also includes the number
and percentage of files and bytes recovered.

Additionally, the output shows the number and percent of files recovered, as well as the number and percent of 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

[source,js]
To get a list of physical files in recovery,
set the `detailed` query parameter to `true`.

[source,console]
--------------------------------------------------
GET _recovery?human&detailed=true
--------------------------------------------------
// CONSOLE
// TEST[s/^/PUT index1\n{"settings": {"index.number_of_shards": 1}}\n/]

Response:
The API returns the following response:

[source,js]
[source,console-result]
--------------------------------------------------
{
"index1" : {
Expand Down Expand Up @@ -262,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.

Also shown are the timings in milliseconds of the various stages of recovery: index retrieval, translog replay, and index start time.

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.

Here is a complete list of options:

[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
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`.
Loading

0 comments on commit 4975748

Please sign in to comment.