Структура документа Ключ-АСТРОМ — Дашборды

Структура документа Ключ-АСТРОМ — Дашборды

Дашборд Ключ-АСТРОМ хранится как документ JSON. Понимание структуры помогает создавать и изменять дашборды через API или путём прямого редактирования JSON в Дашбордах.

Обзор

Документ дашборда состоит из четырёх обязательных свойств — version, variables, tiles и layouts — плюс необязательные свойства, такие как settings и annotations. Плитки определяют содержимое, отображаемое на дашборде, а макеты управляют их положением на сетке.

Структура верхнего уровня

{
  "version": 21,
  "variables": [],
  "tiles": {},
  "layouts": {}
}

Свойство	Тип	Описание
version	number	Версия схемы. Используйте 21 для новых дашбордов.
variables	array	Определения переменных. См. Переменные.
tiles	object	Сопоставление ID плитки с определением плитки. См. Плитки.
layouts	object	Сопоставление ID плитки с позицией в макете. См. Макет.

Необязательные свойства: settings, annotations.

ID плиток в tiles должны совпадать с ID в layouts. ID — это строки (обычно числовые строки, например "1", "2").

Плитки

Плитки хранятся в tiles как объект, ключами которого являются ID плиток. Существует четыре типа плиток.

Плитка Markdown

Плитка Markdown отображает статическое текстовое содержимое, отформатированное с помощью Markdown.

{
  "type": "markdown",
  "content": "# Section Header\n\nSome text here."
}

Плитка данных

Плитка данных выполняет запрос DQL и отображает результаты в виде визуализации.

{
  "type": "data",
  "title": "Tile Name",
  "query": "timeseries avg(dt.host.cpu.usage), by:{host.name}",
  "visualization": "lineChart",
  "visualizationSettings": {},
  "querySettings": {}
}

Свойство	Обязательно	Описание
title	Да	Отображается в верхней части плитки.
query	Да	Запрос DQL.
visualization	Да	Тип визуализации. См. Типы визуализаций.
visualizationSettings	Да	Объект настроек, специфичных для визуализации. Может быть пустым.
querySettings	Да	Объект настроек, специфичных для запроса. Может быть пустым.
description	Нет	Дополнительное описание плитки.
timeframe	Нет	Переопределение временного диапазона для конкретной плитки. Должно быть объектом, а не строкой.
segments	Нет	Фильтр сегментов для конкретной плитки.

Необязательные свойства queryConfig и davisCopilot можно дополнительно использовать для создания специализированных плиток данных:

• если присутствует допустимое свойство queryConfig, плитка интерпретируется как плитка Explore;
• если присутствует допустимое свойство davisCopilot, плитка интерпретируется как плитка Prompt.

Код-плитка

Код-плитка выполняет JavaScript и при необходимости отображает результаты в виде визуализации.

{
  "type": "code",
  "title": "Custom",
  "input": "// JavaScript code here",
  "visualization": "lineChart",
  "visualizationSettings": {}
}

Плитка SLO

Плитка SLO отображает цель уровня обслуживания по её ID.

{
  "type": "slo",
  "title": "SLO Name",
  "input": "slo-id"
}

Типы визуализаций

Свойство visualization плитки данных определяет, как отображаются результаты запроса. Каждая визуализация требует определённых типов полей в результате запроса. Если запрос возвращает неправильные типы, плитка отображается пустой или показывает ошибку.

Типы полей: timestamp, timeframe, long, double, duration, string, numericArray

Легенда: R = обязательно, O = необязательно, C = условно.

Графики временных рядов

lineChart, areaChart, barChart отображают данные метрик во времени.

Слот	Принимаемые типы	Количество	Обязательность
Time	timestamp, timeframe	1	R
Interval	duration	1	C — обязательно, когда Values имеет тип numericArray
Values	long, double, duration, numericArray	1+	R
Names	любой	1+	O

