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


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

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

== Структура верхнего уровня ==
<pre>{
  "version": 21,
  "variables": [],
  "tiles": {},
  "layouts": {}
}</pre>
{| class="wikitable"
!Свойство
!Тип
!Описание
|-
|<code>version</code>
|number
|Версия схемы. Используйте <code>21</code> для новых дашбордов.
|-
|<code>variables</code>
|array
|Определения переменных. См. '''Переменные'''.
|-
|<code>tiles</code>
|object
|Сопоставление ID плитки с определением плитки. См. '''Плитки'''.
|-
|<code>layouts</code>
|object
|Сопоставление ID плитки с позицией в макете. См. '''Макет'''.
|}
Необязательные свойства: <code>settings</code>, <code>annotations</code>.

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

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

=== Плитка Markdown ===
Плитка Markdown отображает статическое текстовое содержимое, отформатированное с помощью Markdown.<pre>{
  "type": "markdown",
  "content": "# Section Header\n\nSome text here."
}</pre>

=== Плитка данных ===
Плитка данных выполняет запрос '''DQL''' и отображает результаты в виде визуализации.<pre>{
  "type": "data",
  "title": "Tile Name",
  "query": "timeseries avg(dt.host.cpu.usage), by:{host.name}",
  "visualization": "lineChart",
  "visualizationSettings": {},
  "querySettings": {}
}</pre>
{| class="wikitable"
!Свойство
!Обязательно
!Описание
|-
|<code>title</code>
|Да
|Отображается в верхней части плитки.
|-
|<code>query</code>
|Да
|Запрос '''DQL'''.
|-
|<code>visualization</code>
|Да
|Тип визуализации. См. '''Типы визуализаций'''.
|-
|<code>visualizationSettings</code>
|Да
|Объект настроек, специфичных для визуализации. Может быть пустым.
|-
|<code>querySettings</code>
|Да
|Объект настроек, специфичных для запроса. Может быть пустым.
|-
|<code>description</code>
|Нет
|Дополнительное описание плитки.
|-
|<code>timeframe</code>
|Нет
|Переопределение временного диапазона для конкретной плитки. Должно быть объектом, а не строкой.
|-
|<code>segments</code>
|Нет
|Фильтр сегментов для конкретной плитки.
|}
Необязательные свойства <code>queryConfig</code> и <code>davisCopilot</code> можно дополнительно использовать для создания специализированных плиток данных:

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

=== Код-плитка ===
Код-плитка выполняет '''JavaScript''' и при необходимости отображает результаты в виде визуализации.<pre>{
  "type": "code",
  "title": "Custom",
  "input": "// JavaScript code here",
  "visualization": "lineChart",
  "visualizationSettings": {}
}</pre>

=== Плитка SLO ===
Плитка SLO отображает цель уровня обслуживания по её ID.<pre>{
  "type": "slo",
  "title": "SLO Name",
  "input": "slo-id"
}</pre>

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

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

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

=== Графики временных рядов ===
<code>lineChart</code>, <code>areaChart</code>, <code>barChart</code> отображают данные метрик во времени.
{| class="wikitable"
!Слот
!Принимаемые типы
!Количество
!Обязательность
|-
|Time
|<code>timestamp</code>, <code>timeframe</code>
|1
|R
|-
|Interval
|<code>duration</code>
|1
|C — обязательно, когда Values имеет тип <code>numericArray</code>
|-
|Values
|<code>long</code>, <code>double</code>, <code>duration</code>, <code>numericArray</code>
|1+
|R
|-
|Names
|любой
|1+
|O
|}
При использовании <code>timeseries</code> или <code>makeTimeseries</code> значения имеют тип <code>numericArray</code>, и в результате запроса должно присутствовать поле интервала.

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

=== Категориальные графики ===
<code>categoricalBarChart</code>, <code>pieChart</code>, <code>donutChart</code> показывают значения, сгруппированные по категориям. Типичный шаблон запроса: <code>summarize <aggregation>, by:{category}</code>.
{| class="wikitable"
!Слот
!Принимаемые типы
!Количество
!Обязательность
|-
|Values
|<code>long</code>, <code>double</code>, <code>duration</code>
|1+
|R
|-
|Categories
|любой
|1+
|R
|}

=== Одно значение и датчик ===
<code>singleValue</code> отображает одно значение метрики.
{| class="wikitable"
!Слот
!Принимаемые типы
!Количество
!Обязательность
|-
|Single value
|любой
|1
|R
|-
|Sparkline
|<code>numericArray</code>
|1
|O
|}
<code>meterBar</code> и <code>gauge</code> отображают числовое значение на шкале.
{| class="wikitable"
!Слот
!Принимаемые типы
!Количество
!Обязательность
|-
|Meter/Gauge value
|<code>long</code>, <code>double</code>, <code>duration</code>
|1
|R
|}

=== Табличные ===
<code>table</code>, <code>raw</code> и <code>recordList</code> принимают любую форму данных без требований к типам полей.

=== Другие визуализации ===
Также доступны <code>davis</code>, <code>histogram</code>, <code>honeycomb</code>, <code>choropleth</code>, <code>dotMap</code>, <code>connectionMap</code>, <code>bubbleMap</code>, <code>heatmap</code>, <code>scatterplot</code> и <code>treemap</code>, каждая со своими требованиями к слотам.

