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

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

Быстрая диагностика

Проверьте статус агента

sudo systemctl status statusradar-agent

Ожидаемый вывод при работающем агенте:

● statusradar-agent.service - StatusRadar Server Monitoring Agent
   Loaded: loaded
   Active: active (running) since ...

Просмотрите последние логи

sudo journalctl -u statusradar-agent -n 100 --no-pager

Запустите агент вручную

# Stop the service
sudo systemctl stop statusradar-agent

# Run manually to see errors
cd /opt/statusradar
python3 statusradar-agent.py

Распространённые проблемы

1. Агент не запускается

Симптомы:

• Сервис не запускается
• systemctl status показывает «failed» или «inactive»

Диагностика:

sudo journalctl -u statusradar-agent -n 50 --no-pager

Частые причины:

Неверный токен

Ошибка в логах:

ERROR: Authentication failed: Invalid token
ERROR: HTTP 401 Unauthorized

Решение:

1. Проверьте значение API_TOKEN в /opt/statusradar/config.env
2. Получите правильный токен в панели управления
3. Перезапустите агент:

   sudo systemctl restart statusradar-agent

Отсутствующие зависимости

Ошибка в логах:

ModuleNotFoundError: No module named 'requests'
ImportError: No module named 'psutil'

Решение:

cd /opt/statusradar
sudo pip3 install -r requirements.txt
sudo systemctl restart statusradar-agent

Синтаксическая ошибка в конфигурации

Конфигурация — это shell-файл окружения (/opt/statusradar/config.env), загружаемый systemd через EnvironmentFile=. Некорректные строки молча игнорируются, из-за чего ключи могут остаться незаданными.

Решение:

1. Проверьте /opt/statusradar/config.env
2. Частые ошибки:
   • Пробелы вокруг знака = (используйте KEY=value, а не KEY = value)
   • Отсутствующие или несбалансированные кавычки для значений со спецсимволами
   • Комментарии в любом месте, кроме начала строки

# Wrong
INTERVAL = 300
REDIS_PASSWORD = s3cr3t  # inline comment after value

# Correct
INTERVAL=300
REDIS_PASSWORD="s3cr3t"

После редактирования перезапустите агент:

sudo systemctl restart statusradar-agent

Permission denied

Ошибка в логах:

PermissionError: [Errno 13] Permission denied: '/opt/statusradar/config.env'

Решение:

# Fix file permissions
sudo chown -R root:root /opt/statusradar
sudo chmod 755 /opt/statusradar
sudo chmod 600 /opt/statusradar/config.env

# Ensure service runs as root
sudo systemctl restart statusradar-agent

2. Метрики не появляются в панели управления

Симптомы:

• Агент работает, но в панели показано «No data»
• Сервер отображается как офлайн
• Время последнего обновления не меняется

Диагностика:

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

sudo journalctl -u statusradar-agent -f

Найдите:

INFO: Metrics collected successfully
INFO: Sent metrics to API

Проверьте сетевую доступность

# Test API connectivity
curl -I https://api.statusradar.dev

# Test from agent directory
cd /opt/statusradar
python3 -c "import requests; print(requests.get('https://api.statusradar.dev/health').status_code)"

Ожидается: 200

Частые причины:

Firewall блокирует исходящий HTTPS

Решение:

# Allow HTTPS outbound (Ubuntu/Debian)
sudo ufw allow out 443/tcp

# Allow HTTPS outbound (CentOS/RHEL)
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Неверный URL API

Ошибка в логах:

ERROR: Connection failed: Could not resolve host

Решение: Проверьте /opt/statusradar/config.env:

API_URL=https://api.statusradar.dev

Ограничение частоты запросов к API

Ошибка в логах:

ERROR: HTTP 429 Too Many Requests

Решение:

• Увеличьте значение INTERVAL в /opt/statusradar/config.env (минимум 60 секунд, по умолчанию 300)
• Если проблема сохраняется, обратитесь в поддержку

Сервер уже зарегистрирован

