elasticsearch/docs/reference/cluster/get-desired-balance.asciidoc

[[get-desired-balance]]
=== Get desired balance API
++++
<titleabbrev>Get desired balance</titleabbrev>
++++

NOTE: {cloud-only}

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-cluster[Cluster APIs].
--

Exposes:

* the <<shards-rebalancing-heuristics,desired balance>> computation and reconciliation stats
* balancing stats such as distribution of shards, disk and ingest forecasts
  across nodes and data tiers (based on the current cluster state)
* routing table with each shard current and desired location
* cluster info with nodes disk usages

[[get-desired-balance-request]]
==== {api-request-title}

[source,console]
--------------------------------------------------
GET /_internal/desired_balance
--------------------------------------------------
// TEST[skip:Can't reliably test desired balance]

The API returns the following result:

[source,console-result]
--------------------------------------------------
{
  "stats": {
    "computation_active": false,
    "computation_submitted": 5,
    "computation_executed": 5,
    "computation_converged": 5,
    "computation_iterations": 4,
    "computation_converged_index": 4,
    "computation_time_in_millis": 0,
    "reconciliation_time_in_millis": 0
  },
  "cluster_balance_stats" : {
    "shard_count": 37,
    "undesired_shard_allocation_count": 0,
    "tiers": {
      "data_hot" : {
        "shard_count" : {
          "total" : 7.0,
          "min" : 2.0,
          "max" : 3.0,
          "average" : 2.3333333333333335,
          "std_dev" : 0.4714045207910317
        },
        "undesired_shard_allocation_count" : {
          "total" : 0.0,
          "min" : 0.0,
          "max" : 0.0,
          "average" : 0.0,
          "std_dev" : 0.0
        },
        "forecast_write_load" : {
          "total" : 21.0,
          "min" : 6.0,
          "max" : 8.5,
          "average" : 7.0,
          "std_dev" : 1.0801234497346435
        },
        "forecast_disk_usage" : {
          "total" : 36.0,
          "min" : 10.0,
          "max" : 16.0,
          "average" : 12.0,
          "std_dev" : 2.8284271247461903
        },
        "actual_disk_usage" : {
          "total" : 36.0,
          "min" : 10.0,
          "max" : 16.0,
          "average" : 12.0,
          "std_dev" : 2.8284271247461903
        }
      },
      "data_warm" : {
        "shard_count" : {
          "total" : 3.0,
          "min" : 1.0,
          "max" : 1.0,
          "average" : 1.0,
          "std_dev" : 0.0
        },
        "undesired_shard_allocation_count" : {
          "total" : 0.0,
          "min" : 0.0,
          "max" : 0.0,
          "average" : 0.0,
          "std_dev" : 0.0
        },
        "forecast_write_load" : {
          "total" : 0.0,
          "min" : 0.0,
          "max" : 0.0,
          "average" : 0.0,
          "std_dev" : 0.0
        },
        "forecast_disk_usage" : {
          "total" : 42.0,
          "min" : 12.0,
          "max" : 18.0,
          "average" : 14.0,
          "std_dev" : 2.8284271247461903
        },
        "actual_disk_usage" : {
          "total" : 42.0,
          "min" : 12.0,
          "max" : 18.0,
          "average" : 14.0,
          "std_dev" : 2.8284271247461903
        }
      }
    },
    "nodes": {
      "node-1": {
        "node_id": "UPYt8VwWTt-IADAEbqpLxA",
        "roles": ["data_content"],
        "shard_count": 10,
        "undesired_shard_allocation_count": 0,
        "forecast_write_load": 8.5,
        "forecast_disk_usage_bytes": 498435,
        "actual_disk_usage_bytes": 498435
      },
      "node-2": {
        "node_id": "bgC66tboTIeFQ0VgRGI4Gg",
        "roles": ["data_content"],
        "shard_count": 15,
        "undesired_shard_allocation_count": 0,
        "forecast_write_load": 3.25,
        "forecast_disk_usage_bytes": 384935,
        "actual_disk_usage_bytes": 384935
      },
      "node-3": {
        "node_id": "2x1VTuSOQdeguXPdN73yRw",
        "roles": ["data_content"],
        "shard_count": 12,
        "undesired_shard_allocation_count": 0,
        "forecast_write_load": 6.0,
        "forecast_disk_usage_bytes": 648766,
        "actual_disk_usage_bytes": 648766
      }
    }
  },
  "routing_table": {
    "test": {
      "0": {
        "current": [
          {
            "state": "STARTED",
            "primary": true,
            "node": "UPYt8VwWTt-IADAEbqpLxA",
            "node_is_desired": true,
            "relocating_node": null,
            "relocating_node_is_desired": null,
            "shard_id": 0,
            "index": "test",
            "forecast_write_load": 8.0,
            "forecast_shard_size_in_bytes": 1024,
            "tier_preference": ["data_content"]
          }
        ],
        "desired": {
          "node_ids": [
            "UPYt8VwWTt-IADAEbqpLxA"
          ],
          "total": 1,
          "unassigned": 0,
          "ignored": 0
        }
      },
      "1": {
        "current": [
          {
            "state": "STARTED",
            "primary": true,
            "node": "2x1VTuSOQdeguXPdN73yRw",
            "node_is_desired": true,
            "relocating_node": null,
            "relocating_node_is_desired": false,
            "shard_id": 1,
            "index": "test",
            "forecast_write_load": null,
            "forecast_shard_size_in_bytes": null,
            "tier_preference": ["data_content"]
          }
        ],
        "desired": {
          "node_ids": [
            "2x1VTuSOQdeguXPdN73yRw"
          ],
          "total": 1,
          "unassigned": 0,
          "ignored": 0
        }
      }
    }
  },
  "cluster_info" : {
      "nodes" : {
        "UPYt8VwWTt-IADAEbqpLxA" : {
          "node_name" : "node-1",
          "least_available" : {
            "path" : "/data",
            "total_bytes" : 1440713945,
            "used_bytes" : 1222486407,
            "free_bytes" : 218227538,
            "free_disk_percent" : 15.1,
            "used_disk_percent" : 84.9
          },
          "most_available" : {
            "path" : "/data",
            "total_bytes" : 1440713945,
            "used_bytes" : 1222486407,
            "free_bytes" : 218227538,
            "free_disk_percent" : 15.1,
            "used_disk_percent" : 84.9
          }
        }
      },
      "shard_sizes" : {
        "[test][0][p]_bytes" : 1720826288,
        "[test][1][p]_bytes" : 1720826288
      },
      "shard_data_set_sizes" : {
        "[test][0][p]_bytes" : 1720826288,
        "[test][1][p]_bytes" : 1720826288
      },
      "shard_paths" : {
        "NodeAndShard[nodeId=UPYt8VwWTt-IADAEbqpLxA, shardId=[test][0]]" : "/data",
        "NodeAndShard[nodeId=bgC66tboTIeFQ0VgRGI4Gg, shardId=[test][0]]" : "/data"
      },
      "reserved_sizes" : []
  }
}
--------------------------------------------------
// TEST[skip:Can't reliably test desired balance]