ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Написать postmortem для retrieval degradation

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

Научиться системно анализировать инциденты, связанные с деградацией качества retrieval в RAG-системе. Вы научитесь собирать и интерпретировать логи и метрики, находить root cause, разрабатывать fix и документировать инцидент в формате postmortem. В результате вы сможете сократить время обнаружения инцидента (MTTD) до <10 минут за счёт чётко прописанных шагов диагностики.

Ключевой результат Написанный и принятый командой postmortem-документ, который позволяет новому инженеру разобраться в инциденте за <10 минут.

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

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

1. Возьмите production-подобную RAG-систему (или разверните из шаблона).
2. В момент времени T0 выполните одно из действий:
   • Уменьшите top_k с 10 до 2 в конфиге retrieval.
   • Смените embedding-модель на заведомо слабую (например, all-MiniLM-L6-v2 → paraphrase-albert-small-v2).
   • Внесите шумные документы в векторную БД (например, 20% документов с рандомными эмбеддингами).
3. Зафиксируйте время T0 и продолжайте генерировать тестовые запросы к RAG в течение 30–60 минут.
4. Соберите метрики "до" (T0-1h) и "после" (T0+1h).

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

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

Этап 1: Обнаружение и первичная диагностика (20–30 минут)

Действия

1. Зафиксируйте момент деградации
   • Откройте Grafana-дашборд с метриками retrieval.
   • Определите временную метку, когда hit rate упал ниже порога (например, <0.7 от baseline).
   • Запишите: time_start: YYYY-MM-DD HH:MM, time_end: HH:MM (если уже исправлено).
2. Соберите первичные данные
   • Выгрузите метрики за 1 час до и во время инцидента.
   • Посчитайте процент затронутых запросов: (кол-во запросов с низким hit rate / общее кол-во запросов) * 100.
3. Проверьте очевидные причины
   • Просмотрите Git-логи за последние 24 часа (изменения кода, конфига).
   • Проверьте статус all health checks (векторная БД, LLM API, Redis).
   • Запросите инфу о деплоях (rolling update, canary).

Ожидаемый результат этапа Заполненный раздел "Обнаружение" в postmortem, гипотеза (например: "вероятно, изменение конфига chunking").

Этап 2: Глубокий анализ (1–1.5 часа)

Действия

Ключевые вопросы для анализа (запишите в postmortem):

1. Какая конкретная метрика упала и на сколько процентов?
2. Это падение произошло резко (step) или постепенно (drift)?
3. Затронуло ли оно все типы запросов (вопросы по коду vs общие факты) или только определённые?
4. Было ли аналогичное падение в прошлом? (сверьтесь с базой postmortem)
5. Можно ли воспроизвести проблему на staging-окружении с теми же параметрами?

Ожидаемый результат этапа Найденная root cause (например, "снижение top_k с 10 до 2 в production-конфиге после мержа PR #142").

Этап 3: Устранение и верификация (30–60 минут)

Действия

1. Разработайте fix
   • Откатите конфиг (git revert — если это была ошибка кода).
   • Переиндексируйте документы (если проблема в эмбеддингах).
   • Настройте alert на hit rate <0.7 (чтобы MTTD стало <10 мин).
2. Примените fix на staging
   • Скопируйте снапшот векторной БД с production.
   • Запустите те же тестовые запросы, убедитесь, что метрики вернулись к baseline.
3. Примените fix на production
   • Используйте blue-green или canary (10% → 50% → 100%).
4. Зафиксируйте время восстановления time_resolved.
5. Проверьте метрики через 1 час hit rate должен быть в пределах 5% от baseline.

Важно Задокументируйте каждый шаг верификации — это будет частью postmortem.

Ожидаемый результат этапа Система восстановлена, метрики в норме.

Этап 4: Написание postmortem (1–2 часа)

Структура postmortem (обязательные разделы):

# POSTMORTEM: [Название инцидента]

## Информация об инциденте
- ID инцидента PM-YYYY-MM-DD-001
- Дата и время YYYY-MM-DD HH:MM UTC
- Длительность X часов Y минут
- [[Вики/severity|Severity]] P0/P1/P2/P3
- Автор [Имя]
- Рецензент [Имя]

## Executive Summary
[Кратко для менеджмента: что случилось, как быстро обнаружили, какой fix применили]

## Влияние на пользователей
- Количество затронутых запросов: X%
- Падение hit rate: 0.92 → 0.45 (на 51%)
- Ухудшение времени ответа: с 400ms до 1.2s (если применимо)
- Наличие жалоб: да/нет (ссылка на тикеты)

