Источники данных виджетов

Виджеты дашбордов используют следующие типы источников данных:

• Статические данные
• Метрики
• Атрибуты
• Индикаторы здоровья
• OpenSearch

Метрики

Для получения метрик используется PromQL запрос. PromQL запрос бывает нескольких типов:

• query
• query_range

Отличие между query (instant) и query_range (range) в PromQL

Характеристика	query (instant)	query_range (range)
Тип запроса	Мгновенный запрос (одна точка во времени)	Запрос за диапазон времени (интервал)
Возвращаемые данные	Последнее значение метрики	Массив значений за указанный период
Формат ответа	"resultType": "vector"	"resultType": "matrix"
Структура ответа	"value": [timestamp, "value"]	"values": [[ts1, "v1"], [ts2, "v2"], ...]
Использование	Текущее состояние (например, CPU сейчас)	Графики, тренды (например, CPU за час)
Пример PromQL	up{job="node"}	up{job="node"}[5m]

Instant Query

Возвращает одно актуальное значение метрики на момент выполнения запроса. Используется для отображения текущего состояния (например, статус сервиса, текущая загрузка CPU).

Пример запроса:

http_requests_total{handler="/api"}

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

[
  {
    "status": "success",
    "data": {
      "resultType": "vector",
      "result": [
        {
          "metric": {},
          "value": [1743080341, "1"]
        }
      ]
    }
  },
  {
    "status": "success",
    "data": {
      "resultType": "vector",
      "result": [
        {
          "metric": {},
          "value": [1743080341, "2"]
        }
      ]
    }
  }
]

Range Query

Возвращает массив значений за указанный временной диапазон (например, последние 5 минут). Используется для построения графиков или анализа трендов.

Пример запроса:

http_requests_total{handler="/api"}[5m]

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

[
  {
    "status": "success",
    "data": {
      "resultType": "matrix",
      "result": [
        {
          "metric": {},
          "values": [
            [1743079579, "1"],
            [1743079580, "1"]
          ]
        }
      ]
    }
  },
  {
    "status": "success",
    "data": {
      "resultType": "matrix",
      "result": [
        {
          "metric": {},
          "values": [
            [1743079579, "2"],
            [1743079580, "2"]
          ]
        }
      ]
    }
  }
]

Ключевые различия

Тип данных:

• query → vector (одно значение + метки).
• query_range → matrix (набор значений с метками).

Применение:

• query → Дашборды с текущими показателями (например, "Сейчас онлайн: 42").
• query_range → Графики изменения метрик (например, "Запросы за последний час").

Синтаксис PromQL:

• Для query_range обязательно указывать диапазон в квадратных скобках (например, [5m]).

Виджеты, показывающие одно число, берут из matrix крайнюю правую точку ряда — то же значение, что вернул бы query. Виджет Одно значение вдобавок рисует весь ряд спарклайном в фоне карточки.

Подстановка IPv4 в запрос

В MetricsQL/PromQL-запросах можно использовать значения атрибутов КЕ из узлов TQL. Например, для атрибута ip_address типа IPv4:

sysUpTime{ip_address='[[ pak_dionis_nx_1.attributes.ip_address ]]'}

IP-адрес подставляется вместе с префиксом сети. Если адрес введён без маски, он сохраняется с префиксом /32: для значения 192.168.0.1 выражение после подстановки будет содержать:

sysUpTime{ip_address='192.168.0.1/32'}

Маска /32 автоматически не удаляется. Явно заданная маска, например 192.168.0.1/24, также сохраняется при подстановке. Для совпадения в приведённом запросе лейбл ip_address метрики должен содержать то же значение, включая префикс сети.

Если лейбл ip_address метрики содержит адрес без маски, удалите префикс сети в шаблоне Jinja:

sysUpTime{ip_address='[[ (pak_dionis_nx_1.attributes.ip_address | string).split('/')[0] ]]'}

Фильтр string приводит значение атрибута к строке, а .split('/')[0] оставляет часть до /. Как для 192.168.0.1/32, так и для 192.168.0.1/24 результат будет:

sysUpTime{ip_address='192.168.0.1'}

Статическое значение

Статическое значение задаётся напрямую в настройках виджета как массив объектов. Каждый объект содержит:

• legend — название (подпись) значения
• value — числовое значение

Формат данных:

[
  { "legend": "<имя>", "value": <число> }
]

Пример:

[
  { "legend": "Метрика #1", "value": 123 },
  { "legend": "Метрика #2", "value": 456 }
]

В рамках одного виджета каждая запись из массива визуально отображается отдельно.

Значения атрибутов

Значения атрибутов — это данные о конфигурационных единицах (КЕ), полученные из CMDB. Каждая КЕ имеет поле attribute_values — массив объектов, содержащих имя и значение атрибута.

Формат атрибута КЕ:

{
  "attribute_name": "<имя атрибута>",
  "value": "<значение>"
}

Формат данных:

Ответ преобразуется в массив объектов { legend, value } для каждого атрибута каждой КЕ. legend берётся из attribute_name, value — из соответствующего поля объекта КЕ.

