-

docs/dashboards.rst

@@ -291,3 +291,570 @@ Kibana со своим кодом, как используемое поле.
 в этот шаблон, и их свойствами. Эти свойства зависят от типов индексов.
 Типы, с которыми индексируются данные форм Synergy, описаны в разделе
 `Индексация данных форм в ARTA Synergy`_.
+
+Создание диаграмм
+~~~~~~~~~~~~~~~~~
+
+Kibana позволяет создавать следующие типы диаграмм:
+
+1. **Area chart** - предназначена для отображения общего изменения
+данных во времени, когда выявление суммарного значения всех данных
+важнее, чем сравнение любых двух или более последовательностей.
+Например, полезна для отображения использования ресурсов сервера.
+
+2. **Data table** - отображение данных как результата агрегации в
+виде таблицы.
+
+3. **Line chart** - используется для отображения данных в виде линий
+(графиков). В отличие от Area charts, удобна для сравнения
+последовательностей между собой.
+
+4. **Markdown widget** - вставка произвольной информации, используя
+синтаксис языка Markdown.
+
+5. **Metric** - отображение одного числа - результата агрегации
+числовых данных.
+
+6. **Pie Chart** - предназначена для отображения вклада нескольких
+частей в некоторый общий результат. Может принимать вид круговой
+(pie) или кольцевой (donut) диаграммы.
+
+7. **Tag cloud** - отображение данных таким образом, чтобы их размер
+зависел от некоторого числового показателя этих данных (например,
+количества упоминаний).
+
+8. **Tile map** - специфический тип диаграмм, использующий агрегацию
+географических данных (тип поля ``geo_point``) для их отображения на
+карте.
+
+9. **Timeseries** - специфический тип диаграмм, визуализирующий
+временные ряды.
+
+10. **Vertical bar chart** - наиболее универсальная диаграмма,
+отображающая числовые показатели произвольных полей в виде
+вертикальной гистограммы.
+
+Здесь будут рассмотрены некоторые наиболее универсальные из этих
+диаграмм. Для ознакомления с работой остальных типов рекомендуем
+обратиться к `официальному руководству по Kibana <https://www.elastic.co/guide/en/kibana/current/visualize.html>`_.
+
+.. note:: В диаграммах возможно использование только агрегируемых типов
+          полей. К ним относятся все числовые типы, а также типы ``date``,
+          ``keyword``, ``geo_shape`` и другие. Агрегируемые поля отмечены
+          галочкой в графе "Aggregatable" (на странице Managenent -
+          Index Patterns).
+
+Общая часть
+"""""""""""
+
+Все диаграммы создаются в разделе **Visualize**:
+
+.. figure:: _static/img/dashboards/visualize.png
+
+    Kibana, раздел Visualize
+
+В общем случае, процесс создания диаграмм состоит из трех шагов:
+
+1. Выбор типа диаграммы.
+
+2. Выбор источника данных шаблона индекса.
+В одной диаграмме возможно использование только одного шаблона,
+поэтому для использования в одной диаграмме данных документов по
+нескольким формам, необходимо использовать alias-ы.
+
+    .. note:: Этот шаг отсутствует для диаграммы *Markdown widget*
+
+.. figure:: _static/img/dashboards/step2.png
+
+    Выбор источника данных
+
+В качестве источника данных может выступать шаблон индекса
+или результат поиска по данным (сохраненный или новый).
+
+3. Настройка отображаемых данных:
+
+.. figure:: _static/img/dashboards/step3.png
+
+    Настройка отображаемых данных
+
+Окно настройки данных имеет стандартный вид:
+
+    В верхней части располагается панель меню с пунктами:
+
+       - *New* - создать новую диаграмму, переход к шагу 1;
+
+       - *Save* - сохранить диаграмму;
+
+       - *Open* - открыть существующую диаграмму;
+
+       - *Share* - предоставить доступ к сохраненной диаграмме;
+
+       - *Refresh* - обновить данные.
+
+Ниже панели меню расположено поле поиска данных, использующее
+синтаксис **Lucene**. Данное поле используется для фильтрации
+данных, отображаемых в диаграмме. Например, для отображения только
+неудаленных документов в этой панели нужно ввести запрос:
+
+    ``deleted:0``
+
+где ``deleted`` - поле, генерируемое во время индексации данных
+форм и хранящее значение 0, если данные в Synergy не были удалены.
+
+Основная рабочая область окна делится на две части:
+
+    - настройка данных: выбор полей и способа их агрегации;
+
+    - просмотр результатов: отображение результата обработки
+    выбранных данных.
+
+В части настройки данных, в разделе *Metrics*, необходимо
+выбрать способ агрегации числовых данных, отображаемых в
+диаграмме. В поле *Aggregation* выбирается способ агрегации,
+а в поле *Custom label* вводится отображаемое название параметра.
+
+В разделе *Buckets* необходимо выбрать используемые данные,
+числовые параметры которых будут отображены на диаграмме. Так
+же, как и в разделе *Metrics*, здесь в поле *Aggregation*
+выбирается способ агрегации, а в поле *Custom label* вводится
+отображаемое название параметра. Отличие от раздела *Metrics*
+состоит в том, что раздел *Buckets* позволяет группировать
+произвольные типы данных при выборе соответствующего типа
+агрегации.
+
+Наиболее универсальным способом агрегации, используемом во
+всех примерах ниже, является *Term*. Этот способ позволяет
+агрегировать данные как строки, аналогично функции `GROUP BY`
+в SQL. Подробно об остальных типах агрегации можно ознакомиться
+в официальном руководстве по Kibana.
+
+При выборе этого типа агрегации дополнительно отображаются
+поля:
+
+    - *Field* - выпадающий список, содержащий все поля, входящие
+      в текущий шаблон индекса, для которых доступна агрегация.
+
+    - *Order By* - параметр сортировки данных - по метрике из
+      раздела *Metrics*, по отдельной метрике (*Custom metric*) или
+      по содержимому текущего поля (*Term*).
+
+    - *Order* - направление сортировки:
+
+    - *Descending* - по убыванию;
+
+    - *Ascending* - по возрастанию.
+
+    - *Size* - количество отображаемых элементов - отображаются
+      указанное количество элементов, располагающиеся в начале
+      списка отсортированных указанным образом данных.
+
+    - *Custom label* - отображаемое название параметра.
+
+>> Для каждого используемого параметра, независимо от того, используется
+ли он в разделах *Metrics* или *Buckets*, доступна дополнительная
+настройка, отображаемая при нажатии на лейбл **Advanced**:
+
+>> ![JSON Input](resources/img/integration/dashboards/json_input.png)
+
+>> Она представляет собой текстовое поле, в которое можно добавить
+специальные свойства в формате `JSON`, например:
+
+>> `{ "script" : "doc['grade'].value * 1.2" }`
+
+В настоящем документе процесс создания диаграмм и дашбордов
+будет рассмотрен на примере анализа данных формы "Заявка":
+
+![Форма "Заявка"](resources/img/integration/dashboards/request_form.png)
+
+##### Pie chart {#sec.dashboards_pie_chart}
+
+![Создание диаграммы Pie chart](resources/img/integration/dashboards/pie_chart_creation.png)
+
+Для диаграммы Pie chart возможно два способа организации
+используемых параметров:
+
+- **Split Slices**: параметр будет отображен на диаграмме как
+новый уровень секторов:
+
+> ![Заявки по офисам и клиентам](resources/img/integration/dashboards/pie_chart_split_slices.png)
+
+> На этом примере в разделе *Buckets* в качестве первого
+параметра использовано поле "Центр решений" - результаты этой
+агрегации на диаграмме отображены во внутреннем круге.
+
+> В качестве второго параметра используется поле "Клиент/проект",
+и результаты этой агрегации отображаются во внешнем круге.
+
+>> **Примечание:**
+
+>> Такая последовательность была выбрана в силу специфики
+входных данных: известно, что один центр решений занимается
+несколькими проектами, но одним проектом занимается ровно
+один центр решений.
+
+> Итоговая диаграмма позволяет оценить распределение объема
+заявок как по центрам решений, так и по отдельным проектам.
+
+- **Split Chart**: для нового параметра будет построена
+отдельная диаграмма:
+
+> ![Заявки по офисам и клиентам](resources/img/integration/dashboards/pie_chart_split_charts.png)
+
+> Здесь для каждого центра решений (поле выбрано первым
+параметром с типом *Split Chart*) отрисована отдельная
+диаграмма, в которой показано распределение заявок по
+проектам этих центров (второй параметр с типом *Split Slices*).
+Видно, что три центра решений оставляли заявки только по одному
+из своих проектов.
+
+>> **Примечание:**
+
+>> Kibana допускает использование *Split Chart* только в
+сочетании с *Split Slices*, причем в этом случае параметр
+со *Split Chart* обязательно должен располагаться выше, чем
+параметр со *Split Slices* (сначала разделить данные по
+отдельным диаграммам, а потом разделять данные внутри каждой
+диаграммы).
+
+Добавить новый параметр можно, нажав на кнопку **Add sub-buckets**.
+
+Вкладка **Options** для этого типа диаграмм содержит три
+параметра:
+
+![Вкладка "Опции" диаграммы Pie chart](resources/img/integration/dashboards/pie_chart_options.png)
+
+- Вид диаграммы: если чекбокс *Donut* включен, диаграмма
+принимает вид кольцевой, если отключен - круговой (по
+умолчанию).
+
+- Расположение легенды: по умолчанию справа от диаграммы.
+
+- Показывать всплывающие подсказки при наведении на часть
+диаграммы: отображаются, если включен чекбокс *Show Tooltip*.
+
+##### Data table {#sec.dashboards_data_table}
+
+![Создание диаграммы Data table](resources/img/integration/dashboards/data_table_creation.png)
+
+В разделе *Metrics* необходимо указать одну или несколько
+метрик, по которым будут агрегироваться данные в таблице.
+
+В разделе *Buckets* необходимо указать используемые параметры
+и способы их агрегации. Для этого типа диаграмм также существует
+два способа организации входных параметров:
+
+- *Split Rows* для добавления параметра как нового столбца к
+текущей таблице;
+
+- *Split Table* для добавления параметра как отдельной таблицы.
+
+Функциональность этих способов полностью аналогична *Split Slices*
+и *Split Chart* для [круговой диаграммы](#sec.dashboards_pie_chart).
+
+![Настроены отображаемые данные в таблице](resources/img/integration/dashboards/data_table_result.png)
+
+> В диаграмме, указанной на рисунке выше, все параметры были
+добавлены как *Split Rows*. Для каждого параметра в разделе
+*Buckets* используется агрегация *Terms*.
+
+Вкладка **Options** для этого типа диаграмм содержит следующие
+параметры:
+
+![Вкладка "Опции" диаграммы Data table](resources/img/integration/dashboards/data_table_options.png)
+
+- Количество отображаемых строк на странице: по умолчанию
+отображается 10 строк. В случае, если все записи не помещаются
+на одну страницу, в нижней части таблицы отображается переключатель
+страниц.
+
+- Отображать метрики для каждой группы/уровня: если чекбокс
+включен, то для каждого столбца (в случае *Split Rows*) или
+каждой таблицы (в случае *Split Table*) будет добавлен столбец
+с результатом агрегации из раздела *Metrics*.
+
+- Отображать частичные строки: если чекбокс включен, то в таблицу
+будут включены строки с данными, отсутствующими для выбранных
+индексов (полей). По умолчанию в таблице отображаются только
+полностью заполненные строки.
+
+- Считать метрики для каждой группы/уровня: чекбокс, недоступный
+для ручной установки. Его значение зависит от параметра
+"Отображать метрики для каждой группы/уровня".
+
+- Отображать итоговые значения: если чекбокс включен, то на каждой
+странице таблицы для каждой отображаемой метрики будет указано
+итоговое значение этой метрики для всех данных таблицы.
+
+- Функция для итогов: выбор функции для подсчета итоговых значений
+метрик. Параметр доступен только в том случае, если установлен
+чекбокс "Отображать итоговые значения".
+
+##### Vertical bar chart {#sec.dashboards_vertical_bar_chart}
+
+![Создание диаграммы Vertical bar chart](resources/img/integration/dashboards/step3.png)
+
+В диаграмме этого типа по оси Y располагаются метрики (параметры
+в *Metrics*), с по оси X - группы (параметры в *Buckets*).
+
+Доступно указание нескольких метрик на оси Y и не больше одной
+группы каждого типа:
+
+- *X-Axis*
+
+- *Split Bars*
+
+- *Split Chart*
+
+Функциональность *Split Bars* и *Split Chart* полностью аналогична
+*Split Slices* и *Split Chart* для [круговой диаграммы](#sec.dashboards_pie_chart).
+
+![Диаграмма Vertical bar chart, пример 1](resources/img/integration/dashboards/split_chart_vertical_bar.png)
+
+На примере 1 показан результат разделения параметров по диаграммам:
+отображается количество заявок, поданных разными авторами и
+выполненных разными исполнителями. Для этого исполнители расположены
+по оси Х, а для каждого автора заявок отрисована отдельная диаграмма.
+
+![Диаграмма Vertical bar chart, пример 2](resources/img/integration/dashboards/split_bars_vertical_bar.png)
+
+На примере 2 показана простая гистограмма, визуализирующая количество
+заявок, выполненных разными исполнителями.
+
+##### Markdown widget {#sec.dashboards_Markdown_widget}
+
+Специфичный тип диаграммы, который не имеет раздела *Data*.
+В левой части рабочей области располагается поле ввода текста
+с использованием синтаксиса языка
+[Markdown](https://ru.wikipedia.org/wiki/Markdown), в правой
+части отображается результат разметки текста:
+
+![Создание Markdown widget](resources/img/integration/dashboards/markdown_widget.png)
+
+Эта диаграмма не имеет никаких особых настроек.
+
+##### Metric {#sec.dashboards_metric}
+
+Диаграмма *Metric* работает только с числовыми данными, поэтому
+для нее доступны только агрегации типа *Metrics*:
+
+![Создание Metrics](resources/img/integration/dashboards/metrics_creation.png)
+
+Добавить новую метрику можно, нажав на кнопку **Add metrics**.
+Новая метрика будет добавлена как новое отображаемое число.
+
+Вкладка **Options** для этого типа диаграмм содержит только
+один параметр - размер шрифта:
+
+![Вкладка "Опции" диаграммы Metrics](resources/img/integration/dashboards/metrics_options.png)
+
+##### Tag cloud {#sec.dashboards_tag_cloud}
+
+![Создание Tag cloud](resources/img/integration/dashboards/tag_cloud_creation.png)
+
+В диаграмме Tag cloud возможно использование только одной агрегации *Metrics*
+и только одного, специального способа организации данных в *Buckets* -
+*Tags*. Добавление новых метрик или новых групп недоступно.
+
+![Пример диаграммы Tag cloud](resources/img/integration/dashboards/tag_cloud_result.png)
+
+Вкладка **Options** содержит следующие параметры:
+
+- зависимость размера текста от числовой метрики: линейная, логарифмическая
+или квадратичная;
+
+- ориентация тэгов: горизонтальная, вертикальная или произвольная;
+
+- границы размеров шрифта в тэгах;
+
+- отображать название используемых параметров: чекбокс, по умолчанию выключен.
+
+![Вкладка "опции" диаграммы Tag cloud](resources/img/integration/dashboards/tag_cloud_options.png)
+
+#### Создание дашбордов {#sec.dashboards_dashboards_creation}
+
+Дашборд представляет собой панель, на которой располагаются
+ранее созданные диаграммы, с широкими возможностями настроек
+отображения, обновления и публикации.
+
+Создание дашбордов производится в разделе **Dashboard**:
+
+![Kibana, раздел Dashboard](resources/img/integration/dashboards/add_dashboard.png)
+
+Панель меню этого раздела содержит пункты:
+
+- **New** - переход к строке поиска и созданию нового фильтра.
+
+- **Add** - добавить новый дашборд, содержит перечень сохраненных диаграмм
+и результатов поиска:
+
+> ![Добавление диаграммы на дашборд](resources/img/integration/dashboards/dashboard_add_panel.png)
+
+> Каждая диаграмма в списке сопровождается пиктограммой, указывающей на тип
+диаграммы.
+
+- **Save** - сохранить текущий дашборд.
+
+- **Open** - открыть ранее сохраненный дашборд.
+
+- **Share** - настройки публикации дашборда. Доступны только для сохраненного
+дашборда.
+
+- **Options** - настройка внешнего вида дашборда, содержит единственный
+чекбокс "Использовать темную тему", по умолчанию выключен.
+
+- **Time range** - настройка режима отображения данных для диаграмм.
+В самой панели отображается настроенный период. По умолчанию отображаются
+данные за последние 15 минут. Данная настройка актуальна, если есть
+необходимость отображения данных в режиме реального времени. Доступна
+возможность быстрой настройки периода (за сегодня, за эту неделю,
+за последний год), указания абсолютной (дата и время в формате
+`YYYY-MM-DD HH:mm:ss.SSS`) или относительной (например, последние
+25 минут) настройки.
+
+> ![Настройки периода отображения](resources/img/integration/dashboards/dashboard_time_range.png)
+
+> При переходе к этой настройке в панели меню появляется дополнительный
+пункт **Auto-refresh**. Он предназначен для настройки интервала обновления
+диаграмм:
+
+> ![Настройки периода обновления диаграмм](resources/img/integration/dashboards/dashboard_refresh.png)
+
+> Данная настройка актуальна, если данные, на основе которых построены
+диаграммы, регулярно обновляются: например, в терминах Synergy, если необходимо
+отображать актуальные данные реестров, в которых регулярно появляются новые
+записи.
+
+> По умолчанию автообновление выключено.
+
+Для всех диаграмм на дашборде возможно одновременное применение условий
+для отображаемых данных. Для этого нужно ввести условие в панель поиска,
+располагающуюся ниже панели меню. Функциональность этой панели для
+раздела **Dashboards** аналогично панели в разделе **Visualize**.
+
+##### Добавление и настройка диаграмм {#sec.dashboards_add_diargam_to_panel}
+
+Для добавления ранее сохраненной диаграммы на дашборд необходимо выбрать пункт
+меню **Add**. Отобразится список доступных диаграмм (илл. "Добавление диаграммы
+на дашборд" выше). Необходимо кликнуть на нужную диаграмму - она будет добавлена
+на дашборд:
+
+![Добавлена панель диаграммы на дашборд](resources/img/integration/dashboards/add_digramm_step1.png)
+
+Размер отображаемой диаграммы можно изменить, потянув за левый нижний угол панели
+диаграммы:
+
+![Изменение размера панели диаграммы](resources/img/integration/dashboards/add_diagramm_resize.png)
+
+![Изменен размер панели диаграммы](resources/img/integration/dashboards/add_daigramm_step2.png)
+
+В случае, если все данные диаграммы не помещаются на панели, в нее будет добавлен
+внутренний скролл.
+
+> **Примечание:**
+
+> Если на определенном размере панели диаграммы "Облако тэгов" не помещаются все
+данные, в ней будут отображены только наиболее популярные тэги (столько, сколько
+возможно уместить на указанном размере панели), и будет отображен текст, предупреждающий,
+что для отображения всех данных необходимо увеличить размер панели диаграммы:
+
+> ![](resources/img/integration/dashboards/tag_cloud_resize.png)
+
+На панели диаграммы отображаются пиктограммы управления:
+
+- ![](resources/img/integration/dashboards/pict1.png) - изменить диаграмму (переход
+к настройкам отображаемых данных диаграммы в разделе **Visualize**);
+
+- ![](resources/img/integration/dashboards/pict2.png) - переместить панель диаграммы
+на дашборде;
+
+- ![](resources/img/integration/dashboards/pict3.png) - удалить панель диаграммы с
+дашборда;
+
+- ![](resources/img/integration/dashboards/pict4.png) - изменить размер панели диаграммы;
+
+- ![](resources/img/integration/dashboards/pict5.png) - отобразать/свернуть источники
+данных в виде таблицы, запроса или исходных данных Elasticsearch, а также
+статистику запроса данных для этой диаграммы;
+
+- ![](resources/img/integration/dashboards/pict6.png) - отобразить/свернуть легенду.
+
+Количество диаграмм, располагаемых на дашборде, не ограничено, наложение диаграмм
+друг на друга не допускается.
+
+Пример готового дашборда:
+
+![Пример готового дашборда в режиме редактирования](resources/img/integration/dashboards/dashboard_kibana.png)
+
+Типы использованных примеров диаграмм (перечислены сверху вниз, слева направо):
+
+1. *Markdown widget*
+
+1. *Pie chart*
+
+1. *Tag cloud*
+
+1. *Metric*
+
+1. *Vertical bar chart*
+
+1. *Pie chart*
+
+1. *Data table*
+
+> **Примечание:**
+
+> Применение фильтров ко всем диаграммам на дашборде дает корректные
+результаты только в том случае, если коды используемых полей полностью
+совпадают (в том числе постфиксы). В случае, если необходимо отображение
+данных из нескольких форм, имеющих сквозные параметры (например, параметр
+"Статус"), необходимо, чтобы коды компоненов, соответствующих этому
+параметру, совпадали на всех формах, а в диаграммах использовалось одно
+и то же поле с учетом [постфикса](#sec.dashboards_form_indexator_doc_structure).
+
+##### Публикация дашборда {#sec.dashboards_sharing}
+
+Kibana предоставляет способы публикации дашборда как интерактивной диаграммы
+или как снимка его состояния на момент публикации (`shapshot`). Публикация
+производится в меню **Share**:
+
+![Пункт меню "Share"](resources/img/integration/dashboards/dashboard_share.png)
+
+Встраивание как дашборда, так и его снимка возможно двумя способами:
+
+1. как фрейма `html` - код для вставки содержится в поле **Embedded iframe**;
+
+2. как ссылки - URL страницы содержится в поле **Link**.
+
+> **Примечание:**
+
+> По URL, автоматически генерируемому Kibana, пользователям предоставляется
+дашборд в режиме редактирования, с правом доступа ко всем разделам Kibana.
+Для того, чтобы предоставить пользователям доступ к дашборду только в режиме
+просмотра, необходимо в URL ссылки добавить параметр:
+
+> `&embed=true`
+
+Один из способов публикации дашборда в Synergy - добавление его как
+[внешнего модуля](#integration.methods.web-module). При этом каждый дашборд
+должен быть оформлен как отдельный внешний модуль. В качестве адреса приложения
+необходимо использовать URL дашборда.
+
+Другой способ - включение фрейма с дашбордом в [пользовательский компонент](#integration.methods.user-component). В этом случае в качестве HTML-кода необходимо
+использовать код из поля *Embedded iframe*.
+
+> **Примечание:**
+
+> По умолчанию в код фрейма включены границы 800х600 пикселей. Для того, чтобы
+дашборд занимал все доступное место, необходимо изменить эти параметры:
+
+> `height="100%" width="100%"`
+
+> Параметр `embed=true`, означающий доступ к дашборду только в режиме просмотра,
+включается Kibana по умолчанию.
+
+> **Примечание:**
+
+> Обратите внимание, что для того, чтобы дашборд был доступен пользователю, у него
+должен быть доступ к серверу, на котором запущена Kibana.
+
+![Пример дашборда, опубликованного как внешний модуль](resources/img/integration/dashboards/dashboard.png)