Служебные API: _cat, здоровье кластера и настройки

После того как вы создали индекс, загрузили документы и настроили маппинг, рано или поздно возникает вопрос: а что вообще происходит внутри кластера? Сколько индексов, каких размеров, на каких нодах какие шарды? Для быстрого осмотра в ES есть два семейства API — _cat (компактный текстовый вывод) и стандартные JSON-эндпоинты вроде _cluster/health и _settings.

_cat API: быстрый осмотр в одну строку

_cat расшифровывается как «compact and aligned text» — набор эндпоинтов, которые возвращают текстовую таблицу вместо JSON. Удобно читать глазами в Kibana Dev Tools или в терминале; для скриптов лучше подходят обычные JSON-эндпоинты.

Основные параметры, которые работают со всеми _cat-эндпоинтами:

?v — verbose, добавить заголовки столбцов (почти всегда нужен)
?s=<col> — сортировка по столбцу, например ?s=store.size:desc
?h=<col1>,<col2> — выбрать только нужные столбцы
?format=json — тот же ответ, но в JSON (для скриптов)

Полный список доступных _cat-эндпоинтов:

GET /_cat

flowchart TD Q["❓ Что нужно узнать?"] --> A["Список индексов и их размер"] Q --> B["Здоровье кластера целиком"] Q --> C["Где живут шарды"] Q --> D["Какие ноды работают"] Q --> E["Настройки конкретного индекса"] A --> API1["GET /_cat/indices?v"] B --> API2["GET /_cluster/health"] B --> API3["GET /_cat/health?v"] C --> API4["GET /_cat/shards?v"] D --> API5["GET /_cat/nodes?v"] E --> API6["GET /<index>/_settings"]

flowchart TD
    Q["❓ Что нужно узнать?"] --> A["Список индексов и их размер"]
    Q --> B["Здоровье кластера целиком"]
    Q --> C["Где живут шарды"]
    Q --> D["Какие ноды работают"]
    Q --> E["Настройки конкретного индекса"]

    A --> API1["GET /_cat/indices?v"]
    B --> API2["GET /_cluster/health"]
    B --> API3["GET /_cat/health?v"]
    C --> API4["GET /_cat/shards?v"]
    D --> API5["GET /_cat/nodes?v"]
    E --> API6["GET /&lt;index&gt;/_settings"]

Карта диагностических API: какой вопрос — какой эндпоинт

_cat/indices: смотрим на все индексы

Самый часто используемый _cat-эндпоинт:

GET /_cat/indices?v

Пример вывода:

health status index   uuid                   pri rep docs.count docs.deleted store.size pri.store.size
green  open   catalog abc123nFgR4B9Kh2Td1wA   1   1       1500            0      2.3mb          1.1mb
yellow open   logs    def456kLmP7Xq3Vc8nB2C   1   1          0            0       226b           226b

Ключевые столбцы:

Столбец	Что означает
`health`	Статус индекса: green / yellow / red
`status`	open (работает) или close (заморожен)
`pri`	Число primary-шардов
`rep`	Число реплик
`docs.count`	Количество документов
`store.size`	Общий размер (primary + replicas)
`pri.store.size`	Размер только primary-шардов

Если нужен только размер индексов по убыванию:

GET /_cat/indices?v&s=store.size:desc&h=index,store.size,docs.count

Проверь себя

Вы создали индекс `products` с параметром `number_of_replicas: 1` на кластере из одной ноды. Что покажет `_cat/indices?v` в столбце `health` для этого индекса — и почему?

_cat/nodes: быстрый осмотр нод

GET /_cat/nodes?v

Пример вывода:

ip        heap.percent ram.percent cpu load_1m node.role   master name
127.0.0.1           31          91   2    0.08 cdfhimrstw  *      node-1

Что важно:

heap.percent — заполненность heap JVM. Если постоянно выше 75–80%, пора думать об увеличении памяти или оптимизации.
master — звёздочка (*) означает, что эта нода сейчас является мастером кластера.
node.role — набор ролей ноды: m = master, d = data, i = ingest и т. д.

Чтобы добавить версию ES в вывод:

GET /_cat/nodes?v&h=ip,heap.percent,ram.percent,cpu,name,version

_cat/shards: где живут шарды

Самый «диагностический» из _cat-эндпоинтов — особенно когда что-то идёт не так:

GET /_cat/shards?v

Пример вывода:

index   shard prirep state      docs   store ip        node
catalog 0     p      STARTED    1500   1.1mb 127.0.0.1 node-1
catalog 0     r      UNASSIGNED
logs    0     p      STARTED       0    226b 127.0.0.1 node-1
logs    0     r      UNASSIGNED

