bottohelp/README_DEVELOPER.md

👨‍💻 Руководство для разработчика

🔧 Поддержка и развитие системы мониторинга

📋 Обзор архитектуры

telegram_bot/
├── core/
│   ├── monitoring.py      # 📊 Метрики + Sentry + Логи
│   ├── alerts.py         # 🚨 Система алертов
│   └── application.py    # 🎯 Главное приложение (обновлено)
├── handlers/             # 🎮 Обработчики (обновлены)
├── tests/               # 🧪 Тесты мониторинга
└── docs/               # 📚 Документация

🚀 Добавление новых метрик

В MetricsCollector (core/monitoring.py):

# Добавьте новую метрику в __init__
self.new_metric = Counter('telegram_bot_new_feature_total', 'Description')

# Используйте в коде
metrics.new_metric.labels(type='example').inc()

В handlers:

# Автоматически через декораторы
@measure_time(metrics, 'api_name')
async def some_api_call(self):
    pass

@error_handler(metrics, 'handler_name')
async def risky_operation(self):
    pass

🚨 Добавление новых алертов

В AlertManager (core/alerts.py):

# Добавьте правило в __init__
self.alert_rules['new_alert'] = {
    'enabled': True,
    'threshold': 100,
    'cooldown': 300,
    'last_alert': None
}

# Добавьте метод проверки
async def _check_new_alert(self):
    if some_condition:
        await self._trigger_alert('new_alert', 'Message', {'data': value})

Настройка уведомлений:

# Добавьте обработчик в __init__
self.alert_handlers.append(self._send_slack_alert)

# Реализуйте метод
async def _send_slack_alert(self, alert_type, message, extra_data):
    # Отправка в Slack
    pass

📊 Добавление новых обработчиков

Создание нового handler:

from handlers.base_handler import BaseHandler

class NewHandler(BaseHandler):
    def __init__(self, config, metrics, service):
        super().__init__(config, metrics)  # Передача metrics обязательна!
        self.service = service

    def get_command_handlers(self):
        return {
            'new_command': self.handle_new_command
        }

Регистрация в Application:

# В core/application.py
from handlers.new_handler import NewHandler

# В _initialize_handlers
handlers['new'] = NewHandler(self.config, self.metrics, NewService())

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

Запуск тестов:

# Все тесты мониторинга
pytest tests/test_monitoring.py -v

# Интеграционные тесты
python test_monitoring_integration.py

# Финальное тестирование
python final_test.py

# Автонастройка
python setup_monitoring.py

Добавление новых тестов:

# В tests/test_monitoring.py
def test_new_metric(metrics):
    """Тест новой метрики"""
    # Тестовая логика
    assert True

📚 Обновление документации

При добавлении функций:

1. Обновите MONITORING.md
2. Добавьте примеры в README_MONITORING.md
3. Обновите README_SYSTEM.md с новыми файлами

Структура документации:

• MONITORING.md - технические детали
• README_MONITORING.md - для пользователей
• GLITCHTIP_SETUP.md - настройка
• START_MONITORING.md - пошаговое руководство

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

Добавление новых настроек:

# В core/config.py
@dataclass
class BotConfig:
    # ... существующие поля
    new_feature_enabled: bool = False

# В _load_from_environment
self._config['new_feature_enabled'] = self._str_to_bool(
    os.getenv('NEW_FEATURE_ENABLED', 'false')
)

🚀 Развертывание

Продакшен рекомендации:

1. GlitchTip:

   docker-compose up -d
   # Настройка HTTPS, backup, scaling
   

2. Prometheus:

   # Отдельный сервер Prometheus
   # Конфигурация scraping
   

3. Grafana:

   docker run -d -p 3000:3000 grafana/grafana
   # Дашборды для телеграм-бота
   

4. Мониторинг мониторинга:

   • Health checks для GlitchTip
   • Алерты на недоступность метрик
   • Backup конфигурации

🐛 Отладка

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

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

   curl http://localhost:8000/metrics
   # Проверьте порт и firewall
   

2. GlitchTip не работает:

   docker-compose logs glitchtip
   # Проверьте логи и конфигурацию
   

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

   • Проверьте DEVELOPER_CHAT_ID
   • Убедитесь в правах бота
   • Проверьте webhook URL

4. Логи не записываются:

   tail -f bot.log
   # Проверьте права на файл
   

📈 Мониторинг производительности

Оптимизация:

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

Профилирование:

import cProfile

# В коде
pr = cProfile.Profile()
pr.enable()
# Ваш код
pr.disable()
pr.print_stats()

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

1. Атомарные изменения:

   • Тестируйте каждый новый компонент
   • Документируйте изменения
   • Обновляйте тесты

2. Безопасность:

   • Не логируйте чувствительную информацию
   • Валидируйте все входные данные
   • Используйте HTTPS для webhook

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

   • Асинхронные операции для алертов
   • Кеширование частых метрик
   • Оптимизация запросов к БД

4. Поддерживаемость:

   • Следуйте существующей архитектуре
   • Добавляйте тесты для новых функций
   • Документируйте все изменения

📞 Поддержка команды

Для новых разработчиков:

1. Изучите MONITORING.md
2. Запустите setup_monitoring.py
3. Пройдите final_test.py
4. Ознакомьтесь с примерами в коде

Структура кода:

• Каждый модуль имеет четкую ответственность
• Используйте type hints
• Добавляйте docstrings
• Следуйте PEP 8

🎯 Будущие улучшения

• Интеграция с Grafana
• Machine learning для анализа ошибок
• Автоматическое создание дашбордов
• A/B тестирование алертов
• Интеграция с системами CI/CD

📋 Контрольные списки

Перед коммитом:

• Тесты проходят
• Документация обновлена
• Код reviewed
• Никаких TODO в коде

Перед развертыванием:

• Все зависимости установлены
• Конфигурация проверена
• Тесты в staging пройдены
• Backup создан

---

Система мониторинга готова для развития и поддержки! 🚀

Для разработчиков: следуйте этим рекомендациям для поддержания качества системы