cat APIs

aliases shows information about currently configured aliases to indices including filter and routing infos.

Might respond with:

The output shows that alias2 has configured a filter, and specific routing configurations in alias3 and alias4.

If you only want to get information about specific aliases, you can specify the aliases in comma-delimited format as a URL parameter, e.g., /_cat/aliases/alias1,alias2.

allocation provides a snapshot of how many shards are allocated to each data node and how much disk space they are using.

Might respond with:

Here we can see that all 5 shards have been allocated to the single node available.

count provides quick access to the document count of the entire cluster, or individual indices.

Looks like:

Or for a single index:

fielddata shows how much heap memory is currently being used by fielddata on every data node in the cluster.

Looks like:

Fields can be specified either as a query parameter, or in the URL path:

Which looks like:

And it accepts a comma delimited list:

Which produces the same output as the first snippet:

The output shows the individual fielddata for the body and soul fields, one row per field per node.

health is a terse, one-line representation of the same information from /_cluster/health.

It has one option ts to disable the timestamping:

which looks like:

A common use of this command is to verify the health is consistent across nodes:

A less obvious use is to track recovery of a large cluster over time. With enough shards, starting a cluster, or even recovering after losing a node, can take time (depending on your network & disk). A way to track its progress is by using this command in a delayed loop:

In this scenario, we can tell that recovery took roughly four minutes. If this were going on for hours, we would be able to watch the UNASSIGNED shards drop precipitously. If that number remained static, we would have an idea that there is a problem.

You typically are using the health command when a cluster is malfunctioning. During this period, it’s extremely important to correlate activities across log files, alerting systems, etc.

There are two outputs. The HH:MM:SS output is simply for quick human consumption. The epoch time retains more information, including date, and is machine sortable if your recovery spans days.

The indices command provides a cross-section of each index. This information spans nodes. For example:

Might respond with:

We can tell quickly how many shards make up an index, the number of docs, deleted docs, primary store size, and total store size (all shards including replicas). All these exposed metrics come directly from Lucene APIs.

Notes:

The index stats by default will show them for all of an index’s shards, including replicas. A pri flag can be supplied to enable the view of relevant stats in the context of only the primaries.

Which indices are yellow?

Which looks like:

Which index has the largest number of documents?

Which looks like:

How many merge operations have the shards for the twitter completed?

Might look like:

How much memory is used per index?

Might look like:

master doesn’t have any extra options. It simply displays the master’s node ID, bound IP address, and node name. For example:

might respond:

This information is also available via the nodes command, but this is slightly shorter when all you want to do, for example, is verify all nodes agree on the master:

The nodeattrs command shows custom node attributes. For example:

Could look like:

The first few columns (node, host, ip) give you basic info per node and the attr and value columns give you the custom node attributes, one per line.

Below is an exhaustive list of the existing headers that can be passed to nodeattrs?h= to retrieve the relevant details in ordered columns. If no headers are specified, then those marked to Appear by Default will appear. If any header is specified, then the defaults are not used.

Aliases can be used in place of the full header name for brevity. Columns appear in the order that they are listed below unless a different order is specified (e.g., h=attr,value versus h=value,attr).

When specifying headers, the headers are not placed in the output by default. To have the headers appear in the output, use verbose mode (v). The header name will match the supplied value (e.g., pid versus p). For example:

Might look like:

The nodes command shows the cluster topology. For example

Might look like:

The first few columns (ip, heap.percent, ram.percent, cpu, load_*) tell you where your nodes live and give a quick picture of performance stats.

The last (node.role, master, and name) columns provide ancillary information that can often be useful when looking at the cluster as a whole, particularly large ones. How many master-eligible nodes do I have?

The nodes API accepts an additional URL parameter full_id accepting true or false. The purpose of this parameter is to format the ID field (if requested with id or nodeId) in its full length or in abbreviated form (the default).

Below is an exhaustive list of the existing headers that can be passed to nodes?h= to retrieve the relevant details in ordered columns. If no headers are specified, then those marked to Appear by Default will appear. If any header is specified, then the defaults are not used.

Aliases can be used in place of the full header name for brevity. Columns appear in the order that they are listed below unless a different order is specified (e.g., h=pid,id versus h=id,pid).

