Устранение неполадок: проверка и интерпретация состояния кластера Elasticsearch

Состояние кластера Elasticsearch — одна из тех проверок, которые выглядят просто, пока не сработает пейджер. API возвращает цвет, но цвет — это только отправная точка. Зеленый кластер может быть медленным. Желтый кластер может быть вполне пригоден для использования в короткое окно технического обслуживания. Красный кластер может означать, что один небольшой тестовый индекс недоступен, или что поиск для клиентов теряет реальные данные.

Когда я проверяю состояние кластера Elasticsearch, я стараюсь не переходить сразу от red к опасным командам восстановления. Сначала я хочу ответить на три вопроса: назначены ли первичные шарды, назначены ли реплики, и пытается ли кластер в настоящее время восстановиться самостоятельно? Команды ниже — это те, которые я использую, чтобы перейти от общего цвета состояния к конкретной причине.

Начните с API состояния

Для быстрого просмотра в терминале подойдет _cat/health:

curl -s "http://localhost:9200/_cat/health?v"

Типичный ответ выглядит так:

epoch      timestamp cluster     status node.total node.data shards pri relo init unassign pending_tasks
1762219800 12:10:00  logs-prod   yellow          3         3    124  62    0    0        2             0

Поля, на которые я смотрю в первую очередь: status, node.total, node.data, relo, init, unassign и pending_tasks. Желтый статус с init или relo больше нуля может означать просто восстановление кластера после перезапуска. Желтый статус с неназначенными шардами и отсутствием движения обычно требует расследования.

Для автоматизации используйте JSON API вместо разбора вывода _cat:

curl -s "http://localhost:9200/_cluster/health?pretty"

Этот ответ включает такие поля, как active_primary_shards, active_shards, relocating_shards, initializing_shards, unassigned_shards и delayed_unassigned_shards. Эти имена проще использовать в скриптах и проверках мониторинга.

Что на самом деле означают зеленый, желтый и красный цвета

Зеленый означает, что каждый первичный шард и каждый настроенный шард-реплика назначены. Это не означает, что запросы выполняются быстро, диск здоров или маппинги хорошо спроектированы. Это означает только то, что Elasticsearch разместил шарды, которые должен был разместить.

Желтый означает, что все первичные шарды назначены, но по крайней мере один шард-реплика не назначен. Ваши данные все еще должны быть доступны для поиска, так как первичные шарды доступны. Риск заключается в избыточности. Если узел, содержащий первичный шард, выйдет из строя, пока его реплика все еще не назначена, этот индекс может стать красным.

Красный означает, что по крайней мере один первичный шард не назначен. Поиск по затронутым индексам может завершиться ошибкой или вернуть частичные результаты, а запись в эти шарды не может выполняться нормально. Красный цвет требует немедленного внимания, но правильное действие зависит от того, почему первичный шард не назначен.

Распространенный пример для небольшого кластера — это одноузловой кластер разработки с одной настроенной репликой. Он останется желтым, потому что Elasticsearch не поместит реплику на тот же узел, что и ее первичный шард. Это не загадка и не повод принудительно назначать шарды. Либо добавьте еще один узел данных, либо установите количество реплик равным нулю для этого индекса:

curl -X PUT "http://localhost:9200/my-index/_settings"   -H 'Content-Type: application/json'   -d '{"index":{"number_of_replicas":0}}'

Не используйте эту настройку небрежно в производственной среде. Она удаляет избыточность для этого индекса.

Найдите точные неназначенные шарды

После цвета состояния выведите список шардов:

curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason" | sort

Ищите UNASSIGNED. Столбец prirep сообщает вам, является ли шард первичным (p) или репликой (r). Это различие важнее самого цвета. Несколько неназначенных реплик обычно означают снижение отказоустойчивости. Один неназначенный первичный шард означает, что по крайней мере часть индекса недоступна.

Если вы видите много неназначенных шардов после запланированного перезапуска узла, также проверьте отложенное выделение:

curl -s "http://localhost:9200/_cluster/health?pretty" | grep delayed_unassigned_shards

Elasticsearch может ждать перед перераспределением реплик после ухода узла, потому что узел может быстро вернуться. Такое поведение позволяет избежать ненужной сетевой и дисковой активности во время последовательных перезапусков.

Спросите Elasticsearch, почему выделение не удалось

API объяснения выделения — лучший следующий шаг. Вы можете запросить любой неназначенный шард:

curl -X GET "http://localhost:9200/_cluster/allocation/explain?pretty"   -H 'Content-Type: application/json'   -d '{}'

Или запросить конкретный шард:

curl -X GET "http://localhost:9200/_cluster/allocation/explain?pretty"   -H 'Content-Type: application/json'   -d '{
    "index": "logs-2026.05.24",
    "shard": 0,
    "primary": false
  }'