== Макет ==
Позиции плиток хранятся в <code>layouts</code> как объект, ключи которого совпадают с ID плиток в <code>tiles</code>. Каждая плитка в <code>tiles</code> должна иметь соответствующую запись в <code>layouts</code>.<pre>"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 }
}</pre>
{| class="wikitable"
!Свойство
!Описание
|-
|<code>x</code>
|Горизонтальная позиция (столбец), с индексом от нуля.
|-
|<code>y</code>
|Вертикальная позиция (строка), с индексом от нуля.
|-
|<code>w</code>
|Ширина в единицах сетки.
|-
|<code>h</code>
|Высота в единицах сетки.
|}
Сетка имеет ширину 24 столбца. Распространённые значения ширины:

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

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

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

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

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

Все типы переменных имеют следующие общие свойства:
{| class="wikitable"
!Свойство
!Тип
!Описание
|-
|<code>key</code>
|string
|Идентификатор, используемый как <code>$key</code> в запросах '''DQL'''.
|-
|<code>type</code>
|string
|<code>"query"</code>, <code>"text"</code> или <code>"csv"</code>.
|-
|<code>visible</code>
|boolean
|Показывать селектор переменной в интерфейсе дашборда.
|-
|<code>editable</code>
|boolean
|Разрешить пользователям изменять выбранное значение.
|}

=== Переменные запроса ===
Переменные запроса заполняют свои параметры путём выполнения запроса '''DQL'''. Запрос должен возвращать ровно одно поле.<pre>{
  "version": 2,
  "key": "Service",
  "type": "query",
  "visible": true,
  "editable": true,
  "input": "smartscapeNodes SERVICE | fields name | sort name asc",
  "multiple": false
}</pre>Для множественного выбора со всеми значениями, выбранными по умолчанию, установите <code>"multiple": true</code> и используйте токен выбора всех значений по умолчанию:<pre>{
  "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*"]
}</pre>Используйте полный токен вида UUID-плюс-<code>*</code>, как показано выше, в качестве подстановочного значения, а не литеральную строку <code>"*"</code>. Ключ-АСТРОМ сохраняет подстановочный знак как '''UUID''', чтобы избежать конфликтов с допустимыми значениями переменных, поскольку <code>*</code> сам по себе может быть одним из них. Литеральное значение по умолчанию <code>"*"</code> вызывает непредвиденное поведение — например, при клонировании дашборда предварительно выбирается дополнительная незаполненная опция, которую затем нужно вручную заменить подстановочным знаком в редакторе переменных.

=== Текстовые переменные ===
Текстовые переменные принимают свободный ввод пользователя.<pre>{
  "version": 2,
  "key": "Threshold",
  "type": "text",
  "visible": true,
  "defaultValue": "",
  "editable": true
}</pre>

=== CSV-переменные ===
CSV-переменные предоставляют статический предопределённый список значений.<pre>{
  "version": 2,
  "key": "Status",
  "type": "csv",
  "visible": true,
  "editable": true,
  "input": "WARN,ERROR,INFO,NONE",
  "multiple": true,
  "defaultValue": ["3420b2ac-f1cf-4b24-b62d-61ba1ba8ed05*"]
}</pre>Подстановочный токен в <code>defaultValue</code> работает так же, как для переменных запроса: используйте токен вида UUID-плюс-<code>*</code>, а не литеральную строку <code>"*"</code>.

=== Синтаксис ссылок на переменные ===
Ссылайтесь на переменную в '''DQL''' с помощью <code>$key</code>.
{| class="wikitable"
!Конфигурация переменной
!Шаблон запроса
|-
|Одиночный выбор (<code>multiple: false</code>)
|<code>filter field == $Variable</code>
|-
|Множественный выбор (<code>multiple: true</code>)
|<code>filter in(field, array($Variable))</code>
|}
Используйте модификаторы, когда подстановка строки по умолчанию не подходит:
{| class="wikitable"
!Модификатор
!Для чего
!Пример
|-
|<code>:noquote</code>
|Числовые параметры или параметры длительности
|<code>limit $N:noquote</code>
|-
|<code>:backtick</code>
|Имя поля в <code>by:{}</code> или <code>sort</code>
|<code>by: {$GroupBy:backtick}</code>
|-
|<code>:triplequote</code>
|Строковые константы в <code>matchesPhrase()</code> или <code>contains()</code>
|<code>matchesPhrase(content, $Search:triplequote)</code>
|}
Переменные могут ссылаться на другие переменные. Зависимая переменная пересчитывается при изменении переменной, от которой она зависит. Циклические зависимости не допускаются.

== Настройки ==
<code>settings</code> — необязательный объект. Если он присутствует, он может быть пустым (<code>{}</code>) или содержать конфигурацию уровня дашборда.<pre>"settings": {
  "defaultTimeframe": {
    "value": {
      "from": "now()-2h",
      "to": "now()"
    },
    "enabled": true
  }
}</pre><code>defaultTimeframe</code> задаёт временной диапазон, отображаемый на плитках, которые не переопределяют временной диапазон. Он также определяет окно, для которого оцениваются аннотации.

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

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

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

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

=== Отсутствует обязательное свойство 'type' ===
'''Ошибка'''<pre>Missing required property 'type' of tile id '10'. Expected one of: 'data', 'code', 'markdown', 'slo'</pre>'''Причина:''' у плитки отсутствует обязательное свойство <code>type</code>. Частая причина — загрузка классического дашборда в '''Дашборды''', который использует другую схему '''JSON'''.

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

=== Недопустимый тип для 'timeframe' ===
'''Ошибка'''<pre>Invalid type for property 'timeframe' of tile id '10' (expected object, received string)</pre>'''Причина:''' свойство <code>timeframe</code> является строкой (например, <code>"timeframe": "last 24h"</code>) вместо объекта.

'''Исправление:''' замените строковое значение правильным форматом объекта:<pre>"timeframe": {
  "tileTimeframeEnabled": true,
  "tileTimeframe": {
    "from": "now()-24h",
    "to": "now()"
  }
}</pre>