When specifying headers, the headers are not placed in the output by default. To have the headers appear in the output, use verbose mode (v). The header name will match the supplied value (e.g., pid versus p). For example:

Might look like:

pending_tasks provides the same information as the /_cluster/pending_tasks API in a convenient tabular format. For example:

Might look like:

The plugins command provides a view per node of running plugins. This information spans nodes.

Might look like:

We can tell quickly how many plugins per node we have and which versions.

The recovery command is a view of index shard recoveries, both on-going and previously completed. It is a more compact view of the JSON recovery API.

A recovery event occurs anytime an index shard moves to a different node in the cluster. This can happen during a snapshot recovery, a change in replication level, node failure, or on node startup. This last type is called a local store recovery and is the normal way for shards to be loaded from disk when a node starts up.

As an example, here is what the recovery state of a cluster may look like when there are no shards in transit from one node to another:

The response of this request will be something like:

In the above case, the source and target nodes are the same because the recovery type was store, i.e. they were read from local storage on node start.

Now let’s see what a live recovery looks like. By increasing the replica count of our index and bringing another node online to host the replicas, we can see what a live shard recovery looks like.

This will return a line like:

We can see in the above listing that our thw twitter shard was recovered from another node. Notice that the recovery type is shown as peer. The files and bytes copied are real-time measurements.

Finally, let’s see what a snapshot recovery looks like. Assuming I have previously made a backup of my index, I can restore it using the snapshot and restore API.

This will show a recovery of type snapshot in the response

The repositories command shows the snapshot repositories registered in the cluster. For example:

might looks like:

We can quickly see which repositories are registered and their type.

The thread_pool command shows cluster wide thread pool statistics per node. By default the active, queue and rejected statistics are returned for all thread pools.

Which looks like:

The first column is the node name

The second column is the thread pool name

The next three columns show the active, queue, and rejected statistics for each thread pool

The cat thread pool API accepts a thread_pool_patterns URL parameter for specifying a comma-separated list of regular expressions to match thread pool names.

which looks like:

Here the host columns and the active, rejected and completed suggest thread pool statistics are displayed.

All built-in thread pools and custom thread pools are available.

For each thread pool, you can load details about it by using the field names in the table below.

In addition to details about each thread pool, it is also convenient to get an understanding of where those thread pools reside. As such, you can request other details like the ip of the responding node(s).

The shards command is the detailed view of what nodes contain which shards. It will tell you if it’s a primary or replica, the number of docs, the bytes it takes on disk, and the node where it’s located.

Here we see a single index, with one primary shard and no replicas:

This will return

If you have many shards, you may wish to limit which indices show up in the output. You can always do this with grep, but you can save some bandwidth by supplying an index pattern to the end.

Which will return the following

Let’s say you’ve checked your health and you see relocating shards. Where are they from and where are they going?

A relocating shard will be shown as follows

Before a shard can be used, it goes through an INITIALIZING state. shards can show you which ones.

You can get the initializing state in the response like this

If a shard cannot be assigned, for example you’ve overallocated the number of replicas for the number of nodes in the cluster, the shard will remain UNASSIGNED with the reason code ALLOCATION_FAILED.

You can use the shards API to find out that reason.

The reason for an unassigned shard will be listed as the last field

These are the possible reasons for a shard to be in a unassigned state:

The segments command provides low level information about the segments in the shards of an index. It provides information similar to the _segments endpoint. For example:

might look like:

The output shows information about index names and shard numbers in the first two columns.

If you only want to get information about segments in one particular index, you can add the index name in the URL, for example /_cat/segments/test. Also, several indexes can be queried like /_cat/segments/test,test1

The following columns provide additional monitoring information:

The snapshots command shows all snapshots that belong to a specific repository. To find a list of available repositories to query, the command /_cat/repositories can be used. Querying the snapshots of a repository named repo1 then looks as follows.

Which looks like:

Each snapshot contains information about when it was started and stopped. Start and stop timestamps are available in two formats. The HH:MM:SS output is simply for quick human consumption. The epoch time retains more information, including date, and is machine sortable if the snapshot process spans days.

The templates command provides information about existing templates.

which looks like

The output shows that there are three existing templates, with template2 having a version value.

The endpoint also supports giving a template name or pattern in the url to filter the results, for example /_cat/templates/template* or /_cat/templates/template0.