Плагин Elasticsearch

Мониторинг поискового и аналитического движка Elasticsearch с подробными метриками по состоянию кластера, индексам, узлам, производительности поиска и статистике JVM.

Обзор

Плагин Elasticsearch собирает подробные метрики из API Elasticsearch, в том числе:

• Состояние кластера — статус, узлы, шарды, активные шарды, перемещаемые шарды
• Статистика индексов — число документов, размер хранилища, частота индексации, частота поиска
• Метрики узлов — использование CPU, использование памяти, использование диска, куча JVM
• Производительность поиска — время запроса, время выборки, scroll-запросы
• Производительность индексации — время индексации, время удаления, время слияния
• Пулы потоков — активные потоки, размер очереди, отклонённые задачи
• Статистика кеша — кеш полей, кеш запросов, кеш запросов

Требования

Версия Elasticsearch

• Минимум: Elasticsearch 7.0
• Рекомендуется: Elasticsearch 8.0 или новее
• Протестировано с: Elasticsearch 7.17, 8.8, 8.10, 8.11

Зависимости Python

pip install elasticsearch>=8.7.0

Устанавливается автоматически при использовании PLUGINS=elasticsearch во время установки агента.

Доступ к Elasticsearch

Агенту нужен HTTP-доступ к REST API Elasticsearch (порт по умолчанию 9200).

Конфигурация

Базовая конфигурация

plugins:
  elasticsearch:
    enabled: true
    host: localhost
    port: 9200

С аутентификацией

plugins:
  elasticsearch:
    enabled: true
    host: localhost
    port: 9200
    username: elastic
    password: your-password

С HTTPS

plugins:
  elasticsearch:
    enabled: true
    host: elasticsearch.example.com
    port: 9200
    username: elastic
    password: your-password
    use_ssl: true
    verify_ssl: true

Все параметры конфигурации

plugins:
  elasticsearch:
    enabled: true                    # Enable/disable plugin
    host: localhost                  # Elasticsearch host
    port: 9200                       # Elasticsearch port
    username: elastic                # Username (optional)
    password: password               # Password (optional)
    use_ssl: false                   # Use HTTPS (default: false)
    verify_ssl: true                 # Verify SSL certificates
    ca_cert: /path/to/ca.pem        # CA certificate path
    timeout: 10                      # Request timeout (seconds)

Переменные окружения

Конфигурацию можно переопределить с помощью переменных окружения:

export ELASTICSEARCH_HOST="localhost"
export ELASTICSEARCH_PORT="9200"
export ELASTICSEARCH_USERNAME="elastic"
export ELASTICSEARCH_PASSWORD="password"

Настройка Elasticsearch

Установка

Ubuntu/Debian:

# Install Elasticsearch
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/8.x/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-8.x.list

sudo apt-get update
sudo apt-get install elasticsearch

# Start service
sudo systemctl start elasticsearch
sudo systemctl enable elasticsearch

CentOS/RHEL:

# Add repository
sudo rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch

cat <<EOF | sudo tee /etc/yum.repos.d/elasticsearch.repo
[elasticsearch]
name=Elasticsearch repository for 8.x packages
baseurl=https://artifacts.elastic.co/packages/8.x/yum
gpgcheck=1
gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
enabled=1
autorefresh=1
type=rpm-md
EOF

# Install
sudo yum install elasticsearch

# Start service
sudo systemctl start elasticsearch
sudo systemctl enable elasticsearch

Конфигурация безопасности

В Elasticsearch 8.x безопасность включена по умолчанию.

Получите начальный пароль:

# Elasticsearch 8.x creates elastic user on first start
# Password is in installation output or reset with:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic

Создайте пользователя для мониторинга:

curl -X POST "localhost:9200/_security/user/monitor" \
  -u elastic:password \
  -H "Content-Type: application/json" \
  -d '{
    "password": "monitor-password",
    "roles": ["monitoring_user"],
    "full_name": "Monitoring User"
  }'

Или отключите безопасность (не рекомендуется для production):

# /etc/elasticsearch/elasticsearch.yml
xpack.security.enabled: false

Конфигурация сети

Привязка ко всем интерфейсам:

# /etc/elasticsearch/elasticsearch.yml
network.host: 0.0.0.0

Примечание по безопасности: Открывайте Elasticsearch только доверенным сетям.

Собираемые метрики

Метрики состояния кластера

Метрики узлов

Метрики индексации

Метрики поиска

Метрики кеша

