ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Настроить coordination metrics для мультиагентной системы

1. Цель задачи

Разработать и внедрить набор метрик для оценки координации между агентами в мультиагентной системе. Метрики должны включать количество коллабораций (число взаимодействий), успешность (доля кооперативных действий, завершённых без ошибок) и латентность (время от отправки запроса до получения ответа). Результатом является работающий дашборд в Grafana, который в реальном времени отображает эти метрики и позволяет анализировать эффективность мультиагентного взаимодействия.

Ключевой результат Дашборд coordination с тремя панелями: «Количество коллабораций (счётчик)», «Успешность координации (%)» и «Latency (p50, p95, p99)», обновляющийся с интервалом не более 5 секунд.

2. Исходные данные

Если нет реального инструмента — симулируем:

1. Создаём Python-скрипт sim_agents.py, который запускает 3–5 потоков, каждый эмулирует агента.
2. Агенты обмениваются сообщениями через очередь в памяти (например, queue.Queue).
3. Каждое сообщение логируется с временной меткой.
4. Параллельно запускаем скрипт sim_metrics.py, который читает логи и вычисляет метрики каждые 2 секунды.
5. Экспонируем метрики через HTTP endpoint (имитация Prometheus exporter) на порту 8000.
6. Grafana подключается к этому endpoint как к источнику Prometheus.

3. Технологический стек

4. Этапы выполнения

Этап 1: Инструментирование мультиагентной системы (3 часа)

Действия

1. В коде каждого агента (например, класс Agent) добавить логирование ключевых событий:
   • Отправка запроса другому агенту (send_request)
   • Получение ответа (receive_response)
   • Ошибка таймаута или некорректного ответа (failure)
2. Каждое событие должно содержать: agent_id, target_agent_id, event_type, timestamp, message_id, duration.
3. Логи писать в JSON-формате в файл agent_events.log.
4. Написать модуль metric_collector.py, который парсит этот лог каждые 2 секунды и вычисляет агрегаты:
   • collaboration_total — количество отправленных запросов (счётчик)
   • collaboration_success_rate — доля успешных ответов (гистограмма или gauge)
   • collaboration_latency_ms — время между send_request и receive_response (гистограмма)
5. Использовать prometheus_client для создания метрик:

   from prometheus_client import Counter, Histogram, Gauge, start_http_server
   collab_total = Counter('collaboration_total', 'Total collaboration requests')
   success_rate = Gauge('collaboration_success_rate', 'Fraction of successful collaborations')
   latency = Histogram('collaboration_latency_ms', 'Latency of collaboration in ms',
                       buckets=[10, 50, 100, 200, 500, 1000])
   

Ожидаемый результат этапа

• Файл metrics_exporter.py, запускающий HTTP-сервер на порту 8000 с метриками.
• Скрипт симуляции run_sim.py, который генерирует 100 коллабораций с разными таймингами (0.01–0.5 с) и случайной долей ошибок (~10%).

Этап 2: Развёртывание Prometheus и Grafana (2 часа)

Действия

1. Создать docker-compose.yml с двумя сервисами:

   prometheus:
     image: prom/prometheus:v2.45.0
     ports: ["9090:9090"]
     volumes: ["./prometheus.yml:/etc/prometheus/prometheus.yml"]
   grafana:
     image: grafana/grafana:10.2.0
     ports: ["3000:3000"]
     environment: [GF_INSTALL_PLUGINS=grafana-piechart-panel]
   