## Таймлайн инцидента
| Время (UTC) | Событие | Данные/Метрика |
|-------------|---------|----------------|
| 10:00 | Baseline stable | hit_rate=0.92, recall@5=0.81 |
| 10:05 | Изменение конфига в PR #142 merge | — |
| 10:12 | Hit rate начал падать | 0.92 → 0.85 (Grafana alert) |
| 10:15 | Первичная диагностика — гипотеза: смена top_k | top_k=2 (логи конфига) |
| 10:20 | Root cause confirmed | — |
| 10:25 | Fix: git revert #142, deploy | — |
| 10:30 | Метрики вернулись к 0.90 | — |
| MTTD (обнаружение): | 3 минуты (10:12 – 10:15) | — |
| MTTR (восстановление): | 25 минут (10:05 – 10:30) | — |

## Root Cause Analysis
[Текст: "Причиной падения hit rate стало изменение параметра top_k с 10 до 2 в конфиге retrieval, вызванное дефектом в CI-пайплайне, который не прогонял тесты на качестве retrieval."]

## Fix и верификация
- Fix откат конфига до top_k=10 + добавление теста на hit rate в CI.
- [[Вики/Check|Верификация]] staging показал hit_rate=0.91, production — 0.90 (baseline 0.92).
- **Мониторинг:** добавлен Prometheus-правило `hit_rate < 0.7` → PagerDuty alert.

## Action Items (уроки)
| # | Действие | Owner | Статус | Дедлайн |
|---|----------|-------|--------|---------|
| 1 | Добавить e2e-тест для retrieval | @alice | ✅ Done | 01.04 |
| 2 | Настроить alert на hit rate | @bob | 🟡 In progress | 05.04 |
| 3 | Провести code review конфигов | @charlie | ❌ Not started | 10.04 |

## Приложения
- Ссылка на дашборд в момент инцидента.
- CSV с метриками до/после.
- Логи retrieval за 10:00–11:00.

Ожидаемый результат этапа Готовый файл postmortem-YYYY-MM-DD.md, сохранённый в git-репозиторий wiki.

Этап 5: Представление и коллективное обсуждение (30–40 минут)

Действия

1. Откройте postmortem на командном ревью (в Slack, в issue, на синхронной встрече).
2. Пройдитесь по всем разделам, запросите обратную связь.
3. При необходимости добавьте/скорректируйте action items.
4. Убедитесь, что MTTD (<10 мин) действительно достижимо — проверьте, что alert сработает за это время.
5. Закрепите postmortem в базе знаний, привяжите к вопросу в базе (например, #512).

Ожидаемый результат этапа Принятый и опубликованный postmortem с как минимум 3-мя action items.

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

• Postmortem содержит все обязательные разделы (Executive Summary, Impact, Timeline, RCA, Fix, Action Items).
• Во вступлении указаны точные метрики "до" и "после" (числа, проценты, единицы измерения).
• Таймлайн имеет временные метки с шагом ≤5 минут.
• Root cause выделена и обоснована (не гипотеза, а подтверждённая причина).
• Приведены ссылки на дашборд, логи, коммиты, используемые в анализе.
• Action items назначены на владельцев с дедлайнами.
• MTTD (время обнаружения) документально не превышает 10 минут (от момента деградации до первого алерта/осознания).
• Postmortem проверен коллегой (peer review) и содержит комментарии рецензента.
• Документ сохранён в репозиторий wiki (Markdown) и доступен команде.
• Добавлен или обновлён Prometheus-алерт, который позволил бы обнаружить аналогичную проблему за <10 минут.

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

Основной артефакт Файл postmortem-YYYY-MM-DD-retrieval-degradation.md (или аналогичное название) в формате Markdown, расположенный в репозитории технической документации (например, docs/postmortems/).

Содержание файла

• Полная структура из Этапа 4, включая заполненные данные (или плейсхолдеры, если инцидент симулирован).
• Реальные числа и ссылки на логи/метрики (для симуляции — сгенерированные, но правдоподобные).
• Action items с ответственными и дедлайнами.
• Чеклист проверки (если принят командой — отметки о выполнении).

Дополнительные результаты (опционально):

• Prometheus-правило для алерта (hit_rate < 0.7).
• E2e-тест на качество retrieval (Python + RAGAS).
• Раздел в wiki "Как писать postmortem" (на основе шаблона).

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

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

Примечание Для первого раза заложите +2 часа на ознакомление с инструментами и настройку окружения. Если симулируете инцидент — добавьте ещё 1 час на подготовку сценария.

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

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

• Я убедился, что MTTD (время от деградации до алерта/обнаружения) в моём постмортеме не превышает 10 минут.
• Я собрал и включил в документ конкретные числа метрик (hit rate, recall, duration) до и после инцидента.
• Я явно описал root cause и не оставил неопределённости.
• Все action items имеют ответственных и реалистичные дедлайны.
• Я получил ревью от коллеги и учёл все замечания.
• Постмортем сохранён в wiki и доступен команде через поиск.