Метрики пула потоков

Статистика индексов

Метрики на дашборде

Дашборд StatusRadar отображает:

Карточка обзора

• Cluster Status — индикатор green/yellow/red
• Nodes — всего узлов в кластере
• Documents — общее число документов
• Store Size — общий размер индексов

График состояния кластера

• Активные шарды во времени
• Неназначенные шарды
• Перемещаемые шарды
• Изменения статуса кластера

График производительности поиска

• Частота запросов
• Частота выборок
• Среднее время запроса

График производительности индексации

• Частота индексации
• Частота удалений
• Среднее время индексации

График кучи JVM

• Использование кучи во времени
• Процент использования кучи
• Активность GC

График ресурсов узлов

• Использование CPU
• Использование памяти
• Использование диска

Установка

Быстрая установка

PLUGINS='elasticsearch' \
TOKEN='your-agent-token' \
ELASTICSEARCH_USERNAME='elastic' \
ELASTICSEARCH_PASSWORD='your-password' \
bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

Установка на существующий агент

1. Установите зависимость Python:

   cd /opt/statusradar
   source venv/bin/activate  # If using venv
   pip install elasticsearch

2. Включите плагин в конфигурации:

   sudo nano /opt/statusradar/config/agent.yaml

   Добавьте:

   plugins:
     elasticsearch:
       enabled: true
       host: localhost
       port: 9200
       username: elastic
       password: your-password

3. Перезапустите агент:

   sudo systemctl restart statusradar-agent

4. Проверьте:

   sudo journalctl -u statusradar-agent -n 50 --no-pager | grep elasticsearch

   Ожидается:

   INFO: Plugin elasticsearch: Metrics collected successfully
   INFO: Plugin elasticsearch: Cluster green, 3 nodes, 1234567 docs

Тестирование

Ручной тест плагина

cd /opt/statusradar
python3 plugins/elasticsearch_plugin.py

Ожидаемый вывод:

Plugin: elasticsearch
Enabled: True
Available: True

Collecting metrics...
{
  "cluster_status": "green",
  "nodes_total": 3,
  "nodes_data": 3,
  "shards_active": 120,
  "shards_primary": 60,
  "shards_unassigned": 0,
  "indices_count": 25,
  "docs_count": 1234567,
  "store_size_bytes": 5368709120,
  "indexing_total": 987654,
  "search_query_total": 456789,
  "jvm_heap_used_percent": 45.2,
  "cpu_percent": 12.5
}

Проверка соединения с Elasticsearch

# Check cluster health
curl -u elastic:password http://localhost:9200/_cluster/health?pretty

# Check node stats
curl -u elastic:password http://localhost:9200/_nodes/stats?pretty

# Check indices
curl -u elastic:password http://localhost:9200/_cat/indices?v

Устранение неполадок

Плагин не собирает метрики

Проверка 1: Запущен ли Elasticsearch?

sudo systemctl status elasticsearch

Проверка 2: Может ли агент подключиться к Elasticsearch?

curl -u elastic:password http://localhost:9200

Проверка 3: Установлен ли пакет Python?

python3 -c "import elasticsearch; print(elasticsearch.__version__)"

Проверка 4: Проверьте логи агента

sudo journalctl -u statusradar-agent -n 100 --no-pager | grep elasticsearch

Распространённые ошибки

"Authentication failed"

Ошибка:

ERROR: Plugin elasticsearch: 401 Unauthorized

Причины:

1. Неверные имя пользователя/пароль
2. Безопасность не включена, но переданы учётные данные
3. У пользователя нет прав на мониторинг

Решение:

# Elasticsearch 8.x - reset password
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic

# Or disable security (not recommended)
# Edit /etc/elasticsearch/elasticsearch.yml:
# xpack.security.enabled: false

"Connection refused"

Ошибка:

ERROR: Plugin elasticsearch: Connection refused

Причины:

1. Elasticsearch не запущен
2. Неверный host/port
3. Файрвол блокирует соединение

Решение:

# Check Elasticsearch is running
sudo systemctl status elasticsearch

# Check port
sudo netstat -tlnp | grep 9200

# Test connection
curl http://localhost:9200

"No module named 'elasticsearch'"

Ошибка:

ERROR: No module named 'elasticsearch'

Решение:

pip install elasticsearch
# Or if using venv:
cd /opt/statusradar && source venv/bin/activate && pip install elasticsearch

"SSL certificate verification failed"

Ошибка:

