Плагин Meilisearch

Мониторинг поискового движка Meilisearch через эндпоинт метрик Prometheus с метриками по производительности HTTP, статистике индексов, размеру базы данных и обработке задач.

Обзор

Плагин Meilisearch собирает метрики из эндпоинта Prometheus /metrics Meilisearch, в том числе:

• Метрики базы данных — общий размер базы данных, используемое хранилище, процент утилизации
• Статистика индексов — число индексов, всего документов
• Производительность HTTP — число запросов, времена отклика, средняя задержка
• Статус индексации — активна ли индексация в данный момент
• Статистика задач — всего обработанных задач

Требования

Версия Meilisearch

• Минимум: Meilisearch 1.0
• Рекомендуется: Meilisearch 1.5 или новее
• Протестировано с: Meilisearch 1.3, 1.4, 1.5, 1.6

ВАЖНО: Meilisearch должен быть запущен с флагом --experimental-enable-metrics или переменной окружения MEILI_EXPERIMENTAL_ENABLE_METRICS=true, чтобы открыть эндпоинт Prometheus /metrics.

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

pip install requests>=2.28.0

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

Доступ к Meilisearch

Агенту нужен HTTP-доступ к эндпоинту метрик Prometheus Meilisearch (порт по умолчанию 7700).

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

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

plugins:
  meilisearch:
    enabled: true
    host: localhost
    port: 7700

С API-ключом

plugins:
  meilisearch:
    enabled: true
    host: localhost
    port: 7700
    api_key: your-master-key

С HTTPS

plugins:
  meilisearch:
    enabled: true
    host: search.example.com
    port: 7700
    protocol: https
    api_key: your-api-key

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

plugins:
  meilisearch:
    enabled: true                # Enable/disable plugin
    host: localhost              # Meilisearch host
    port: 7700                   # Meilisearch port
    protocol: http               # Protocol: http or https
    api_key: ""                  # API key (master key recommended)

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

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

export MEILISEARCH_HOST="localhost"
export MEILISEARCH_PORT="7700"
export MEILISEARCH_PROTOCOL="http"  # or "https"
export MEILISEARCH_API_KEY="your-master-key"

Настройка Meilisearch

Установка

Установка из бинарного файла:

# Download latest release
curl -L https://install.meilisearch.com | sh

# Run Meilisearch with metrics enabled
./meilisearch --experimental-enable-metrics

# Or with master key and metrics
./meilisearch \
  --master-key="your-secure-master-key" \
  --experimental-enable-metrics

Docker:

docker run -d \
  --name meilisearch \
  -p 7700:7700 \
  -e MEILI_MASTER_KEY="your-secure-master-key" \
  -e MEILI_EXPERIMENTAL_ENABLE_METRICS="true" \
  getmeili/meilisearch:latest

Как сервис systemd:

# Create service file
sudo nano /etc/systemd/system/meilisearch.service

[Unit]
Description=Meilisearch
After=network.target

[Service]
Type=simple
User=meilisearch
WorkingDirectory=/var/lib/meilisearch
Environment="MEILI_MASTER_KEY=your-secure-master-key"
Environment="MEILI_EXPERIMENTAL_ENABLE_METRICS=true"
Environment="MEILI_DB_PATH=/var/lib/meilisearch/data"
Environment="MEILI_HTTP_ADDR=0.0.0.0:7700"
ExecStart=/usr/local/bin/meilisearch
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl start meilisearch
sudo systemctl enable meilisearch

Настройка API-ключа

Мастер-ключ (рекомендуется для эндпоинта метрик):

• Устанавливается через переменную окружения MEILI_MASTER_KEY
• Требуется для доступа к эндпоинту Prometheus /metrics
• Предоставляет полный доступ ко всем операциям API

Примечание: Эндпоинт /metrics обычно требует мастер-ключ. Пользовательские API-ключи могут не иметь доступа к этому экспериментальному эндпоинту.

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

Примечание: Этот плагин собирает метрики из эндпоинта Prometheus /metrics Meilisearch (требуется флаг --experimental-enable-metrics). Доступные метрики зависят от того, что предоставляет Meilisearch.

Метрики базы данных

Метрики индексов

Статус индексации

Метрики HTTP

Метрики задач

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

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

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

