9.5. Using the _cat API

Using the curl commands in sections 9.1, 9.2, and 9.3 is a great way to see what’s going on with your cluster, but sometimes it’s helpful to see the output in a more readable format (if you don’t believe us, try curling the http://localhost:9200/_cluster/state URL on a large cluster and see how much information comes back!). This is where the handy _cat API comes in. The _cat API provides helpful diagnostic and debugging tools that print data in a more human-readable way, rather than trying to page through a giant JSON response. The following listing shows two of its commands for the equivalent health and node listing cURL statements we already covered.

Listing 9.5. Using the _cat API to find cluster health and nodes

In addition to the health and nodes endpoints, the _cat API has many other features, all of which are useful for debugging different things your cluster may be undergoing. You can see the full list of supported _cat APIs by running curl 'localhost:9200/_cat'.

_cat APIs

At the time of this writing, here are some of the most useful _cat APIs and what they do. Be sure to check out the others!

allocation—Shows the number of shards allocated to each node count—Counts the number of documents in the entire cluster or index health—Displays the health of the cluster indices—Displays information about existing indices master—Shows what node is currently elected master nodes—Shows various information about all nodes in the cluster recovery—Shows the status of ongoing shard recoveries in the cluster shards—Displays count, size, and names of shards in the cluster plugins—Displays information about installed plugins

While we’re looking at adding nodes to a cluster, why not look at how the shards are distributed across each node using the _cat API in the following code listing. This is a much easier way to see how shards are allocated in your cluster as opposed to the curl command in listing 9.2.

Listing 9.6. Using the _cat API to show shard allocation

Using the _cat/allocation and _cat/shards APIs is also a great way to determine when a node can be safely shut down after performing the decommission we discussed in section 9.3.1. Compare the output of the curl command from listing 9.2 to the output from the commands in listing 9.6; it’s much easier to read the _cat API output!

Now that you can see where the shards are located in your cluster, we should spend some more time discussing how you should plan your Elasticsearch cluster to make the most of your nodes and data.