ERROR: Plugin elasticsearch: SSL certificate verification failed

Решение:

plugins:
  elasticsearch:
    use_ssl: true
    verify_ssl: false  # Disable verification (not recommended)
    # Or provide CA certificate:
    # ca_cert: /etc/elasticsearch/certs/ca.crt

Влияние на производительность

На Elasticsearch

Минимальное влияние:

• Stats API возвращает предварительно рассчитанную статистику
• Нет операций поиска или индексации
• Время отклика: < 100 мс

Бенчмарк:

• Накладные расходы: < 0.1% CPU
• Нет измеримой деградации производительности

На агент

Использование ресурсов:

• Память: +20 МБ
• CPU: +4% во время сбора
• Сеть: +3 КБ за сбор

Время сбора: 0.2–1 секунда

Сценарии использования

1. Мониторинг состояния кластера

Отслеживайте:

• Статус кластера (green/yellow/red)
• Неназначенные шарды
• Число узлов

Оповещение при:

• Статусе кластера yellow/red
• Неназначенных шардах > 0
• Снижении числа узлов

2. Производительность поиска

Отслеживайте:

• Частоту запросов
• Среднее время запроса
• Медленные запросы

Оповещение при:

• Среднем времени запроса > 1 секунды
• Всплеске частоты запросов
• Растущей очереди поиска

3. Производительность индексации

Отслеживайте:

• Частоту индексации
• Среднее время индексации
• Отклонения bulk-операций

Оповещение при:

• Росте времени индексации
• Отклонениях очереди bulk
• Избыточном времени слияния

4. Мониторинг кучи JVM

Отслеживайте:

• Процент использования кучи
• Частоту GC
• Длительность GC

Оповещение при:

• Куче > 75% (риск OOM)
• Частых паузах GC
• Длительных паузах GC

5. Управление шардами

Отслеживайте:

• Распределение шардов
• Перемещаемые шарды
• Инициализирующиеся шарды

Оптимизируйте:

• Размещение шардов
• Ребалансировку
• Размер шардов

Лучшие практики

1. Установите подходящий размер кучи

Рекомендация: 50% от RAM системы, максимум 31 ГБ

# /etc/elasticsearch/jvm.options
-Xms16g
-Xmx16g  # Same as Xms

Никогда:

• Не превышайте 31 ГБ (лимит compressed oops)
• Не используйте более 50% RAM
• Не задавайте Xms != Xmx

2. Отслеживайте статус кластера

Green: Все первичные и реплика-шарды размещены Yellow: Все первичные шарды размещены, часть реплик отсутствует Red: Часть первичных шардов не размещена

Оповещайте о статусе yellow/red немедленно.

3. Управляйте числом шардов

Рекомендации:

• Держите размер шарда между 10–50 ГБ
• Ограничивайте число шардов на узел до 20–25 на ГБ кучи
• Используйте управление жизненным циклом индексов (ILM)

Рассчитайте оптимальное число шардов:

Shards per index = Index size / Target shard size (30GB)

4. Включите медленные логи

# /etc/elasticsearch/elasticsearch.yml
index.search.slowlog.threshold.query.warn: 10s
index.search.slowlog.threshold.query.info: 5s
index.search.slowlog.threshold.fetch.warn: 1s

index.indexing.slowlog.threshold.index.warn: 10s
index.indexing.slowlog.threshold.index.info: 5s

5. Отслеживайте кучу JVM

Здоровое использование кучи: 40–75%

Если куча > 75%:

• Увеличьте размер кучи (до 31 ГБ)
• Уменьшите кеш данных полей
• Снизьте нагрузку запросами
• Добавьте больше узлов

6. Используйте пользователя для мониторинга

Создайте выделенного пользователя только для чтения для мониторинга:

curl -X POST "localhost:9200/_security/user/monitor" \
  -u elastic:password \
  -H "Content-Type: application/json" \
  -d '{
    "password": "monitor-password",
    "roles": ["monitoring_user"]
  }'

Тонкая настройка производительности Elasticsearch

Оптимизация индексации

Bulk-индексация:

POST /_bulk
{ "index": { "_index": "logs" } }
{ "message": "Log entry", "timestamp": "2025-10-15" }

Интервал обновления:

{
  "index": {
    "refresh_interval": "30s"  # Default: 1s
  }
}

Оптимизация поиска

Используйте фильтры вместо запросов, когда возможно:

