mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
612ce0f996
* (Doc+) Cross-link CAT APIs to parent object --------- Co-authored-by: Lisa Cawley <lcawley@elastic.co> Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com>
135 lines
4.2 KiB
Text
135 lines
4.2 KiB
Text
[[cat-allocation]]
|
|
=== cat allocation API
|
|
++++
|
|
<titleabbrev>cat allocation</titleabbrev>
|
|
++++
|
|
|
|
[IMPORTANT]
|
|
====
|
|
cat APIs are only intended for human consumption using the command line or {kib}
|
|
console. They are _not_ intended for use by applications. For application
|
|
consumption, use the <<cluster-nodes-stats,node stats API>>.
|
|
====
|
|
|
|
Provides a snapshot of the number of shards <<shard-allocation-relocation-recovery,allocated>> to each data node
|
|
and their disk space.
|
|
|
|
|
|
[[cat-allocation-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_cat/allocation/<node_id>`
|
|
|
|
`GET /_cat/allocation`
|
|
|
|
[[cat-allocation-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have the `monitor` or
|
|
`manage` <<privileges-list-cluster,cluster privilege>> to use this API.
|
|
|
|
[[cat-allocation-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=node-id]
|
|
|
|
[[cat-allocation-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=bytes]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=http-format]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=local]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=cat-h]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=help]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=cat-s]
|
|
|
|
include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=cat-v]
|
|
|
|
[[cat-allocation-api-response-body]]
|
|
==== {api-response-body-title}
|
|
|
|
`shards`::
|
|
Number of primary and replica shards assigned to the node.
|
|
|
|
`shards.undesired`::
|
|
Amount of shards that are scheduled to be moved elsewhere in the cluster
|
|
or -1 other than desired balance allocator is used
|
|
|
|
`write_load.forecast`::
|
|
Sum of index write load forecasts
|
|
|
|
`disk.indices.forecast`::
|
|
Sum of shard size forecasts
|
|
|
|
`disk.indices`::
|
|
Disk space used by the node's shards. Does not include disk space for the
|
|
<<index-modules-translog,translog>> or unassigned shards.
|
|
+
|
|
IMPORTANT: This metric double-counts disk space for hard-linked files, such as
|
|
those created when <<indices-shrink-index,shrinking>>,
|
|
<<indices-split-index,splitting>>, or <<indices-clone-index,cloning>> an index.
|
|
|
|
`disk.used`::
|
|
+
|
|
--
|
|
Total disk space in use. {es} retrieves this metric from the node's operating
|
|
system (OS). The metric includes disk space for:
|
|
|
|
- {es}, including the <<index-modules-translog,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 {es}. {es} retrieves this metric from the node's
|
|
OS. <<disk-based-shard-allocation,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,`network.host`>>.
|
|
|
|
`ip`::
|
|
IP address and port for the node.
|
|
|
|
`node`::
|
|
Name for the node. Set using <<node-name,`node.name`>>.
|
|
|
|
`node.role`, `r`, `role`, `nodeRole`::
|
|
Node roles
|
|
|
|
[[cat-allocation-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
[source,console,id=cat-allocation-example]
|
|
--------------------------------------------------
|
|
GET /_cat/allocation?v=true
|
|
--------------------------------------------------
|
|
// TEST[s/^/PUT test\n{"settings": {"number_of_replicas": 0}}\n/]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,txt]
|
|
--------------------------------------------------
|
|
shards shards.undesired write_load.forecast disk.indices.forecast disk.indices disk.used disk.avail disk.total disk.percent host ip node node.role
|
|
1 0 0.0 260b 260b 47.3gb 43.4gb 100.7gb 46 127.0.0.1 127.0.0.1 CSUXak2 himrst
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/\d+(\.\d+)?[tgmk]?b/\\d+(\\.\\d+)?[tgmk]?b/ s/46/\\d+/]
|
|
// TESTRESPONSE[s/CSUXak2 himrst/.+/ non_json]
|
|
|
|
This response shows a single shard is allocated to the one node available.
|