Если вы переустанавливаете агент, сервер может уже существовать в панели управления.

Решение:

1. Проверьте наличие существующего сервера в панели
2. Используйте существующий токен или сначала удалите старый сервер

3. Плагин не работает

Симптомы:

• Отсутствуют метрики конкретного плагина
• Ошибки плагина в логах

Диагностика:

Протестируйте плагин вручную

cd /opt/statusradar
python3 plugins/redis_plugin.py
python3 plugins/mysql_plugin.py
# etc.

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

Plugin: redis
Enabled: True
Available: True

Collecting metrics...
{
  "used_memory": 1234567,
  "connected_clients": 5,
  ...
}

Частые причины:

Плагин не включён

Плагины включаются перечислением в ключе PLUGINS через запятую.

Решение: Проверьте /opt/statusradar/config.env:

PLUGINS=redis,nginx,mysql

Затем перезапустите агент:

sudo systemctl restart statusradar-agent

Сервис не запущен

Ошибка:

ConnectionRefusedError: [Errno 111] Connection refused

Решение:

# Check if service is running
sudo systemctl status redis
sudo systemctl status mysql
sudo systemctl status postgresql
sudo systemctl status nginx
# etc.

# Start if needed
sudo systemctl start redis

Неверные параметры подключения

Ошибка:

ERROR: Authentication failed
ERROR: Access denied for user

Решение: Проверьте параметры подключения в /opt/statusradar/config.env:

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=monitor
MYSQL_PASSWORD=secret

Недостаточно прав

Пример для MySQL:

-- Grant necessary permissions
GRANT PROCESS, REPLICATION CLIENT ON *.* TO 'monitor'@'localhost';
FLUSH PRIVILEGES;

Пример для PostgreSQL:

-- Grant pg_monitor role
GRANT pg_monitor TO monitor;

Отсутствует конфигурация сервиса

Пример для Nginx:

Ошибка:

ERROR: HTTP 404 Not Found

Решение: Включите stub_status в nginx:

location /nginx_status {
    stub_status on;
    access_log off;
    allow 127.0.0.1;
    deny all;
}

Перезагрузите nginx:

sudo nginx -t
sudo systemctl reload nginx

4. Высокое потребление ресурсов

Симптомы:

• Агент использует слишком много CPU или памяти
• Замедление системы

Диагностика:

# Check agent resource usage
ps aux | grep statusradar-agent

# Check memory usage
sudo systemctl status statusradar-agent | grep Memory

Решения:

Снизьте частоту сбора

В /opt/statusradar/config.env:

INTERVAL=600

Отключите неиспользуемые плагины

Удалите плагин из списка PLUGINS (через запятую) в /opt/statusradar/config.env, затем перезапустите агент:

PLUGINS=nginx,mysql

sudo systemctl restart statusradar-agent

5. Ошибки SSL/TLS

Ошибка в логах:

SSLError: [SSL: CERTIFICATE_VERIFY_FAILED]

Решения:

Обновите CA-сертификаты

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y ca-certificates
sudo update-ca-certificates

# CentOS/RHEL
sudo yum install -y ca-certificates
sudo update-ca-trust

SSL-сертификат Python

# Reinstall certifi
sudo pip3 install --upgrade certifi

# Or use system certificates
export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

6. Проблемы синхронизации времени

Симптомы:

• Неверные временные метки метрик
• Сбои аутентификации

Решение:

# Install NTP
sudo apt-get install -y ntp  # Ubuntu/Debian
sudo yum install -y ntp      # CentOS/RHEL

# Start NTP service
sudo systemctl start ntp
sudo systemctl enable ntp

# Check time sync
timedatectl status

7. Агент останавливается через некоторое время

Симптомы:

• Агент сначала работает, но останавливается через часы/дни
• Перед остановкой в логах нет ошибок

Диагностика:

# Check if service auto-restart is enabled
systemctl show statusradar-agent | grep Restart

Ожидается: Restart=always

Решения:

Обновите systemd-сервис

Отредактируйте /etc/systemd/system/statusradar-agent.service:

[Service]
Restart=always
RestartSec=30

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

sudo systemctl daemon-reload
sudo systemctl restart statusradar-agent

Проверьте системные ресурсы

# Check available memory
free -h

# Check available disk space
df -h /opt/statusradar

Просмотрите системные логи

# Check for OOM killer
sudo journalctl -k | grep -i "killed process"

# Check for system errors
sudo journalctl -xe

Интерпретация логов

Успешный сбор

INFO: Collecting system metrics
INFO: Plugin redis: Metrics collected successfully
INFO: Plugin mysql: Metrics collected successfully
INFO: Sending metrics to API
INFO: Metrics sent successfully

Тревожные сигналы

WARNING: Plugin redis: Connection timeout (retrying)
WARNING: API request took 5.2s (slow network)

Обычно они временные. Если повторяются — разберитесь в причине.

Признаки ошибок

ERROR: Authentication failed
ERROR: Plugin mysql: Access denied
ERROR: Cannot connect to API

Они требуют немедленного внимания.

Расширенная отладка

Включите отладочное логирование

Отредактируйте код агента или добавьте в конфигурацию:

import logging
logging.basicConfig(level=logging.DEBUG)

Отладка сети

# Monitor network traffic
sudo tcpdump -i any -nn port 443

# Test DNS resolution
nslookup api.statusradar.dev

# Test with curl
curl -v -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.statusradar.dev/v1/agent/config

Отладка конкретного плагина

# Test plugin with verbose output
python3 -c "
import sys
sys.path.insert(0, '/opt/statusradar')
from plugins.redis_plugin import RedisPlugin
plugin = RedisPlugin()
print(plugin.collect())
"

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

Если устранить проблему не удаётся:

1. Соберите информацию:

   # System info
   uname -a
   python3 --version
   
   # Agent version
   head -20 /opt/statusradar/statusradar-agent.py | grep VERSION
   
   # Recent logs
   sudo journalctl -u statusradar-agent -n 200 --no-pager > agent-logs.txt
   
   # Configuration (remove sensitive data!)
   cat /opt/statusradar/config.env

2. Обратитесь в поддержку:

   • Email: [email protected]
   • Укажите: версию ОС, версию Python, логи ошибок, конфигурацию

3. Форумы сообщества:

   • Issues на GitHub: https://github.com/statusradar/agent/issues
   • Сообщество: https://community.statusradar.dev

Превентивные меры

Регулярное обслуживание

# Update agent (monthly)
curl -s https://statusradar.dev/install-agent.sh | sudo bash -s update

# Check logs weekly
sudo journalctl -u statusradar-agent -n 100 --no-pager

# Monitor dashboard daily
# https://statusradar.dev/dashboard/servers

Настройте мониторинг

Создайте оповещение об отключении агента:

1. Перейдите в Dashboard > Alerts
2. Создайте оповещение для «Server Offline»
3. Получайте уведомления, когда агент перестаёт отправлять метрики

Резервное копирование конфигурации

# Backup config file
sudo cp /opt/statusradar/config.env \
  /opt/statusradar/config.env.backup

Часто задаваемые вопросы

В: Можно ли запустить несколько агентов на одном сервере?

Нет. Один агент на сервер. Используйте плагины для мониторинга нескольких сервисов.

В: Что произойдёт, если агент временно офлайн?

Исторические данные сохраняются. Мониторинг возобновится, когда агент снова выйдет в онлайн.

В: Как полностью удалить агент?

См. руководство по удалению.

В: Можно ли отслеживать удалённые сервисы?

Да! Настройте плагины с удалёнными хостами в /opt/statusradar/config.env:

REDIS_HOST=remote-server.example.com
REDIS_PORT=6379

В: Сколько трафика использует агент?

~1–5 КБ в минуту (базовые метрики) + 5–10 КБ на каждый включённый плагин.

В: Безопасно ли запускать от root?

Да. Агенту нужен root для системных метрик. Следуйте рекомендациям по безопасности.

Дальнейшие шаги

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