{
  "query": {
    "bool": {
      "filter": [
        { "term": { "status": "published" } }
      ]
    }
  }
}

Включите кеш запросов:

{
  "index": {
    "requests": {
      "cache": {
        "enable": true
      }
    }
  }
}

Настройки памяти

Circuit breaker для данных полей:

indices.breaker.fielddata.limit: 40%

Circuit breaker для запросов:

indices.breaker.request.limit: 60%

Расширенная конфигурация

Кластер Elasticsearch

Мониторинг каждого узла отдельно:

plugins:
  elasticsearch_node1:
    enabled: true
    host: es-node1.internal
    port: 9200
    username: elastic
    password: password

  elasticsearch_node2:
    enabled: true
    host: es-node2.internal
    port: 9200
    username: elastic
    password: password

Docker-контейнер

Мониторинг Elasticsearch в Docker:

plugins:
  elasticsearch:
    enabled: true
    host: elasticsearch-container
    port: 9200
    username: elastic
    password: password

Запуск Docker:

docker run -d --name elasticsearch \
  -p 9200:9200 \
  -e "discovery.type=single-node" \
  -e "ELASTIC_PASSWORD=password" \
  docker.elastic.co/elasticsearch/elasticsearch:8.11.0

Elastic Cloud

Мониторинг развёртывания Elastic Cloud:

plugins:
  elasticsearch:
    enabled: true
    host: my-deployment.es.eastus2.azure.elastic-cloud.com
    port: 9243
    username: elastic
    password: cloud-password
    use_ssl: true
    verify_ssl: true

Примеры конфигураций

Базовая локальная конфигурация

plugins:
  elasticsearch:
    enabled: true
    host: localhost
    port: 9200

Production с аутентификацией

plugins:
  elasticsearch:
    enabled: true
    host: elasticsearch.internal
    port: 9200
    username: monitor
    password: ${ELASTICSEARCH_PASSWORD}
    use_ssl: true
    verify_ssl: true

Кластер Elasticsearch (3 узла)

plugins:
  es_master:
    enabled: true
    host: es-master.internal
    port: 9200
    username: monitor
    password: ${ES_PASSWORD}

  es_data1:
    enabled: true
    host: es-data1.internal
    port: 9200
    username: monitor
    password: ${ES_PASSWORD}

  es_data2:
    enabled: true
    host: es-data2.internal
    port: 9200
    username: monitor
    password: ${ES_PASSWORD}

Ограничения

Текущие ограничения

1. Нет деталей по отдельным индексам — только общекластерная статистика
2. Нет анализа запросов — используйте медленные логи для отладки запросов
3. Нет метрик пайплайнов — статистика ingest-пайплайнов не собирается

Масштабируемость

Протестировано с:

• Кластерами с 100+ узлами
• Индексами с 1 ТБ+ данных
• Частотой индексации 10 000+ документов в секунду

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

• Время отклика Stats API постоянно независимо от размера кластера
• Нет влияния на производительность Elasticsearch

Лучшие практики мониторинга

Критические метрики

1. Статус кластера red — потеря данных
2. Неназначенные шарды > 0 — отсутствует реплика
3. Куча JVM > 85% — риск OOM
4. Свободного места на диске < 10% — порог watermark

Пороги оповещений

# Recommended thresholds
cluster_status: != green
shards_unassigned: > 0
jvm_heap_used_percent: > 75
search_query_time_avg_ms: > 1000
indexing_time_avg_ms: > 500

Устранение проблем производительности

Медленный поиск

Симптомы: Высокое время запроса

Решения:

1. Включите кеш запросов
2. Используйте фильтры вместо запросов
3. Уменьшите число шардов
4. Добавьте больше узлов
5. Проверьте медленные логи

Высокая куча JVM

Симптомы: Куча > 75%

Решения:

1. Увеличьте размер кучи (максимум 31 ГБ)
2. Уменьшите данные полей
3. Отключите поле _source, если не нужно
4. Используйте doc_values
5. Добавьте больше узлов

Неназначенные шарды

Симптомы: Статус кластера yellow/red

Решения:

1. Проверьте место на диске
2. Увеличьте index.number_of_replicas, если нужно
3. Проверьте настройки размещения шардов
4. Вручную перенаправьте шарды

# Retry failed allocations
curl -X POST "localhost:9200/_cluster/reroute?retry_failed=true"

Следующие шаги

• Просмотреть все плагины
• Системные требования
• Руководство по конфигурации агента
• Руководство по устранению неполадок