Прочитайте unassigned_info, can_allocate и node_allocation_decisions. Полезная часть обычно написана простым языком: превышен порог заполнения диска, выделение отключено, нет соответствующего атрибута узла, слишком много шардов на узле или реплика не может быть размещена, потому что существует только один узел.

Если в объяснении указано allocation_delayed, подождите, только если ожидается, что отсутствующий узел скоро вернется. Если в объяснении сказано, что ни один узел не удовлетворяет правилам выделения, ожидание не поможет.

Инструкция для желтого кластера

При желтом состоянии я использую следующий порядок:

Проверьте, достаточно ли в кластере узлов данных для настроенного количества реплик.
Проверьте пороги заполнения диска с помощью _cat/allocation.
Проверьте, не было ли отключено выделение во время технического обслуживания.
Проверьте фильтры маршрутизации на уровне индекса и правила осведомленности.
Решите, добавлять ли емкость, уменьшать количество реплик или исправлять неверное правило.

Проверка количества узлов проста. Если у индекса number_of_replicas: 2, Elasticsearch нужны три подходящих узла данных для размещения одного первичного шарда и двух реплик. «Подходящих» имеет значение. Если осведомленность о выделении требует отдельных зон, вам нужны узлы в этих зонах, а не просто любые три узла.

Проверьте выделение и диск:

curl -s "http://localhost:9200/_cat/allocation?v"

Если узлы превысили пороги заполнения диска, Elasticsearch может отказаться от новых выделений шардов. Освободите место, добавьте узлы, расширьте диски или удалите старые индексы после создания снимков. Повышение порогов может выиграть время в контролируемой аварийной ситуации, но не создает емкость.

Проверьте настройки выделения:

curl -s "http://localhost:9200/_cluster/settings?include_defaults=true&pretty"

Если cluster.routing.allocation.enable установлен в none, выделение отключено. Это часто случается после скриптов обслуживания, которые забыли включить его обратно. Включите его снова:

curl -X PUT "http://localhost:9200/_cluster/settings?pretty"   -H 'Content-Type: application/json'   -d '{
    "persistent": {
      "cluster.routing.allocation.enable": "all"
    }
  }'

Также проверьте, не было ли значение установлено как transient; постоянные и временные настройки могут влиять на поведение.

Инструкция для красного кластера

При красном состоянии замедлитесь и определите радиус поражения. Не начинайте с allocate_empty_primary. Эта команда по своей сути принимает потерю данных.

Сначала найдите затронутые первичные шарды:

curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason"   | grep ' p '   | grep UNASSIGNED

Затем проверьте один из них с помощью объяснения выделения:

curl -X GET "http://localhost:9200/_cluster/allocation/explain?pretty"   -H 'Content-Type: application/json'   -d '{
    "index": "affected-index",
    "shard": 0,
    "primary": true
  }'

Если первичный шард не назначен из-за того, что узел не работает, вашим лучшим вариантом восстановления может быть восстановление этого узла. Проверьте службу, диск, журналы JVM и сетевой путь. Если копия реплики существует на другом узле, Elasticsearch обычно должен повысить ее. Если этого не происходит, вывод объяснения и журналы обычно сообщают вам причину.

Если данные потеряны или повреждены, восстановитесь из снимка. Это чистый путь восстановления. Если снимка не существует и данные могут быть перестроены из другого источника, вы можете решить выделить пустой первичный шард:

curl -X POST "http://localhost:9200/_cluster/reroute?pretty"   -H 'Content-Type: application/json'   -d '{
    "commands": [
      {
        "allocate_empty_primary": {
          "index": "affected-index",
          "shard": 0,
          "node": "target-node-name",
          "accept_data_loss": true
        }
      }
    ]
  }'

Используйте это только тогда, когда потеря содержимого шарда приемлема. Название буквально: Elasticsearch выделяет пустой первичный шард и продолжает работу.

Наблюдайте за восстановлением вместо того, чтобы гадать

После исправления наблюдайте за движением шардов:

curl -s "http://localhost:9200/_cat/recovery?v&active_only=true"
curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason"
curl -s "http://localhost:9200/_cluster/health?pretty"

Восстановление может быть ограничено скоростью диска, пропускной способностью сети, размером шарда и настройками восстановления кластера. Большой шард может находиться в состоянии INITIALIZING дольше, чем вы ожидаете. Это отличается от зависания. Если количество байтов и файлов меняется в _cat/recovery, дайте ему поработать.

Также проверьте ожидающие задачи кластера, когда состояние не меняется:

curl -s "http://localhost:9200/_cat/pending_tasks?v"

Длинная очередь может указывать на перегруженный мастер-узел или повторяющиеся решения о выделении, которые не могут быть завершены.

Практический пример