[
  { "legend": "<имя атрибута>", "value": "<значение атрибута>" },
  { "legend": "<имя атрибута>", "value": "<значение атрибута>" }
]

OpenSearch

OpenSearch используется для запросов к индексам логов и документов. В отличие от метрик (VictoriaMetrics), OpenSearch работает с полнотекстовым поиском и агрегациями над структурированными данными.

Для получения данных из OpenSearch используется его REST API с отправкой запроса в формате DSL (Domain Specific Language).

При использовании OpenSearch в качестве источника данных виджетов допускается только один запрос. Несколько запросов к OpenSearch не поддерживаются.

Поле времени

В настройках источника рядом с полем «Индекс» задаётся «Поле времени». Для каждого индекса оно настраивается отдельно, в том числе в группах, привязанных к узлам TQL или КЕ. Настройка доступна во всех виджетах с источником OpenSearch.

По умолчанию используется @timestamp. Для индекса с другим именем поля укажите, например, event_time, time или timestamp. Диапазон времени дашборда автоматически добавляется в запрос как range-фильтр по этому полю; границы передаются в ISO-формате. Укажите существующее поле даты, совместимое с этим форматом. Существующие виджеты без этой настройки продолжают использовать @timestamp.

В виджете «Таблица OpenSearch» выбранное поле также задаёт сортировку по убыванию по умолчанию и выводится первой колонкой данных после кнопки просмотра документа.

Если очистить поле времени, автоматический фильтр диапазона дашборда отключится. В форме появится подсказка «Диапазон дашборда не применяется», а на карточке виджета — постоянная пометка «Данные не ограничены диапазоном дашборда». В таблице при этом нет сортировки по времени по умолчанию и выделенной первой временной колонки. Фильтры, заданные внутри пользовательского DSL, продолжают действовать.

Имена полей внутри пользовательского DSL, агрегаций и выражений JSONata настраиваются отдельно: изменение «Поля времени» их не переименовывает.

Пример запроса

{
  "query": {
    "bool": {
      "must": [
        { "match": { "level": "error" } },
        { "range": { "@timestamp": { "gte": "now-1h", "lte": "now" } } }
      ]
    }
  },
  "size": 0,
  "aggs": {
    "logs_per_minute": {
      "date_histogram": {
        "field": "@timestamp",
        "calendar_interval": "1m"
      },
      "aggs": {
        "error_count": {
          "value_count": {
            "field": "_id"
          }
        }
      }
    }
  }
}

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

{
  "took": 42,
  "timed_out": false,
  "hits": {
    "total": { "value": 1523 },
    "hits": []
  },
  "aggregations": {
    "logs_per_minute": {
      "buckets": [
        {
          "key_as_string": "2024-03-26T10:00:00Z",
          "key": 1711442400000,
          "doc_count": 245,
          "error_count": { "value": 245 }
        },
        {
          "key_as_string": "2024-03-26T10:01:00Z",
          "key": 1711442460000,
          "doc_count": 198,
          "error_count": { "value": 198 }
        }
      ]
    }
  }
}

Ключевые особенности

• Запрос: отправляется как JSON DSL на endpoint POST /{index}/_search.
• Фильтрация: используется bool query с must, filter, should для комбинирования условий.
• Агрегации: поддерживаются date_histogram, terms, avg, sum, cardinality и другие для построения графиков и статистики.
• Временной диапазон: диапазон дашборда автоматически добавляется как range-фильтр по настроенному полю времени, если это поле не пустое.
• Pagination: параметры from и size управляют смещением и количеством возвращаемых документов.

Для дашбордов рекомендуется использовать агрегации (aggs) вместо возврата сырых документов (size: 0), чтобы минимизировать объём передаваемых данных и нагрузку на кластер.

Преобразование данных из OpenSearch

Для виджетов, использующих OpenSearch в качестве источника данных, данные из OpenSearch преобразуются в формат, понятный виджету, с помощью JSONata — лёгкого языка запросов и трансформаций для JSON.

Принцип работы

1. Виджет отправляет запрос к OpenSearch и получает ответ в формате DSL-ответа OpenSearch.
2. Пользователь задаёт JSONata-выражение, которое преобразует ответ OpenSearch в нужный для виджета формат.

Пример трансформации из OpenSearch в формат виджета «Одно значение»

Ниже приведён пример: исходный ответ OpenSearch, JSONata-выражение и результат в формате виджета «Одно значение".

Исходные данные (ответ OpenSearch)

{
  "took": 42,
  "timed_out": false,
  "hits": { "total": { "value": 1523 }, "hits": [] }
}

JSONata-выражение

$map($.hits.hits, function($v, $i) {
  {
    "legend": $v._index,
    "value": $i
  }
})

Результат

[
  {
    "legend": "logs",
    "value": 0
  },
  {
    "legend": "logs",
    "value": 1
  }
]

Поле	Описание
legend	Отображаемое название значения (например, строка времени)
value	Числовое значение метрики