Столбец prirep: p — primary-шард, r — replica. Столбец state показывает текущее состояние шарда:

Состояние	Что означает
`STARTED`	Шард работает нормально
`UNASSIGNED`	Шард не назначен ни на одну ноду
`INITIALIZING`	Шард инициализируется (запуск или восстановление)
`RELOCATING`	Шард переезжает на другую ноду при балансировке

Почему реплика UNASSIGNED на одной ноде — это нормально: ES принципиально не размещает primary и реплику одного шарда на одном сервере. На кластере из одной ноды реплике просто некуда идти, поэтому индекс уходит в yellow. Это не ошибка — ожидаемое поведение для dev-среды.

Если шард завис в UNASSIGNED и нужно понять причину:

GET /_cluster/allocation/explain

Ответ объяснит на человеческом языке, почему шард не может быть назначен: нет свободных нод, не хватает места на диске, несовместимые атрибуты — причину укажут явно.

Проверь себя

В выводе `_cat/shards?v` шард имеет `prirep=r` и `state=UNASSIGNED`. О чём это говорит и нужно ли паниковать, если вы работаете на dev-кластере из одной ноды?

_cluster/health: здоровье кластера в JSON

Для программной проверки — например, из CI/CD-скрипта или health-check — используйте _cluster/health:

GET /_cluster/health

Ответ:

{
  "cluster_name": "my-cluster",
  "status": "yellow",
  "timed_out": false,
  "number_of_nodes": 1,
  "number_of_data_nodes": 1,
  "active_primary_shards": 5,
  "active_shards": 5,
  "relocating_shards": 0,
  "initializing_shards": 0,
  "unassigned_shards": 5,
  "active_shards_percent_as_number": 50.0
}

Поле status — агрегированный статус по всем индексам кластера:

Статус	Ситуация	Что делать
green	Все primary и replica-шарды назначены и работают	Всё хорошо
yellow	Primary работают, часть реплик не назначена	Данные доступны, но нет избыточности. Нормально для dev из одной ноды
red	Один или несколько primary-шардов не назначены	Часть данных недоступна — нужна срочная диагностика

Проверить здоровье конкретного индекса:

GET /_cluster/health/catalog

Дождаться, пока кластер станет green (с таймаутом — удобно в автоматизации деплоя):

GET /_cluster/health?wait_for_status=green&timeout=30s

Запрос вернёт ответ только когда кластер достигнет нужного статуса или истечёт таймаут.

Проверь себя

Вы запросили `GET /_cluster/health` и получили `"status": "red"`. Какой следующий шаг в диагностике и что именно вы ищете?

Просмотр и изменение настроек индекса

Посмотреть, с какими настройками создан индекс:

GET /catalog/_settings

Ответ:

{
  "catalog": {
    "settings": {
      "index": {
        "number_of_shards": "1",
        "number_of_replicas": "1",
        "provided_name": "catalog",
        "creation_date": "1705312800000",
        "uuid": "abc123nFgR4B9Kh2Td1wA",
        "version": { "created": "8140099" }
      }
    }
  }
}

Чтобы увидеть сразу всё — маппинг и настройки вместе:

GET /catalog

Некоторые настройки меняются после создания индекса — это динамические настройки. Например, убрать реплики на dev-кластере из одной ноды, чтобы индекс стал green:

PUT /catalog/_settings
{
  "number_of_replicas": 0
}

Число primary-шардов — статическая настройка: её нельзя изменить после создания индекса. Как и тип поля в маппинге, это требует _reindex в новый индекс. Об этом подробнее — в статье Маппинг: явный, динамический и шаблоны индексов.

Статистику индекса (число документов, размер в байтах, операции ввода-вывода):

GET /catalog/_stats

Диагностический рецепт: в каком порядке смотреть

Когда что-то идёт не так или нужно быстро разобраться в состоянии кластера, вот удобная последовательность:

1. GET /_cluster/health — первый взгляд: green / yellow / red.

2. GET /_cat/indices?v — найти индексы с проблемным статусом.

3. GET /_cat/shards?v&index=<проблемный_индекс> — увидеть UNASSIGNED-шарды.

4. GET /_cluster/allocation/explain — понять, почему шард не назначен.

5. GET /_cat/nodes?v — проверить, все ли ноды живы.

Эта последовательность закрывает большинство диагностических сценариев. Для более глубокого анализа в продакшне — _cluster/stats, _nodes/stats и инструменты Kibana Stack Monitoring, о которых подробнее в статье Мониторинг и здоровье кластера.