Предположим, _cat/health показывает желтый цвет с двумя неназначенными шардами. _cat/shards показывает, что оба являются репликами для logs-2026.05.24. Объяснение выделения говорит, что кластер не может выделить шарды, потому что каждый узел данных превысил низкий порог заполнения диска. Исправление заключается не в ручном перенаправлении шардов. Исправление — это емкость: удалите старые индексы после создания их снимков, добавьте хранилище, добавьте узлы данных или переместите холодные данные в другое место.

Другой пример: трехузловой кластер стал желтым после последовательного перезапуска. _cluster/health показывает delayed_unassigned_shards: 8. Остановленный узел уже возвращается. В этом случае ожидание в течение нескольких минут может быть правильным. Немедленное принудительное выделение может создать дополнительную работу по восстановлению и замедлить перезапуск.

Третий пример: одноузловой лабораторный кластер навсегда желтый. _cat/shards показывает, что каждый неназначенный шард является репликой. У индекса одна реплика. Elasticsearch ведет себя правильно. Установите количество реплик равным нулю для лаборатории или добавьте второй узел данных.

Сделайте проверку состояния честной

Состояние кластера должно быть частью мониторинга, но правила оповещения требуют контекста. Немедленно оповещайте о красном состоянии. Оповещайте о желтом состоянии, когда оно длится дольше короткого окна технического обслуживания, когда количество неназначенных реплик увеличивается или когда причиной является нехватка дискового пространства. Отслеживайте пороги заполнения диска, количество узлов, давление JVM и успешность создания снимков наряду с цветом состояния. Цвет говорит вам, с чего начать; API шардов и выделения говорят вам, что делать дальше.

Когда проверки состояния расходятся с симптомами пользователей

Иногда кластер зеленый, а пользователи все равно жалуются. Это не противоречие. Состояние кластера касается назначения шардов, а не задержки запросов или корректности. Если состояние зеленое, но поиск медленный, переходите к задержке поиска, пулам потоков, горячим шардам, давлению JVM и задержке хранилища. Зеленый кластер с одним перегруженным узлом данных все еще может казаться сломанным.

Бывает и наоборот. Кластер может быть желтым по безобидной причине, например, одноузловая среда разработки с настроенными репликами. Полезная привычка — связывать состояние с бизнес-воздействием. Какой индекс затронут? Это первичный шард или реплика? Читает ли приложение из этого индекса прямо сейчас? Это происходит во время планового обслуживания? Эти вопросы удерживают вас от того, чтобы относиться к каждому желтому статусу как к катастрофе.

Для систем, ориентированных на клиентов, я предпочитаю хранить небольшую таблицу Runbook вне Elasticsearch: шаблон индекса, обслуживающая служба, источник данных, политика создания снимков, можно ли воспроизвести данные и кто утверждает разрушительное восстановление. Во время инцидента с красным состоянием эта таблица часто бывает более полезной, чем еще одна панель мониторинга. Если clickstream-* можно воспроизвести из Kafka, выбор восстановления отличается от индекса, содержащего пользовательские документы без вышестоящей копии.

Более безопасные привычки работы с командами

Используйте явные имена индексов, когда можете. Подстановочные знаки удобны, но они скрывают радиус поражения. Перед выполнением любой команды, изменяющей настройки или удаляющей данные, выведите список того, чему соответствует шаблон:

curl -s "http://localhost:9200/_cat/indices/logs-prod-*?v&s=index"

Сохраняйте вывод команд во время инцидента. Вставляйте результаты объяснения выделения, списки шардов и ответы о состоянии в тикет. Состояние Elasticsearch быстро меняется во время восстановления, и вам может понадобиться более ранний вывод, чтобы понять, почему было принято решение.

Если безопасность включена, выполняйте эти команды от имени пользователя, имеющего минимально необходимые привилегии для диагностики, и используйте отдельный, более ограниченный процесс для деструктивных операций. В стрессовой ситуации слишком легко вставить команду записи в ту же оболочку, где вы только что проверяли состояние.

Что проверить после возвращения кластера к зеленому состоянию

Зеленый цвет — это не конец инцидента. Проверьте, перестроились ли реплики на ожидаемых узлах, не приблизился ли диск к порогам заполнения, и не остался ли какой-либо индекс с временными настройками, такими как number_of_replicas: 0, длинный refresh_interval или отключенное выделение.

Также убедитесь, что создание снимков выполняется успешно после восстановления. Кластер, у которого только что были проблемы с шардами, мог выявить пробел в политике хранения, учетных данных репозитория или расписании создания снимков. Если восстановление зависело от удачи, потому что снимка не существовало, запишите это и исправьте до следующего сбоя.

Наконец, пересмотрите оповещения. Если люди заметили проблему до того, как это сделал мониторинг, добавьте или настройте оповещения о красном состоянии, длительном желтом состоянии, давлении порогов заполнения диска, отсутствующих узлах, неудачных снимках и повторных выборах мастера. Цвет состояния кластера полезен, но лучшее оповещение сообщает вам, почему цвет изменился и какой индекс затронут.