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

Это руководство помогает диагностировать и решать распространённые проблемы с IceGate.

Здоровье Сервисов

Проверка Статуса Сервисов

# Сервис Query
        curl http://localhost:3100/ready
        
        # Сервис Ingest
        curl http://localhost:4318/health

Просмотр Логов Сервисов

# Docker Compose
        docker compose logs -f query
        docker compose logs -f ingest

Проблемы с Подключением

Не Удаётся Подключиться к Сервису Query

Симптомы:

  • Connection refused на порту 3100
  • Ошибки тайм-аута

Решения:

  1. Проверьте, что сервис запущен:

    docker ps | grep query

  2. Проверьте привязку порта:

    netstat -tlnp | grep 3100

  3. Проверьте логи сервиса на наличие ошибок:

    docker compose logs query | tail -100

Не Удаётся Подключиться к Объектному Хранилищу

Симптомы:

  • "Connection refused" к объектному хранилищу
  • Ошибки аутентификации S3

Решения:

  1. В локальном развёртывании RustFS проверьте, что объектное хранилище работает. Путь готовности специфичен для RustFS - на AWS S3 или у другого провайдера сразу переходите к шагу 3:

    curl http://localhost:9000/health/ready

  2. Проверьте учётные данные:

    echo $AWS_ACCESS_KEY_ID
        echo $AWS_SECRET_ACCESS_KEY

  3. Протестируйте подключение к S3. Уберите --endpoint-url, если бэкенд - настоящий AWS S3:

    aws s3 ls --endpoint-url http://localhost:9000

Не Удаётся Подключиться к Каталогу

Симптомы:

  • Ошибки "Catalog unavailable"
  • Ошибки создания таблиц

Решения:

  1. В S3-каталоге по умолчанию убедитесь, что объект состояния каталога читается, - отдельного сервиса каталога здесь нет:

    aws --endpoint-url http://localhost:9000 s3 ls s3://warehouse/catalog/root.json

    Отсутствие root.json означает, что миграция не выполнялась. Сначала запустите maintain migrate create.

  2. Проверьте конфигурацию каталога:

    catalog:
          backend: !s3
            warehouse: catalog
          warehouse: s3://warehouse/
          properties:
            bucket: warehouse
            region: us-east-1
            endpoint: http://rustfs:9000

  3. Только для REST-бэкенда проверьте, что Nessie запущен:

    curl http://localhost:19120/api/v1/trees

Проблемы с Запросами

Запрос Возвращает Пустые Результаты

Возможные Причины:

  • Неправильный идентификатор тенанта
  • Временной диапазон вне окна данных
  • Данные ещё не компактированы

Решения:

  1. Проверьте заголовок тенанта:

    curl -H "X-Scope-OrgID: correct-tenant" ...

  2. Проверьте временной диапазон:

    # Список доступного временного диапазона
        curl http://localhost:3100/loki/api/v1/labels \
          -H "X-Scope-OrgID: my-tenant"

  3. Проверьте WAL на наличие свежих данных:

    aws s3 ls s3://warehouse/wal/ --recursive

Тайм-аут Запроса

Симптомы:

  • Запросы выполняются слишком долго
  • 504 Gateway Timeout

Решения:

  1. Добавьте фильтр по временному диапазону:

    {service_name="api"} | timestamp > 1h ago

  2. Уменьшите лимит результатов:

    curl ... --data-urlencode 'limit=100'

  3. Проверьте план запроса:

    curl http://localhost:3100/loki/api/v1/explain \
          --data-urlencode 'query={service_name="api"}' \
          -H "X-Scope-OrgID: my-tenant"

Некорректный Синтаксис Запроса

Симптомы:

  • Ответы "parse error"
  • 400 Bad Request

Решения:

  1. Проверьте синтаксис LogQL:

    • Метки должны быть в фигурных скобках: {service_name="api"}
    • Строковые значения в кавычках: "value"
    • Формат длительности: [5m], [1h]

  2. Проверьте неподдерживаемые возможности:

    • Pipeline парсеры (json, logfmt) пока не поддерживаются
    • Некоторые агрегации не реализованы

Проблемы с Загрузкой

Данные Не Появляются

Симптомы:

  • Данные отправлены, но запрос возвращает пустой результат
  • Нет ошибок от ingest

Решения:

  1. Проверьте, что данные были приняты:

    curl -v -X POST http://localhost:4318/v1/logs \
          -H "X-Scope-OrgID: my-tenant" \
          -H "Content-Type: application/json" \
          -d '...'

  2. Проверьте файлы WAL:

    aws s3 ls s3://warehouse/wal/logs/ --recursive

  3. Дождитесь компакции (или запросите WAL напрямую)

Ошибки Загрузки

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

  • 400 Bad Request: Некорректный формат OTLP
  • 503 Service Unavailable: Хранилище недоступно
  • 429 Too Many Requests: Превышен лимит запросов

Решения:

  1. Проверьте формат OTLP payload
  2. Проверьте подключение к хранилищу
  3. Уменьшите частоту загрузки или масштабируйте реплики ingest

Проблемы с Производительностью

Медленные Запросы

  1. Добавьте фильтры по партициям:

    {tenant_id="my-tenant", service_name="api"}

  2. Ограничьте временной диапазон:

    --data-urlencode 'start=1704067200'
        --data-urlencode 'end=1704153600'

  3. Проверьте статистику таблицы:

    SHOW STATS FOR icegate.logs;

Высокое Потребление Памяти

  1. Уменьшите количество параллельных запросов
  2. Добавьте лимиты запросов
  3. Увеличьте выделение памяти сервиса

Получение Помощи

Если проблемы сохраняются:

  1. Соберите диагностическую информацию:

    # Логи сервисов
        docker compose logs > logs.txt
        
        # Информация о системе
        docker stats > stats.txt

  2. Обратитесь к GitHub Issues

  3. Включите:

    • Версию IceGate
    • Конфигурацию (очищенную от секретов)
    • Сообщения об ошибках
    • Шаги для воспроизведения

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

Предыдущая
Обслуживание
Следующая
Окружение для Разработки