• Database Size — общее и используемое хранилище (с % утилизации)
• Indices — число индексов
• Documents — общее число документов по индексам
• Indexing Status — активна ли индексация

График размера базы данных

• Общий размер базы данных во времени
• Используемый размер базы данных во времени
• Процент утилизации

График статистики индексов

• Число документов во времени
• Число индексов во времени

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

• Всего HTTP-запросов
• Среднее время отклика (мс)
• Частота запросов

График статистики задач

• Всего обработанных задач
• Частота обработки задач

Установка

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

PLUGINS='meilisearch' \
TOKEN='your-agent-token' \
MEILISEARCH_API_KEY='your-master-key' \
bash -c "$(curl -sL https://statusradar.dev/install-agent.sh)"

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

1. Настройте агент:

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

   Добавьте:

   plugins:
     meilisearch:
       enabled: true
       host: localhost
       port: 7700
       api_key: your-master-key

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

   sudo systemctl restart statusradar-agent

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

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

   Ожидается:

   INFO: Plugin meilisearch: Metrics collected successfully
   INFO: Plugin meilisearch: 5 indices, 12345 documents, 256 MB database (75% used)

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

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

cd /opt/statusradar
python3 plugins/meilisearch_plugin.py

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

Plugin: meilisearch
Enabled: True
Available: True

Collecting metrics...
{
  "db_size_bytes": 268435456,
  "used_db_size_bytes": 201326592,
  "db_utilization_percent": 75.0,
  "index_count": 5,
  "index_docs_count": 12345,
  "is_indexing": 0,
  "http_requests_total": 9876,
  "http_response_time_seconds_total": 123.45,
  "http_avg_response_time_ms": 12.5,
  "nb_tasks_total": 9888
}

Проверка API Meilisearch

# Health check
curl http://localhost:7700/health

# Prometheus metrics endpoint (requires experimental flag)
curl http://localhost:7700/metrics

# With API key
curl http://localhost:7700/metrics \
  -H "Authorization: Bearer your-master-key"

# Check metrics are being exposed
curl http://localhost:7700/metrics | grep meilisearch

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

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

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

sudo systemctl status meilisearch
# Or check process:
ps aux | grep meilisearch

Проверка 2: Включён ли эндпоинт метрик?

# Should return Prometheus metrics
curl http://localhost:7700/metrics

# If you get 404, Meilisearch is not started with --experimental-enable-metrics

Проверка 3: Может ли агент получить доступ к метрикам Meilisearch?

# Without API key
curl http://localhost:7700/metrics | head -20

# With API key
curl http://localhost:7700/metrics \
  -H "Authorization: Bearer your-master-key" | head -20

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

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

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

"Connection refused"

Ошибка:

ERROR: Plugin meilisearch: Connection refused

Причины:

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

Решение:

# Check Meilisearch is running
ps aux | grep meilisearch

# Check port
sudo netstat -tlnp | grep 7700

# Test metrics endpoint
curl http://localhost:7700/metrics

"Invalid API key"

Ошибка:

ERROR: Plugin meilisearch: 401 Unauthorized - Invalid API key

Решение:

Проверьте API-ключ:

# Test with API key
curl http://localhost:7700/metrics \
  -H "Authorization: Bearer your-master-key"

Если ключ забыт, перезапустите Meilisearch с новым мастер-ключом:

./meilisearch \
  --master-key="new-secure-master-key" \
  --experimental-enable-metrics

"Forbidden"

Ошибка:

ERROR: Plugin meilisearch: 403 Forbidden

Причина: У API-ключа нет необходимых прав для эндпоинта метрик

Решение: Используйте мастер-ключ. Эндпоинт /metrics обычно требует доступа с мастер-ключом.

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

На Meilisearch

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

• Эндпоинт Prometheus /metrics возвращает предварительно рассчитанную статистику
• Нет операций индексации или поиска
• Время отклика: < 50 мс

Бенчмарк:

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

На агент

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

• Память: +10 МБ
• CPU: +2% во время сбора
• Сеть: +1 КБ за сбор

Время сбора: < 0.2 секунды

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

1. Мониторинг роста индексов

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

• Число документов по каждому индексу
• Рост размера базы данных
• Частоту создания индексов

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

• Быстром росте числа документов
• Размере базы данных, приближающемся к лимиту
• Слишком большом числе индексов

