Спецификация шаблонов модели здоровья

Эта спецификация описывает правила заполнения файлов шаблонов модели здоровья.

Статусы

Каждая сущность панели может принимать один из четырёх статусов, определяющих также внешний вид соответствующего индикатора или панели:

  • gray — данные не поступают.

  • green — данные поступают, но показатели находятся в допустимых значениях.

  • yellow — данные поступают, но показатели превышают допустимые значения.

  • red — у этого статуса может быть одно из двух значений:

    • данные не поступают, и это само по себе является сигналом проблемы;

    • данные поступают, и показатели превышают критичные значения.

Типы данных

При описании полей для типов возможных значений используются следующие обозначения:

  • array<T> — массив элементов типа <T>;

  • boolean — логическое;

  • integer — целое число;

  • map<string,T> — словарь, где ключ является строкой, а значение имеет тип <T>;

  • string — строка.

Встроенные переменные

Механизм шаблонов позволяет использовать встроенные переменные. Для обращения к переменной используйте следующий синтаксис:

${variable}

Здесь variable — имя переменной.

Доступны следующие переменные:

  • pak_id — идентификатор ПАК.

  • entity_id — текущая сущность при расчёте статусов и индикаторов.

  • id и meta.<поле> — поля текущей сущности при рендере title и subtitle.

Элементы типа repeat_for имеют следующие особенности:

  • Переменные _module_id, _node_id и другие формируются из меток, указанных в repeat_for.id_field.

  • В качестве имён переменных могут быть использованы любые метки, которые возвращает запрос в repeat_for.list_query.

  • Переменная должна существовать в данных, иначе раскрытие панели будет некорректным.

Структура шаблона

Каждый шаблон представляет собой YAML-файл со следующей структурой:

---
uid: mbd_p
title: МПД.П
version: v1.0
schema_version: "1.1"
refresh_interval: 30

panels:
  # Панели

relationships:
  # Взаимосвязи между панелями

aggregations:
  # Правила агрегации

Особенности заполнения шаблона:

  • Комбинация значений полей uid и version в каждом шаблоне должна быть уникальной.

  • В блоке panels должна быть хотя бы одна запись.

aggregations

Блок aggregations содержит список правил агрегации. Каждое правило может содержать следующие поля:

  • condition

    Требования к срабатыванию условий.

    Тип: string.

    Возможные значения:

    • ALL — должны быть выполнены одновременно все условия;

    • ANY — должно быть выполнено хотя бы одно условие.

  • depends_on

    Список идентификаторов зависимых панелей.

    Тип: array<string>.

    Это поле обязательно для заполнения.

  • target

    Идентификатор целевой панели

    Тип: string.

    Это поле обязательно для заполнения.

  • type

    Название типа зависимости.

    Тип: string.

    Возможное значение: dependency.

panels

