Index recovery API

Returns information about ongoing and completed shard recoveries.

GET /twitter/_recovery

Request

GET /<index>/_recovery

GET /_recovery

Description

Use the index recovery API to get information about ongoing and completed shard recoveries.

Shard recovery is the process of syncing a replica shard from a primary shard. Upon completion, the replica shard is available for search.

Recovery automatically occurs during the following processes:

Path parameters

<index>

(Optional, string) Comma-separated list or wildcard expression of index names used to limit the request.

Use a value of _all to retrieve information for all indices in the cluster.

Query parameters

active_only
(Optional, boolean) If true, the response only includes ongoing shard recoveries. Defaults to false.
detailed
(Optional, boolean) If true, the response includes detailed information about shard recoveries. Defaults to false.
index
(Optional, string) Comma-separated list or wildcard expression of index names used to limit the request.

Response body

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 snapshot restoration.
REPLICA
The recovery is related to a 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.

Examples

Get recovery information for several indices

GET index1,index2/_recovery?human

Get segment information for all indices

GET /_recovery?human

The API returns the following response:

{
  "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
      }
    } ]
  }
}

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.

Get detailed recovery information

To get a list of physical files in recovery, set the detailed query parameter to true.

GET _recovery?human&detailed=true

The API returns the following response:

{
  "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
      }
    } ]
  }
}

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.