2. Мониторинг очереди задач

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

• Задачи в очереди
• Обрабатываемые задачи
• Неудавшиеся задачи

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

• Накоплении очереди задач (> 100 задач)
• Высокой частоте отказов
• Задачах, зависших в обработке

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

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

• Задержку поиска (через метрики приложения)
• Частоту обновления индексов
• Частоту индексации документов

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

• Настройки индексов
• Релевантность поиска
• Правила фильтрации

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

1. Устанавливайте мастер-ключ в production

Всегда используйте мастер-ключ в production:

MEILI_MASTER_KEY="secure-random-string-at-least-32-chars"

Сгенерируйте безопасный ключ:

openssl rand -base64 32

2. Отслеживайте размер базы данных

Выделите подходящее место на диске:

• База данных может сильно вырасти при большом числе документов
• Отслеживайте использование диска
• Внедряйте политики хранения

3. Отслеживайте очередь задач

Здоровая очередь:

• В очереди: < 10 задач
• В обработке: 1–5 задач
• Неудавшиеся: 0 или минимум

Если очередь накапливается:

• Увеличьте ресурсы
• Оптимизируйте размер документов
• Группируйте операции в пакеты

4. Используйте асинхронную индексацию

# Python example
import meilisearch

client = meilisearch.Client('http://localhost:7700', 'your-master-key')

# Async document addition
task = client.index('movies').add_documents([
    {'id': 1, 'title': 'Movie 1'},
    {'id': 2, 'title': 'Movie 2'}
])

# Check task status
client.get_task(task.task_uid)

5. Внедрите проверки состояния

# Health endpoint
curl http://localhost:7700/health

# Should return: {"status": "available"}

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

Настройки индексов

{
  "searchableAttributes": ["title", "description"],
  "filterableAttributes": ["genre", "year"],
  "sortableAttributes": ["year", "rating"],
  "rankingRules": [
    "words",
    "typo",
    "proximity",
    "attribute",
    "sort",
    "exactness"
  ]
}

Конфигурация памяти

# Set max indexing memory (MB)
MEILI_MAX_INDEXING_MEMORY=2048 ./meilisearch

Лимит размера полезной нагрузки

# Set max payload size (bytes)
MEILI_HTTP_PAYLOAD_SIZE_LIMIT=104857600 ./meilisearch

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

Несколько экземпляров Meilisearch

plugins:
  meilisearch_prod:
    enabled: true
    host: search-prod.internal
    port: 7700
    api_key: ${MEILI_PROD_KEY}

  meilisearch_staging:
    enabled: true
    host: search-staging.internal
    port: 7700
    api_key: ${MEILI_STAGING_KEY}

Docker-контейнер

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

plugins:
  meilisearch:
    enabled: true
    host: meilisearch-container
    port: 7700
    api_key: ${MEILI_MASTER_KEY}

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

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

plugins:
  meilisearch:
    enabled: true
    host: localhost
    port: 7700
    api_key: ${MEILISEARCH_MASTER_KEY}

С HTTPS

plugins:
  meilisearch:
    enabled: true
    host: search.example.com
    port: 443
    protocol: https
    api_key: ${MEILISEARCH_API_KEY}

Высокодоступная конфигурация

plugins:
  meilisearch_primary:
    enabled: true
    host: search1.internal
    port: 7700
    api_key: ${MEILI_KEY}

  meilisearch_replica:
    enabled: true
    host: search2.internal
    port: 7700
    api_key: ${MEILI_KEY}

Ограничения

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

1. Нет метрик по отдельным поискам — только агрегированная статистика
2. Нет анализа запросов — разбивка поисковых запросов недоступна
3. Нет использования RAM — метрики памяти не предоставляются API

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

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

• 10М+ документов
• 100+ индексов
• Базами данных размером в ГБ

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

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

Чек-лист мониторинга

Критично:

1. Накопление очереди задач (> 100 задач)
2. Высокая частота отказов задач (> 5%)
3. База данных, приближающаяся к лимиту диска

Важно: 4. Число документов не растёт (проблемы индексации) 5. Задачи, зависшие в обработке 6. Устаревшая версия

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

tasks_enqueued: > 100
tasks_failed_rate: > 0.05
database_size_percent: > 85

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

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