При использовании timeseries или makeTimeseries значения имеют тип numericArray, и в результате запроса должно присутствовать поле интервала.

bandChart имеет те же требования плюс два дополнительных обязательных слота numericArray для минимального и максимального значений полосы.

Категориальные графики

categoricalBarChart, pieChart, donutChart показывают значения, сгруппированные по категориям. Типичный шаблон запроса: summarize <aggregation>, by:{category}.

Слот	Принимаемые типы	Количество	Обязательность
Values	long, double, duration	1+	R
Categories	любой	1+	R

Одно значение и датчик

singleValue отображает одно значение метрики.

Слот	Принимаемые типы	Количество	Обязательность
Single value	любой	1	R
Sparkline	numericArray	1	O

meterBar и gauge отображают числовое значение на шкале.

Слот	Принимаемые типы	Количество	Обязательность
Meter/Gauge value	long, double, duration	1	R

Табличные

table, raw и recordList принимают любую форму данных без требований к типам полей.

Другие визуализации

Также доступны davis, histogram, honeycomb, choropleth, dotMap, connectionMap, bubbleMap, heatmap, scatterplot и treemap, каждая со своими требованиями к слотам.

Макет

Позиции плиток хранятся в layouts как объект, ключи которого совпадают с ID плиток в tiles. Каждая плитка в tiles должна иметь соответствующую запись в layouts.

"layouts": {
  "1": { "x": 0, "y": 0, "w": 24, "h": 1 },
  "2": { "x": 0, "y": 1, "w": 12, "h": 8 },
  "3": { "x": 12, "y": 1, "w": 12, "h": 8 },
  "4": { "x": 0, "y": 9, "w": 24, "h": 8 }
}

Свойство	Описание
x	Горизонтальная позиция (столбец), с индексом от нуля.
y	Вертикальная позиция (строка), с индексом от нуля.
w	Ширина в единицах сетки.
h	Высота в единицах сетки.

Сетка имеет ширину 24 столбца. Распространённые значения ширины:

• 24 — полная ширина
• 12 — половина ширины
• 6 — четверть ширины

Распространённые значения высоты:

• 1 — строка заголовка или метки
• от 6 до 8 — стандартный график
• от 12 до 16 — детальный вид

Плитки, у которых x + w > 24, переносятся на следующую строку.

Переменные

Переменные обеспечивают динамическую фильтрацию по плиткам. Определяются в variables как массив и используются в запросах DQL через $key.

Все типы переменных имеют следующие общие свойства:

Свойство	Тип	Описание
key	string	Идентификатор, используемый как $key в запросах DQL.
type	string	"query", "text" или "csv".
visible	boolean	Показывать селектор переменной в интерфейсе дашборда.
editable	boolean	Разрешить пользователям изменять выбранное значение.

Переменные запроса

Переменные запроса заполняют свои параметры путём выполнения запроса DQL. Запрос должен возвращать ровно одно поле.

{
  "version": 2,
  "key": "Service",
  "type": "query",
  "visible": true,
  "editable": true,
  "input": "smartscapeNodes SERVICE | fields name | sort name asc",
  "multiple": false
}

Для множественного выбора со всеми значениями, выбранными по умолчанию, установите "multiple": true и используйте токен выбора всех значений по умолчанию:

{
 "version": 2,
 "key": "Services",
 "type": "query",
 "visible": true,
 "editable": true,
 "input": "smartscapeNodes SERVICE | fields name | sort name asc",
 "multiple": true,
 "defaultValue": ["3420b2ac-f1cf-4b24-b62d-61ba1ba8ed05*"]

}

Используйте полный токен вида UUID-плюс-*, как показано выше, в качестве подстановочного значения, а не литеральную строку "*". Ключ-АСТРОМ сохраняет подстановочный знак как UUID, чтобы избежать конфликтов с допустимыми значениями переменных, поскольку * сам по себе может быть одним из них. Литеральное значение по умолчанию "*" вызывает непредвиденное поведение — например, при клонировании дашборда предварительно выбирается дополнительная незаполненная опция, которую затем нужно вручную заменить подстановочным знаком в редакторе переменных.

