cat allocation API

cat allocation API

cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.

Provides a snapshot of the number of shards allocated to each data node and their disk space.

Request

GET /_cat/allocation/<node_id>

GET /_cat/allocation

Prerequisites

  • If the Elasticsearch security features are enabled, you must have the monitor or manage cluster privilege to use this API.

Path parameters

<node_id>

(Optional, string) Comma-separated list of node IDs or names used to limit returned information.

Query parameters

bytes

(Optional, byte size units) Unit used to display byte values.

format

(Optional, string) Short version of the HTTP accept header. Valid values include JSON, YAML, etc.

local

(Optional, Boolean) If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.

master_timeout

(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.

h

(Optional, string) Comma-separated list of column names to display.

help

(Optional, Boolean) If true, the response includes help information. Defaults to false.

s

(Optional, string) Comma-separated list of column names or column aliases used to sort the response.

v

(Optional, Boolean) If true, the response includes column headings. Defaults to false.

Response body

shards

Number of primary and replica shards assigned to the node.

disk.indices

Disk space used by the node’s shards. Does not include disk space for the translog or unassigned shards.

This metric double-counts disk space for hard-linked files, such as those created when shrinking, splitting, or cloning an index.

disk.used

Total disk space in use. Elasticsearch retrieves this metric from the node’s operating system (OS). The metric includes disk space for:

  • Elasticsearch, including the translog and unassigned shards
  • The node’s OS
  • Any other applications or files on the node

Unlike disk.indices, this metric does not double-count disk space for hard-linked files.

disk.avail

Free disk space available to Elasticsearch. Elasticsearch retrieves this metric from the node’s OS. Disk-based shard allocation uses this metric to assign shards to nodes based on available disk space.

disk.total

Total disk space for the node, including in-use and available space.

disk.percent

Total percentage of disk space in use. Calculated as disk.used / disk.total.

host

Network host for the node. Set using network.host.

ip

IP address and port for the node.

node

Name for the node. Set using node.name.

Examples

  1. GET /_cat/allocation?v=true

The API returns the following response:

  1. shards disk.indices disk.used disk.avail disk.total disk.percent host      ip        node
  2.      1         260b    47.3gb     43.4gb    100.7gb           46 127.0.0.1 127.0.0.1 CSUXak2

This response shows a single shard is allocated to the one node available.