Блок panels содержит список записей, описывающих панели. Каждая панель может содержать следующие поля:

  • card_template

    Шаблон карточки панели.

    Тип: card_template.

    Это поле обязательно для заполнения для панелей с type=grid.

  • counters

    Псевдоним для entities в шаблонах со схемой версии 1.0.

    Тип: array<entity_counter>.

  • entities

    Вложенные счётчики сущности. Счётчик может содержать ссылки на дочернюю панель через поле query.

    Тип: array<entity_counter>.

  • entity_fields

    Поля для совместимости со схемой версии 1.0. В схеме версии 1.1 чаще используется сочетание id и repeat_for.id_field.

    Тип: entity_fields.

  • id

    Идентификатор панели.

    Тип: string.

    Значение может содержать ссылки на переменные, например, module-${_module_id}. Однако, после раскрытия repeat_for итоговые значения id должны быть уникальными.

    Это поле обязательно для заполнения.

  • indicators

    Индикаторы состояния по числовым рядам.

    Тип: array<indicator>.

  • list_query

    PromQL- или MetricQL-запрос, возвращающий временные ряды для сущностей панели.

    Тип: string.

    Как правило, одна сущность соответствует одному ряду после группировки по идентификатору сущности.

    Это поле обязательно для заполнения для панелей с type=list.

  • meta

    Список меток, которые нужно перенести из временного ряда в поле meta сущности.

    Тип: array<meta_item>.

  • panel_type

    Семантический тип панели. Значение этого поля влияет на фильтрацию в API и на выбор ID-поля сущности по умолчанию (через внутреннее соответствие panel_type полю label).

    Тип: string.

    Возможные значения:

    • comm — коммутатор;

    • connections — подключения;

    • hw_node — аппаратный узел;

    • interconnect — сеть интерконнект;

    • management — менеджмент-сеть;

    • module — модуль ПАК;

    • node — узел ПАК;

    • pak — ПАК;

    • pg_service — сервис PostgreSQL;

    • public — сеть внешнего доступа;

    • tps — количество транзакций в секунду в кластере PostgreSQL;

    • vip — Virtual IP;

    • vm — виртуальная машина.

  • repeat_for

    Правило размножения панелей по результату запроса.

    Тип: repeat_for.

  • row_template

    Шаблон строки панели.

    Тип: row_template.

    Это поле обязательно для заполнения для панелей с type=list.

  • status_query

    Запрос, по которому определяется статус панели. Фактическое поведение зависит от возвращаемых меток.

    Тип: string.

    Особенности работы поля:

    • Если запрос возвращает метку severity со значением critical или warning, итоговый статус рассчитывается следующим образом:

      • critical — red;

      • warning — yellow;

      • во всех остальных случаях — green.

    • Если запрос не удаётся выполнить, или не удаётся сопоставить сущности, итоговый статус — gray.

    • Для ALERTS есть оптимизированный путь обработки.

    • Если в результатах запроса есть дублирование оповещений, добавьте в запрос агрегацию, например:

      max by (_node_id, alertname, severity, _cids) (ALERTS{_node_id="${entity_id}", ...})

    В max by обязательно сохраняйте значение label сущности панели, иначе движок не сможет привязать алерт к entity, и статус может стать gray.

    Это поле обязательно для заполнения для панелей, имеющих статус.

  • title

    Заголовок панели в веб-интерфейсе.

    Тип: string.

  • type

    Тип панели.

    Тип: string.

    Возможные значения:

    • grid — набор карточек;

    • list — список сущностей;

    • stat — единственное значение.

card_template

Элементы типа card_template могут содержать следующие поля:

  • details

    Дополнительные поля.

    Тип: map<string,string>.

  • indicator

    Источник итогового статуса.

    Тип: boolean.

    Возможные значения:

    • true — источником итогового статуса является indicators. Отсутствие данных считается критической проблемой и поднимает итоговый статус сущности до red.

    • false — источником итогового статуса является status_query, индикаторы добавляются поверх.

    Это поле обязательно для заполнения.

  • subtitle

    Подзаголовок карточки в веб-интерфейсе.

    Тип: string.

  • title

    Заголовок карточки в веб-интерфейсе.

    Тип: string.

    Это поле обязательно для заполнения.

  • tooltip

    Подсказка для карточки в веб-интерфейсе.

    Тип: string.

entity_counter

Элементы типа entity_counter могут содержать следующие поля:

  • id

    Идентификатор счётчика.

    Тип: string.

  • query

    PromQL-запрос, MetricQL-запрос или ссылка на id панели.

    Тип: string.

  • thresholds

    Настройки пороговых значений.

    Тип: thresholds.

  • title

    Заголовок элемента в веб-интерфейсе.

    Тип: string.

    Это поле обязательно для заполнения.

entity_fields

Элементы типа entity_fields могут содержать следующие поля:

  • group_by

    Правило дополнительной группировки.

    Тип: string.

  • id

    Метка ряда, которая задаёт идентификатор сущности.

    Тип: string.

    Это поле обязательно для заполнения.

  • meta

    Мета-поля сущности.

    Тип: array<meta_item>.

indicator

