prod/infra/monitoring/README_PID_MANAGER.md

# PID Manager - Управление процессами ботов

## Описание

`pid_manager.py` - это общий модуль для управления PID файлами всех ботов в проекте. Он обеспечивает создание, отслеживание и очистку PID файлов для мониторинга состояния процессов.

## Использование

### Для новых ботов

Чтобы добавить PID мониторинг в новый бот, выполните следующие шаги:

1. **Импортируйте PID менеджер в ваш скрипт запуска:**

```python
import sys
import os

# Добавляем путь к инфраструктуре в sys.path
infra_path = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))), 'infra', 'monitoring')
if infra_path not in sys.path:
    sys.path.insert(0, infra_path)

from pid_manager import get_bot_pid_manager
```

2. **Создайте PID менеджер в начале main функции:**

```python
async def main():
    # Создаем PID менеджер для отслеживания процесса (если доступен)
    pid_manager = None
    if get_bot_pid_manager:
        pid_manager = get_bot_pid_manager("your_bot_name")  # Замените на имя вашего бота
        if not pid_manager.create_pid_file():
            logger.error("Не удалось создать PID файл, завершаем работу")
            return
    else:
        logger.info("PID менеджер недоступен, запуск без PID файла")
    
    # Ваш код запуска бота...
```

3. **Очистите PID файл при завершении:**

```python
try:
    # Ваш код работы бота...
finally:
    # Очищаем PID файл (если PID менеджер доступен)
    if pid_manager:
        pid_manager.cleanup_pid_file()
```

### Для мониторинга

Чтобы добавить новый бот в систему мониторинга:

```python
from infra.monitoring.metrics_collector import MetricsCollector

# Создаем экземпляр коллектора метрик
collector = MetricsCollector()

# Добавляем новый бот в мониторинг
collector.add_bot_to_monitoring("your_bot_name")

# Теперь можно проверять статус
status, uptime = collector.check_process_status("your_bot_name")
```

## Структура файлов

```
prod/
├── infra/
│   └── monitoring/
│       ├── pid_manager.py          # Основной модуль
│       ├── metrics_collector.py    # Мониторинг процессов
│       └── README_PID_MANAGER.md   # Эта документация
├── bots/
│   ├── telegram-helper-bot/
│   │   └── run_helper.py           # Использует PID менеджер
│   └── your-new-bot/
│       └── run_your_bot.py         # Будет использовать PID менеджер
├── helper_bot.pid                  # PID файл helper_bot
├── your_bot.pid                    # PID файл вашего бота
└── .gitignore                      # Содержит *.pid
```

## API

### PIDManager

- `create_pid_file()` - Создает PID файл
- `cleanup_pid_file()` - Удаляет PID файл
- `is_running()` - Проверяет, запущен ли процесс
- `get_pid()` - Получает PID из файла

### Функции

- `get_bot_pid_manager(bot_name)` - Создает PID менеджер для бота
- `create_pid_manager(process_name, project_root)` - Создает PID менеджер с настройками

## Примеры

### Простой бот

```python
import asyncio
from pid_manager import get_bot_pid_manager

async def main():
    # Создаем PID менеджер
    pid_manager = get_bot_pid_manager("simple_bot")
    if not pid_manager.create_pid_file():
        print("Не удалось создать PID файл")
        return
    
    try:
        # Ваш код бота
        print("Бот запущен...")
        await asyncio.sleep(3600)  # Работаем час
    finally:
        # Очищаем PID файл
        pid_manager.cleanup_pid_file()

if __name__ == '__main__':
    asyncio.run(main())
```

### Бот с обработкой сигналов

```python
import asyncio
import signal
from pid_manager import get_bot_pid_manager

async def main():
    pid_manager = get_bot_pid_manager("advanced_bot")
    if not pid_manager.create_pid_file():
        return
    
    # Флаг для корректного завершения
    shutdown_event = asyncio.Event()
    
    def signal_handler(signum, frame):
        print(f"Получен сигнал {signum}, завершаем работу...")
        shutdown_event.set()
    
    # Регистрируем обработчики сигналов
    signal.signal(signal.SIGINT, signal_handler)
    signal.signal(signal.SIGTERM, signal_handler)
    
    try:
        # Ваш код бота
        await shutdown_event.wait()
    finally:
        pid_manager.cleanup_pid_file()

if __name__ == '__main__':
    asyncio.run(main())
```

## Примечания

- PID файлы создаются в корне проекта
- Все PID файлы автоматически игнорируются Git (см. `.gitignore`)
- PID менеджер автоматически обрабатывает сигналы SIGTERM и SIGINT
- При завершении процесса PID файл автоматически удаляется
- Система мониторинга автоматически находит PID файлы в корне проекта

## Изолированный запуск

При запуске бота изолированно (без доступа к основному проекту):

- PID менеджер автоматически не создается
- Бот запускается без PID файла
- В логах появляется сообщение "PID менеджер недоступен (изолированный запуск), PID файл не создается"
- Это позволяет запускать бота в любой среде без ошибок

## Автоматическое определение

Система автоматически определяет доступность PID менеджера:

1. **В основном проекте**: PID менеджер доступен, создается PID файл для мониторинга
2. **Изолированно**: PID менеджер недоступен, бот работает без PID файла
3. **Fallback**: Если PID менеджер недоступен, бот продолжает работать нормально