bottohelp/metrics/MONITORING.md

📊 Система мониторинга ошибок

Обзор

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

🚀 Компоненты системы

1. Логирование (Structured Logging)

• Формат: JSON для легкого парсинга
• Уровни: DEBUG, INFO, WARNING, ERROR, CRITICAL
• Ротация: Автоматическая ротация логов
• Интеграция: Отправка ERROR и выше в Sentry

2. Метрики (Prometheus)

• Сервер метрик: HTTP endpoint на порту 8000 (настраиваемо)
• Собираемые метрики:
  • telegram_bot_errors_total - количество ошибок по типам
  • telegram_bot_command_duration_seconds - время выполнения команд
  • telegram_bot_active_users - количество активных пользователей
  • telegram_bot_messages_total - общее количество сообщений
  • telegram_bot_api_response_time_seconds - время отклика внешних API
  • telegram_bot_status - статус бота (1=работает, 0=остановлен)

3. Мониторинг ошибок (Sentry)

• Автоматический захват: Все необработанные исключения
• Performance monitoring: Отслеживание производительности
• Фильтрация: Исключение тестовых данных и чувствительной информации
• Контекст: Добавление информации о боте и конфигурации

4. Система алертов (AlertManager)

• Типы алертов:
  • Высокая частота ошибок (>10 в минуту)
  • Падение бота
  • Высокое время отклика (>5 секунд)
  • Проблемы с подключением к БД
• Каналы уведомлений:
  • Telegram (разработчикам)
  • Email
  • Webhook

🛠 Настройка

1. Установка зависимостей

pip install prometheus_client sentry-sdk

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

Добавьте в config_local.py:

# Включение мониторинга
ENABLE_SENTRY = True
SENTRY_DSN = "https://your-dsn@sentry.io/project-id"

# Настройки Prometheus
PROMETHEUS_PORT = 8000

# Уведомления разработчиков
ENABLE_DEVELOPER_NOTIFICATIONS = True
DEVELOPER_CHAT_ID = 123456789  # ID чата для алертов

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

export ENABLE_SENTRY=true
export SENTRY_DSN="https://your-dsn@sentry.io/project-id"
export PROMETHEUS_PORT=8000
export DEVELOPER_CHAT_ID=123456789

📈 Использование метрик

Prometheus endpoint

http://localhost:8000/metrics

Пример запросов к метрикам

# Количество ошибок в минуту
rate(telegram_bot_errors_total[1m])

# Среднее время отклика команд
rate(telegram_bot_command_duration_seconds_sum[5m]) / rate(telegram_bot_command_duration_seconds_count[5m])

# Активные пользователи
telegram_bot_active_users

# Статус бота
telegram_bot_status

🎯 Настройка алертов

Добавление нового правила алерта

from .alerts import AlertManager

# В Application или где-то еще
alert_manager = AlertManager(config, metrics)

# Добавляем новое правило
alert_manager.add_alert_rule('custom_rule', {
    'enabled': True,
    'threshold': 100,
    'cooldown': 600,  # 10 минут
    'last_alert': None
})

Отключение алерта

alert_manager.disable_alert_rule('high_error_rate')

🔧 Интеграция в код

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

from core.monitoring import measure_time, error_handler

class MyHandler(BaseHandler):
    @measure_time(metrics, 'weather_api')
    async def call_external_api(self):
        # Код API вызова
        pass

    @error_handler(metrics, 'my_handler')
    async def risky_operation(self):
        # Рискованный код
        pass

Ручная запись метрик

# Запись ошибки
metrics.record_error('DatabaseError', 'user_handler', exception)

# Запись команды
metrics.record_command('start', 'user_handler', duration)

# Запись сообщения
metrics.record_message('text')

# Обновление активных пользователей
metrics.update_active_users(150)

📊 Grafana дашборды

Рекомендуемые панели

1. Обзор ошибок

   • График количества ошибок по времени
   • Разбивка по типам ошибок
   • Топ обработчиков с ошибками

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

   • Время отклика команд
   • Среднее время API вызовов
   • Загрузка системы

3. Активность пользователей

   • Количество активных пользователей
   • Общее количество сообщений
   • Топ команд

4. Системные метрики

   • Статус бота
   • Использование памяти/CPU
   • Состояние подключений

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

{
  "name": "Telegram Bot Prometheus",
  "type": "prometheus",
  "url": "http://localhost:8000",
  "access": "proxy"
}

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

Запуск тестов мониторинга

pytest tests/test_monitoring.py -v

Имитация ошибок для тестирования

# В коде для тестирования
import time

async def test_error_scenario():
    # Имитация медленного ответа
    await asyncio.sleep(6)  # > 5 секунд для триггера алерта

    # Имитация ошибки
    raise ValueError("Test error for monitoring")

🚨 Troubleshooting

Проблемы с Prometheus

1. Метрики не собираются

   • Проверьте порт 8000
   • Убедитесь, что prometheus_client установлен

2. Высокая нагрузка

   • Уменьшите частоту сбора метрик
   • Используйте sampling для высоконагруженных endpoint'ов

Проблемы с Sentry

1. Ошибки не отправляются

   • Проверьте SENTRY_DSN
   • Убедитесь, что ENABLE_SENTRY=true
   • Проверьте сетевые настройки

2. Слишком много событий

   • Настройте фильтры в _before_send_sentry
   • Увеличьте traces_sample_rate

Проблемы с алертами

1. Алерты не приходят

   • Проверьте DEVELOPER_CHAT_ID
   • Убедитесь, что бот имеет права отправки сообщений

2. Слишком много алертов

   • Увеличьте cooldown в правилах
   • Настройте пороги срабатывания

📋 TODO для продакшена

• Настроить мониторинг ресурсов сервера (CPU, память, диск)
• Добавить health checks endpoint
• Интегрировать с внешними системами мониторинга
• Настроить retention политику для метрик и логов
• Добавить A/B тестирование алертов
• Создать runbook для реагирования на алерты

🤝 Вклад в развитие

При добавлении новых метрик или алертов:

1. Добавьте описание в эту документацию
2. Обновите тесты
3. Убедитесь в обратной совместимости
4. Протестируйте в staging окружении

📞 Поддержка

При проблемах с системой мониторинга:

1. Проверьте логи в bot.log
2. Посмотрите метрики в Prometheus
3. Проверьте настройки в Sentry
4. Обратитесь к разработчикам

---

Последнее обновление: Октябрь 2025