2. Настроить prometheus.yml для сбора метрик с localhost:8000 (хост машины) с интервалом 5 секунд.
3. Запустить контейнеры: docker-compose up -d.
4. Проверить, что Prometheus видит target (status UP) на http://localhost:9090/targets.
5. В Grafana добавить источник данных Prometheus (URL: http://prometheus:9090).
6. Импортировать базовый дашборд (ID 1860) или создать пустой.

Ожидаемый результат этапа

• Работающие Prometheus и Grafana.
• Данные метрик отображаются в Explore Grafana (например, запрос collaboration_total).

Этап 3: Создание дашборда coordination (3 часа)

Действия

1. В Grafana создать новый дашборд с именем «Coordination Metrics».
2. Добавить три панели:
   • Panic 1: Общее количество коллабораций
     • Тип: Stat. Запрос: increase(collaboration_total[5m]). Отображение: текущее значение и темп.
   • Panic 2: Успешность координации
     • Тип: Gauge. Запрос: collaboration_success_rate (gauge от 0 до 1). Единица: процент (умножить на 100 в Transform).
   • Panic 3: Латентность (p50, p95, p99)
     • Тип: Time series. Запросы:
       • histogram_quantile(0.50, sum(rate(collaboration_latency_ms_bucket[2m])) by (le))
       • histogram_quantile(0.95, ...)
       • histogram_quantile(0.99, ...)
     • Легенда: p50, p95, p99.
3. Настроить временной диапазон «Last 15 minutes», auto-refresh 5s.
4. Добавить переменную agent (query: label_values(collaboration_total, agent)), чтобы фильтровать по конкретному агенту (необязательно).
5. Сохранить дашборд (ID дашборда: 295).

Ожидаемый результат этапа

• Дашборд с 3-мя панелями, реагирующими на изменение метрик при запуске симуляции.

Этап 4: Тестирование и верификация (1.5 часа)

Действия

1. Запустить симуляцию коллабораций (run_sim.py) с разными параметрами:
   • Нормальный режим: 50 коллабораций, доля ошибок 5%.
   • Нагрузка: 200 коллабораций, latency 0.1–1 с, ошибки 20%.
   • Сбой: на 10 секунд отключить агента B.
2. Наблюдать изменения на дашборде.
3. Сравнить значения метрик с эталонными (по логам).
4. Написать скрипт validate_metrics.py, который проверяет:
   • collaboration_total совпадает с числом уникальных message_id.
   • collaboration_success_rate = успешные/(успешные+ошибки) с точностью 1%.
   • collaboration_latency_ms перцентили совпадают с перцентилями из логов (допуск 20% для p99 из-за сглаживания).
5. Задокументировать результаты в файле test_report.md.

Ожидаемый результат этапа

• Подтверждение корректности всех метрик.
• Отчёт с графиками отклонений (если есть).

Этап 5: Документация и финализация (0.5 часа)

Действия

1. Написать README.md с инструкцией по запуску системы.
2. Приложить конфигурационные файлы (prometheus.yml, grafana-dashboard.json (экспорт дашборда)).
3. Добавить описание архитектуры: компоненты, потоки данных.
4. Указать метрики и их PromQL-запросы.

Ожидаемый результат этапа

• Папка проекта с кодом, конфигами, дашбордом (JSON) и документацией.

5. Критерии приемки (Definition of Done)

• Дашборд Grafana отображает метрики в реальном времени (обновление каждые 5 секунд).
• Панель «Количество коллабораций» показывает точный счётчик, увеличивающийся при каждом запросе.
• Панель «Успешность координации» в процентах соответствует расчёту по логам (отклонение < 2%).
• Панель «Latency» содержит три временных ряда (p50, p95, p99), значения совпадают с эталонными в пределах 10% (для p99 — 20%).
• При симуляции сбоя (отключение агента) метрика success_rate падает, а latency возрастает.
• Все метрики экспонируются через /metrics и видны в Prometheus (target UP).
• Код инструментирования не изменяет базовую логику агентов (работает как overlay).
• Написана документация (README) с инструкцией по запуску и воспроизведению.

6. Ожидаемый результат

Основной артефакт Дашборд Grafana (экспортированный JSON) с тремя панелями метрик coordination.

Дополнительно

• Исходный код мультиагентной системы (если создавался с нуля) или файл-патч для инжекции метрик.
• Конфиг Prometheus (prometheus.yml).
• Файл docker-compose.yml для инфраструктуры мониторинга.
• Скрипты симуляции и валидации.
• Отчёт о тестировании (test_report.md).

7. Возможные сложности и их решение

8. Бюджет времени (оценка)

Примечание Для первого выполнения может потребоваться до 14 ч из-за настройки окружения и отладки.

9. Связанные вопросы из базы знаний

10. Чек-лист самопроверки

• Я определил три метрики (кол-во, успешность, latency) и корректно их инструментировал.
• Я запустил симуляцию и убедился, что дашборд обновляется каждые 5 секунд.
• Я проверил точность метрик с помощью скрипта валидации.
• Я экспортировал дашборд в JSON и сохранил конфиги в репозиторий.
• Я написал README с шагами для воспроизведения результата.