Текстовые переменные

Текстовые переменные принимают свободный ввод пользователя.

{
  "version": 2,
  "key": "Threshold",
  "type": "text",
  "visible": true,
  "defaultValue": "",
  "editable": true
}

CSV-переменные

CSV-переменные предоставляют статический предопределённый список значений.

{
  "version": 2,
  "key": "Status",
  "type": "csv",
  "visible": true,
  "editable": true,
  "input": "WARN,ERROR,INFO,NONE",
  "multiple": true,
  "defaultValue": ["3420b2ac-f1cf-4b24-b62d-61ba1ba8ed05*"]
}

Подстановочный токен в defaultValue работает так же, как для переменных запроса: используйте токен вида UUID-плюс-*, а не литеральную строку "*".

Синтаксис ссылок на переменные

Ссылайтесь на переменную в DQL с помощью $key.

Конфигурация переменной	Шаблон запроса
Одиночный выбор (multiple: false)	filter field == $Variable
Множественный выбор (multiple: true)	filter in(field, array($Variable))

Используйте модификаторы, когда подстановка строки по умолчанию не подходит:

Модификатор	Для чего	Пример
:noquote	Числовые параметры или параметры длительности	limit $N:noquote
:backtick	Имя поля в by:{} или sort	by: {$GroupBy:backtick}
:triplequote	Строковые константы в matchesPhrase() или contains()	matchesPhrase(content, $Search:triplequote)

Переменные могут ссылаться на другие переменные. Зависимая переменная пересчитывается при изменении переменной, от которой она зависит. Циклические зависимости не допускаются.

Настройки

settings — необязательный объект. Если он присутствует, он может быть пустым ({}) или содержать конфигурацию уровня дашборда.

"settings": {
  "defaultTimeframe": {
    "value": {
      "from": "now()-2h",
      "to": "now()"
    },
    "enabled": true
  }
}

defaultTimeframe задаёт временной диапазон, отображаемый на плитках, которые не переопределяют временной диапазон. Он также определяет окно, для которого оцениваются аннотации.

Валидация дашборда

Ключ-АСТРОМ проверяет JSON дашборда при сохранении изменений в редакторе JSON. Если проверка не пройдена, редактор показывает ошибку и не позволяет сохранить, пока вы её не исправите.

Начиная с версии Ключ-АСТРОМ 1.344 дашборды, не прошедшие валидацию, не будут загружаться. Чтобы исправить дашборд, не прошедший валидацию, откройте его в Дашбордах и выберите Редактировать JSON в меню дашборда.

Когда вы открываете дашборд с ошибками валидации, в левом нижнем углу появляется уведомление. Доступные действия зависят от ваших разрешений:

• Разрешения на редактирование: выберите Редактировать JSON, чтобы открыть редактор JSON и исправить ошибки напрямую.
• Разрешения на просмотр: вы не можете исправить дашборд. Это должен сделать владелец дашборда.

Отсутствует обязательное свойство 'type'

Ошибка

Missing required property 'type' of tile id '10'. Expected one of: 'data', 'code', 'markdown', 'slo'

Причина: у плитки отсутствует обязательное свойство type. Частая причина — загрузка классического дашборда в Дашборды, который использует другую схему JSON.

Исправление: добавьте допустимое свойство type к плитке. Поддерживаемые значения: data, code, markdown и slo.

Недопустимый тип для 'timeframe'

Ошибка

Invalid type for property 'timeframe' of tile id '10' (expected object, received string)

Причина: свойство timeframe является строкой (например, "timeframe": "last 24h") вместо объекта. Исправление: замените строковое значение правильным форматом объекта:

"timeframe": {
  "tileTimeframeEnabled": true,
  "tileTimeframe": {
    "from": "now()-24h",
    "to": "now()"
  }
}