New

The executive guide to generative AI

Read more
About usPartnersSupport|Login

WARNING: Version 5.0 of Elasticsearch has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« Nodes hot_threads Query DSL »
Elastic Docs ›Elasticsearch Guide [5.0] ›Cluster APIs

Cluster Allocation Explain API

edit

Cluster Allocation Explain API

edit

The cluster allocation explanation API is designed to assist in answering the question "why is this shard unassigned?". To explain the allocation (on unassigned state) of a shard, issue a request like:

The cluster allocation explain API is new and should still be considered experimental. The API may change in ways that are not backwards compatible

$ curl -XGET 'http://localhost:9200/_cluster/allocation/explain' -d'{
  "index": "myindex",
  "shard": 0,
  "primary": false
}'

Specify the index and shard id of the shard you would like an explanation for, as well as the primary flag to indicate whether to explain a primary or replica shard.

The response looks like:

{
  "shard" : {
    "index" : "myindex",
    "index_uuid" : "KnW0-zELRs6PK84l0r38ZA",
    "id" : 0,
    "primary" : false
  },
  "assigned" : false,                             
  "shard_state_fetch_pending": false,             
  "unassigned_info" : {
    "reason" : "INDEX_CREATED",                   
    "at" : "2016-03-22T20:04:23.620Z"
  },
  "allocation_delay_ms" : 0,                      
  "remaining_delay_ms" : 0,                       
  "nodes" : {
    "V-Spi0AyRZ6ZvKbaI3691w" : {
      "node_name" : "H5dfFeA",
      "node_attributes" : {                       
        "bar" : "baz"
      },
      "store" : {
        "shard_copy" : "NONE"                     
      },
      "final_decision" : "NO",                    
      "final_explanation" : "the shard cannot be assigned because one or more allocation decider returns a 'NO' decision",
      "weight" : 0.06666675,                      
      "decisions" : [ {                           
        "decider" : "filter",
        "decision" : "NO",
        "explanation" : "node does not match index include filters [foo:\"bar\"]"
      } ]
    },
    "Qc6VL8c5RWaw1qXZ0Rg57g" : {
      "node_name" : "bGG90GE",
      "node_attributes" : {
        "bar" : "baz",
        "foo" : "bar"
      },
      "store" : {
        "shard_copy" : "AVAILABLE"
      },
      "final_decision" : "NO",
      "final_explanation" : "the shard cannot be assigned because one or more allocation decider returns a 'NO' decision",
      "weight" : -1.3833332,
      "decisions" : [ {
        "decider" : "same_shard",
        "decision" : "NO",
        "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists"
      } ]
    },
    "PzdyMZGXQdGhqTJHF_hGgA" : {
      "node_name" : "DKDM97B",
      "node_attributes" : { },
      "store" : {
        "shard_copy" : "NONE"
      },
      "final_decision" : "NO",
      "final_explanation" : "the shard cannot be assigned because one or more allocation decider returns a 'NO' decision",
      "weight" : 2.3166666,
      "decisions" : [ {
        "decider" : "filter",
        "decision" : "NO",
        "explanation" : "node does not match index include filters [foo:\"bar\"]"
      } ]
    }
  }
}

Whether the shard is assigned or unassigned

Whether information about the shard is still being fetched

Reason for the shard originally becoming unassigned

Configured delay before the shard can be allocated

Remaining delay before the shard can be allocated

User-added attributes the node has

The shard copy information for this node and error (if applicable)

Final decision and explanation of whether the shard can be allocated to this node

Weight for how much the allocator would like to allocate the shard to this node

List of node decisions factoring into final decision about the shard

For a shard that is already assigned, the output looks similar to:

{
  "shard" : {
    "index" : "only-foo",
    "index_uuid" : "KnW0-zELRs6PK84l0r38ZA",
    "id" : 0,
    "primary" : true
  },
  "assigned" : true,
  "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g",      
  "shard_state_fetch_pending": false,
  "allocation_delay_ms" : 0,
  "remaining_delay_ms" : 0,
  "nodes" : {
    "V-Spi0AyRZ6ZvKbaI3691w" : {
      "node_name" : "bGG90GE",
      "node_attributes" : {
        "bar" : "baz"
      },
      "store" : {
        "shard_copy" : "NONE"
      },
      "final_decision" : "NO",
      "final_explanation" : "the shard cannot be assigned because one or more allocation decider returns a 'NO' decision",
      "weight" : 1.4499999,
      "decisions" : [ {
        "decider" : "filter",
        "decision" : "NO",
        "explanation" : "node does not match index include filters [foo:\"bar\"]"
      } ]
    },
    "Qc6VL8c5RWaw1qXZ0Rg57g" : {
      "node_name" : "I8hydUG",
      "node_attributes" : {
        "bar" : "baz",
        "foo" : "bar"
      },
      "store" : {
        "shard_copy" : "AVAILABLE"
      },
      "final_decision" : "ALREADY_ASSIGNED",        
      "final_explanation" : "the shard is already assigned to this node",
      "weight" : 0.0,
      "decisions" : [ {
        "decider" : "same_shard",
        "decision" : "NO",
        "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists"
      } ]
    },
    "PzdyMZGXQdGhqTJHF_hGgA" : {
      "node_name" : "H5dfFeA",
      "node_attributes" : { },
      "store" : {
        "shard_copy" : "NONE"
      },
      "final_decision" : "NO",
      "final_explanation" : "the shard cannot be assigned because one or more allocation decider returns a 'NO' decision",
      "weight" : 3.6999998,
      "decisions" : [ {
        "decider" : "filter",
        "decision" : "NO",
        "explanation" : "node does not match index include filters [foo:\"bar\"]"
      } ]
    }
  }
}

Node the shard is currently assigned to

The decision is "ALREADY_ASSIGNED" because the shard is currently assigned to this node

You can also have Elasticsearch explain the allocation of the first unassigned shard it finds by sending an empty body, such as:

$ curl -XGET 'http://localhost:9200/_cluster/allocation/explain'

If you would like to include all decisions that were factored into the final decision, the include_yes_decisions parameter will return all decisions:

$ curl -XGET 'http://localhost:9200/_cluster/allocation/explain?include_yes_decisions=true'

Additionally, you can return information gathered by the cluster info service about disk usage and shard sizes by setting the include_disk_info parameter to true:

$ curl -XGET 'http://localhost:9200/_cluster/allocation/explain?include_disk_info=true'
« Nodes hot_threads Query DSL »
Was this helpful?
Feedback