# Блок 7. Наблюдаемость и аналитика

> Машинный контракт метрик и устройство sidecar-наблюдателя — в
> [инженерном справочнике](../architecture/README.md) (разделы `/metrics` и sidecar-watchdog).

## Живая Telegram-карточка задачи

Каждая задача — одна карточка в Telegram, обновляемая на каждом событии:

- текущая стадия и Plane-статус (включая человеческие гейты — видно, когда задача ждёт вас);
- строка работающего агента: роль · модель · эффорт;
- стоимость задачи нарастающим итогом (токены/доллары по каждому запуску агента);
- честные метрики времени на финише: время агентов / время ожидания человека / общее
  календарное — три независимые цифры, а не одна вводящая в заблуждение сумма;
- кликабельный номер задачи (ведёт в Plane), отметка багфикс-маршрута.

Карточка тихая (без пингов); пингуют только алерты: красный гейт, ожидание решения человека,
инциденты.

## Служебные страницы платформы

- **`GET /queue`** — человекочитаемый снимок всего конвейера: очередь и job'ы, состояние
  serial gate и заморозок, авто-лейблы, багфикс-трек, coverage, журнал уроков, фоновые
  демоны. Первая точка диагностики «что сейчас происходит».
- **`GET /metrics`** — машинный контракт для внешнего наблюдателя (версионированная схема):
  health, возраст последних событий, счётчики сбоев.
- **`GET /health`** — живость процесса.

## Sidecar-watchdog: наблюдатель отделён от наблюдаемого

Отдельный контейнер-сторож опрашивает `/metrics` платформы и шлёт алерты в **собственный**
Telegram-канал со **своим** ботом. Падение платформы, зависание очереди или протухание
событий видно даже тогда, когда сама платформа уже не может пожаловаться.

## Журнал уроков

Машинная таблица отклонений конвейера: красные гейты, ложные блокировки слияния, исчерпание
ретраев, деградации после выкладки. Каждая запись — контекст (задача, стадия, агент, репо),
первопричина и предложение. Журнал — наблюдатель (никогда не влияет на продвижение задач) и
фундамент петли самообучения платформы: уроки доступны через API и копятся для будущего
ретроспективного анализа.

## Стоимость и аналитика по агентам

Каждый запуск агента фиксирует модель, эффорт, длительность и стоимость
([модель объектов](tech-data-model.md)). Это даёт ответы на вопросы «сколько стоит задача»,
«какая роль ест бюджет», «как изменилась экономика после смены модели» — по фактам, не по
ощущениям.

---

*Что делать при инцидентах и как устроен прод — `docs/operations/` (через
[инженерный справочник](../architecture/README.md)); бизнес-взгляд на наблюдаемость —
[business.md](business.md).*