Элементы типа indicator могут содержать следующие поля:

  • id

    Идентификатор индикатора.

    Тип: string.

    Это поле обязательно для заполнения.

  • query

    PromQL- или MetricQL-выражение.

    Тип: string.

    Это поле обязательно для заполнения.

  • thresholds

    Правила вычисления пороговых значений.

    Тип: thresholds.

  • title

    Подпись индикатора в веб-интерфейсе.

    Тип: string.

meta_item

Элементы типа meta_item могут содержать следующие поля:

  • name

    Ключ, который попадёт в entity.meta.

    Тип: string.

    Это поле обязательно для заполнения.

  • source

    Название метки в ряду list_query для выбора значения.

    Тип: string.

    Это поле обязательно для заполнения.

repeat_for

Элементы типа repeat_for могут содержать следующие поля:

  • id_field

    Название метки ряда, значение которой станет идентификатором итерации.

    Тип: string.

    Это поле обязательно для заполнения.

  • list_query

    Запрос, который возвращает набор значений для раскрытия панели.

    Тип: string.

    Это поле обязательно для заполнения.

  • source

    list_query или id уже объявленной панели.

    Тип: string.

    Это поле обязательно для заполнения.

row_template

Элементы типа row_template могут содержать следующие поля:

  • details

    Дополнительные поля.

    Тип: map<string,string>.

  • indicator

    Источник итогового статуса.

    Тип: boolean.

    Возможные значения:

    • true — источником итогового статуса является indicators. Отсутствие данных считается критической проблемой и поднимает итоговый статус сущности до red.

    • false — источником итогового статуса является status_query, индикаторы добавляются поверх.

    Это поле обязательно для заполнения.

  • subtitle

    Подзаголовок строки.

    Тип: string.

  • title

    Заголовок строки.

    Тип: string.

    Это поле обязательно для заполнения.

thresholds

Элементы типа thresholds могут содержать следующие поля:

  • critical

    Правило для порога critical.

    Тип: string.

  • warning

    Правило для порога warning.

    Тип: string.

    Правило имеет вид строки, состоящий из оператора сравнения и числового значения, например:

    # ...
    thresholds:
      critical: >= 90
      warning: >= 80

    Возможные операторы сравнения:

    • >= — больше или равно;

    • ⇐ — меньше или равно;

    • > — больше;

    • < — меньше;

    • == — равно;

    • != — не равно.

refresh_interval

Длительность в секундах периода обновления статуса панелей.

Тип: integer.

relationships

Блок relationships описывает взаимосвязи между панелями.

Элементы типа relationships могут содержать следующие поля:

  • from

    Идентификатор родительской панели.

    Тип: string.

    Это поле обязательно для заполнения.

  • label

    Подпись к связи, отображаемая в веб-интерфейсе.

    Тип: string.

  • to

    Идентификатор дочерней панели.

    Тип: string.

    Это поле обязательно для заполнения.

schema_version

Номер версии схемы, которой соответствует шаблон.

Тип: string.

Значение в этом поле влияет на то, каким образом Геном обрабатывает значения других полей.

Возможные значения:

  • 1.0 — для старых шаблонов;

  • 1.1 — для новых шаблонов.

title

Название шаблона, которое будет выводиться в веб-интерфейсе.

Тип: string.

uid

Код типа ПАК.

Тип: string.

Возможные значения:

  • base — базовый;

  • constructor — конструктор ПАК;

  • mbd_g — МБД.Г;

  • mbd_ii — МБД.ИИ;

  • mbd_kh — МБД.КХ;

  • mbd_p — МБД.П;

  • mbd_s — МБД.С;

  • mbd_t — МБД.Т;

  • mbd_h — МБД.Х;

  • mbd_y — МБД.Я;

  • mv_vk — МВ.ВК;

  • mv_vrm — МВ.ВРМ;

  • mv_g — МВ.Г;

  • mv_di — МВ.ДИ;

  • mv_k — МВ.К;

  • mv_s — МВ.С;

  • mdi_v — МДИ.В;

  • ms_bn — МС.БН;

  • mhd_b — МХД.Б;

  • mhd_du — МХД.ДУ;

  • mhd_o — МХД.О;

  • mhd_r — МХД.Р.

version

Номер версии шаблона.

Тип: string.