New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Delete desired nodes API Reset desired balance API »
Elastic Docs ›Elasticsearch Guide [8.15] ›REST APIs ›Cluster APIs

Get desired balance API

edit
IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Get desired balance API

edit

This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.

Exposes:

  • the 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

Request

edit
resp = client.perform_request(
    "GET",
    "/_internal/desired_balance",
)
print(resp)
const response = await client.transport.request({
  method: "GET",
  path: "/_internal/desired_balance",
});
console.log(response);
GET /_internal/desired_balance
Copy as curlTry in Elastic 

The API returns the following 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" : []
  }
}
« Delete desired nodes API Reset desired balance API »

On this page

Was this helpful?
Feedback