API мониторинга: события, временная шкала и статус¶

Эта страница - справочник по вычисляемым полям, которые REST API Topolograph рассчитывает для отслеживаемых графов: временная шкала событий (волны), status графа и object_status события. Здесь объясняется, что означает каждое вычисляемое значение.

Временная шкала событий (волны)¶

Временная шкала событий группирует события подъёма/разрыва узла/хоста в хронологические волны, чтобы можно было описать сетевой инцидент (например: «нестабильность началась в момент T на устройстве X; всплеск флапа от устройства Y; сеть сошлась в T+n»), не просматривая сотни сырых событий. Группировка вычисляется на стороне сервера.

Доступно через REST API Topolograph по адресу:

GET /api/events/{graph_time}/adjacency/timeline
    ?last_minutes=<int>       (optional)
    ?start_time=<ISO8601>     (optional, e.g. 2025-06-30T20:00:00Z)
    ?end_time=<ISO8601>       (optional)
    ?page=<int>               (optional, default 1)
    ?per_page=<int>           (optional, default 20)

Список waves постраничный; ответ включает блок pagination (page, per_page, total, total_pages).

События существуют только для графов, отслеживаемых Watcher-ом. Ответ содержит только сводки по волнам (без вложенных массивов событий). Чтобы получить отдельные события волны, повторно запросите эндпоинт API Topolograph GET /api/events/{graph_time}/adjacency с start_ts/end_ts этой волны.

Как определяются волны¶

События размещаются на одной хронологической временной шкале и разбиваются на волны по паузе между ними: новая волна начинается, когда промежуток до следующего события превышает gap_multiplier * median_gap_sec. Используется медианный промежуток (а не среднее), чтобы один длинный период затишья не искажал порог.

Поле	Значение
`gap_multiplier`	Множитель, используемый для разделения волн (по умолчанию `5`).
`median_gap_sec`	Медианное число секунд между последовательными событиями (устойчиво к всплескам).

Поля каждой волны¶

Поле	Значение
`wave_number`	Последовательный номер волны, начиная с 1.
`start_ts` / `end_ts`	Временные метки ISO 8601 (`...Z`) первого/последнего события волны. Их можно повторно использовать как `start_time`/`end_time` для получения событий волны.
`duration_sec`	Секунды от первого до последнего события волны.
`event_count`	Число событий в волне.
`distinct_devices`	Число уникальных устройств в волне.
`trigger_device`	Устройство первого события в волне.
`pattern`	Классификация волны (см. ниже).
`converged`	`true`, если каждое устройство, ушедшее в down в этой волне, восстанавливается (последующий up) в пределах запрошенного временного окна. Восстановление после `end_time` не видно, поэтому волна может показывать `converged: false`, даже если сеть позже восстановилась за пределами окна.

Паттерны волн¶

pattern классифицирует волну по тому, что произошло с состоянием устройств. Это отражает статус графа status из API Topolograph GET /api/graph/{graph_time}/status:

`pattern`	Значение	Пример	Связанный статус графа
`outage`	По крайней мере одно устройство остаётся down к концу волны (ушло вниз и не вернулось).	`R1 down` (без последующего up); `R1 down, R2 down then up` (R1 всё ещё down)	`critical`
`flap`	Всё, что ушло вниз, вернулось в пределах волны. Не зависит от числа устройств: 1 устройство down-затем-up или 100 устройств, каждое down-затем-up - оба случая `flap`.	`R1 down then up`; `R1..R100 each down then up`	`warning`
`up`	Только события up, ничего не ушло вниз в этой волне (восстановление или совершенно новое соседство).	`R1 up`, `R2 up`	`ok`

Пример ответа¶

{
  "graph_time": "10May2025_17h03m00s_7_hosts_ospfwatcher",
  "watcher_name": "demo-watcher",
  "gap_multiplier": 5,
  "median_gap_sec": 10.0,
  "waves": [
    {
      "wave_number": 1,
      "start_ts": "2025-05-10T17:09:24.707000Z",
      "end_ts": "2025-05-10T17:11:27.707000Z",
      "duration_sec": 123.0,
      "event_count": 10,
      "distinct_devices": 6,
      "trigger_device": "10.1.1.3",
      "pattern": "outage",
      "converged": false
    }
  ],
  "pagination": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1 }
}

Статус графа¶

API Topolograph GET /api/graph/{graph_time}/status возвращает общий status графа, вычисляемый на основе его связности и событий. Это аналог pattern волны на уровне всего графа:

`status`	Когда	Связанный `pattern` волны
`critical`	Граф разорван (disconnected), или узел ушёл вниз и не вернулся (затянувшийся down).	`outage`
`warning`	Граф связен, но узел ушёл вниз и снова вверх (флап), либо есть события ухода сети или изменения метрики линка.	`flap`
`ok`	Есть события, но они только up (восстановление хоста/сети), либо событий вообще нет и граф связен.	`up`
`no_monitoring_data`	Граф не отслеживается Watcher-ом, поэтому у него нет событий.	н/п

status.details также включает:

Поле	Значение
`is_monitored`	`true`, если граф питается от Watcher-а (события есть только у отслеживаемых графов).
`is_connected`	`true`, если граф топологии полностью связен.
`up_node_events` / `down_node_events`	Число событий подъёма/разрыва узла с момента сбора графа.
`all_host_up_down_events`	Число всех событий подъёма/разрыва хоста (включая восстановленные).
`network_up_down_events`	Число событий подъёма/разрыва сети (подсети).
`adjacency_cost_change_events`	Число изменений метрики линка/соседства (изменение метрики, а не разрыв).
`top_unstable_devices`	Топ-N `{device, event_count}` по убыванию (самые проблемные устройства).

`object_status` события¶

Сырые события (/adjacency, /networks) несут object_status, вычисляемый на основе изменения метрики, о котором сообщил Watcher:

`object_status`	Значение
`down`	Метрика изменилась на `-1` (соседство или сеть ушли вниз).
`up`	Метрика изменилась с `-1` на другое значение (восстановилась или появилась впервые).
`changed`	Метрика изменилась между двумя реальными значениями (изменение метрики, а не down/up).

Только события хоста up/down попадают в волны; события changed - это изменения метрики линка, и они отражаются отдельно в adjacency_cost_change_events.