Аналитические дашборды
======================

Аналитические дашборды - это набор диаграмм, отображающих состояние
данных в различных представлениях и разрезах. Они предназначены для
упрощения работы по их оценке, обработке, прогнозированию дальнейшего
состояния и принятию решений.

Введение
--------

Для интеграции аналитических дашбордов в Synergy используется
комбинация инструментов **Elasticsearch** и **Kibana**.

`Elasticsearch (ES) <https://www.elastic.co/products/elasticsearch>`_ -
это мощный инструмент для полнотекстового поиска и анализа данных.
Он позволяет быстро загружать, выполнять поиск и анализировать
большие объемы данных. Однако ES не имеет специальной визуальной
оболочки, и его использование возможно с помощью набора специальных
API.

`Kibana <https://www.elastic.co/products/kibana>`_ - это платформа
для анализа и визуализации данных. Kibana обрабатывает данные,
загруженные в ES, и работает только параллельно с ним. Если
работа с ES предполагает использование специального синтаксиса
команд, то Kibana позволяет обрабатывать те же данные с
помощью визуального интерфейса. При этом Kibana содержит
интерпретатор, позволяющий использование всех возможностей и
специальных команд ES.

Индексация и обработка исходных данных Synergy производится с
помощью ES, дальнейший анализ и визуализация - с помощью Kibana.

В настоящем документе будут рассмотрены только некоторые из
возможностей этих инструментов, непосредственно относящиеся
к задаче визуализации данных. Для подробного изучения всех их
возможностей и способов использования рекомендуем обращаться
к официальной документации:

- `Elasticsearch <https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started.html>`_;

- `Kibana <https://www.elastic.co/guide/en/kibana/current/introduction.html>`_.

Индексация данных форм в ARTA Synergy
-------------------------------------

Запись данных в индекс производится после сохранения данных по форме.
Первичная загрузка данных в ES осуществляется с помощью процесса индексации
данных форм (*Административное приложение -> Обслуживание системы -> Управление индексом форм*).
В это время для каждой формы и каждого компонента этой формы в Synergy
создается несколько индексов. Каждый из этих индексов будет отображен в
Kibana со своим кодом, как используемое поле.

Названия индексов и alias-ы
~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Для всех данных по форме, принадлежащих реестру с идентификатором ``someRegistryID``,
  создаётся индекс с именем ``<index-prefix>-r-someRegistryID``.

- Для всех данных по форме с идентификатором ``someFormID`` создаётся
  индекс с именем ``<index-prefix>-f-someFormID``.

- Если итоговая длина названия индекса (как для форм, так и для реестров)
  превысит 255 байт, оно будет обрезано до 255 байт.

Таким образом, для каждого реестра и для каждой формы, по которым есть данные,
будет создано по индексу. Если по форме создан реестр, а также созданы какие-то
данные вне реестра, то в этом случае будет создано два индекса:

#. ``<index-prefix>-r-IdOfRegistryWithOtherForm``

#. ``<index-prefix>-f-otherID``.

.. note:: `Здесь <https://www.elastic.co/guide/en/elasticsearch/reference/current/_list_all_indices.html#_list_all_indices>`_
          описано, как получить названия всех имеющихся индексов в Elasticsearch.

Кроме этого, для удобства использования и возможности переноса конфигурации для
каждого из вышеперечисленных индексов создаётся
`alias <https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-aliases.html>`_.
Имена alias-ов формируются так:

- Для данных реестров: ``r-нормализованный_код_реестра``

- Для данных форм без реестров: ``f-нормализованный_код_формы``
  где ``нормализованый_код_реестра`` и ``нормализованный_код_формы`` - коды, соответственно,
  реестра и формы, в которых специальные символы \, ., [, ], {, }, (, ), +, -, ?, ^, $, |
  заменяются на _.

.. warning::  При этом возможна ситуация, когда нормализованные коды разных реестров совпадут и alias
              будет создан на на все соответветствующие индексы. Эта маловероятное затруднение может быть
              решено изменением кодов соответствующих реестров или форм. В случае, если это невозможно,
              необходимые alias-ы `можно создать вручную <https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-aliases.html>`_.

              При изменении кода реестра или формы в Synergy имя соответствующего alias-а также изменяется.

Структура документа в индексе
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Одна единица данных в индексе Elasticsearch называется *Документ*. Документ содержит
поля определённых `типов <https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html>`_.
Каждый документ в текущем индексе соответствует одной единице данных по форме (=файлу по форме,
записи реестра) и содержит следующие поля:

- ``asfDataId`` - идентификатор данных по форме, тип ``keyword``;

- ``formId`` - идентификатор формы, тип ``keyword``;

- ``formCode`` - код формы, тип ``keyword``;

- ``registryId`` - идентификатор реестра, тип ``keyword`` (содержит значение ``-1`` для данных по
  форме, не связанных с реестром);

- ``documentId`` - идентификатор документа Synergy, тип ``keyword``;

- ``status`` - статус записи реестра, тип ``number``:

	- 0 - "Подготовка" (``NO_ROUTE``) - это значение также устанавливается для данных по форме,
  не связанных с реестром

	- 1 - "В процессе" (``STATE_NOT_FINISHED``)

	- 2 - "Активная" (``STATE_SUCCESSFUL``)

	- 3 - "Неуспешная" (``STATE_UNSUCCESSFUL``)

- ``deleted`` - признак удаления записи реестра (0 - не удалено, 1 - удалено), тип ``number``
  (0 для данных по форме, не связанных с реестром);

- ``created`` - дата и время создания данных по форме, тип ``date``;

- ``modified`` - дата и время изменения данных по форме, тип ``date``.

Далее следуют поля, соответствующие компонентам формы:

- Для каждого компонента формы создаётся несколько полей документа в индексе.

- Название полей, соответствующих компоненту формы, формируется так:
  ``идентфикаторкомпонентаформывнижнемрегистре_key_постфикс`` и
  ``идентфикаторкомпонентаформывнижнемрегистре_value_постфикс`` (данные для которых берутся,
  соответственно, из полей ``key`` и ``value`` данных по форме).

- Для каждого поля ``*_key`` и ``*_value`` создаются поля с нижеперечисленными постфиксами.

- Для компонентов, находящихся внутри динамической таблицы, а также компонентов с
  мультивыбором ("Объекты Synergy"), значения записываются в
  `массив <https://www.elastic.co/guide/en/elasticsearch/reference/current/array.html>`_
  для всех постфиксов с учетом типов компонентов.

- Для компонентов, имеющих ``key`` и ``value``, создается общее поле ``*_object``
  (`Object <https://www.elastic.co/guide/en/elasticsearch/reference/5.3/object.html>`_).

Постфиксы для полей ``*_key``:

- ``_exact`` - поле содержит значение ``key``, приведенное к нижнему регистру, тип ``keyword``;

- ``_sort`` - поле содержит точное значение ``key``, тип ``keyword``;

- ``_number`` - поле содержит значение ``key``, приведенное к числу, тип ``number``;

            .. note:: Если поле ``key`` в документе пусто, в данное поле будет записано максимальное
                      значение для типа ``long``: 9 223 372 036 854 775 807

- ``_date`` - поле содержит значение ``key``, приведенное к дате; поле присутствует только для
компонентов Synergy типа "Дата/время"; тип ``date``;

- ``_double`` - поле содержит значение ``key``, приведенное к числу, тип ``double``;

            .. note:: Данное поле создается только в том случае, если из значения ``key`` удалось
                      выделить число (т.е. есть хотя бы один документ, использующий это поле,
                      содержит числовое значение);

- пустой постфикс - поле содержит n-граммы значения ``key``, через пробел, тип ``text``.

Постфиксы для полей ``*_value``:

- ``_exact`` - поле содержит значение ``value``, приведенное к нижнему регистру, тип ``keyword``;

- ``_sort`` - поле содержит точное значение ``value``, тип ``keyword``;

- ``_number`` - поле содержит значение ``value``, приведенное к числу, тип ``number``;

            .. note:: Если поле ``key`` в документе пусто, в данное поле будет записано максимальное
                      значение для типа ``long``: 9 223 372 036 854 775 807

- ``_prefix`` - поле содержит возможные префиксы из значения ``value``, через пробел, тип ``text``;

- ``_postfix`` - поле содержит возможные постфиксы из значения ``value``, через пробел, тип ``text``;

- пустой постфикс - поле содержит n-граммы значения ``value``, через пробел, тип ``text``.

Индексы изменения данных (историчные индексы)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Индексы изменения данных создаются только для тех форм и реестров, коды которых подпадают
под шаблоны (секции в конфигурационном файле ``arta/elasticConfiguration.xml``, см. описание выше).

Имя индекса ``<index-prefix>-rh-someRegistryID`` и ``<index-prefix>-fh-someFormID``, для реестров и
форм, соответственно. Alias-ы: ``rh-нормализованный_код_реестра`` и ``fh-нормализованный_код_формы``.

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

- Для ``*_key``:

	- ``_exact``

	- ``_number``

	- ``_date``

	- ``_double``

- Для ``*_value``:

	- ``_exact``

	- ``_number``

Типы данных и условия создания полей такие же, как и в текущем индексе.

Визуализация данных в Kibana
----------------------------

Шаблоны индексов
~~~~~~~~~~~~~~~~

Для использования индексов Elasticsearch в диаграммах Kibana
необходимо указать эти индексы, используя **шаблоны индексов**
(Index patterns). Они представляют собой маску имени, которой
должны соответствовать индексы, входящие в этот шаблон.

Подробно о шаблонах индексов написано в
`официальном руководстве по Kibana <https://www.elastic.co/guide/en/kibana/current/index-patterns.html>`_.

Например, если необходимо создать шаблон для индексов ``myindex-1``,
``myindex-2``, ``myindex-3`` и ``myindex-abc``, требуется создать
шаблон индекса ``myindex-*``, где символ * означает подстановку
произвольного набора символов.

.. note:: Поскольку имена индексов данных форм составляются
          на основе кодов соответствующих компонентов форм, рекомендуется присваивать
          этим компонентам коды с учетом некоторого значащего префикса так,
          чтобы используемые данные можно было объединить в группу по маске
          имени.

          В случае, если изменение кодов компонентов не представляется
          возможным, можно создать шаблон индекса с маской "*". Этот шаблон
          будет содержать все индексы Elasticsearch.

          Другой способ объединения данных по форме в единый шаблон индекса -
          создание шаблона для отдельного реестра или формы. Например, если
          в диаграмме необходимо использовать данные реестра ``someRegistryID``,
          нужно создать шаблон индекса с названием ``r-someRegistryID``.
          Аналогично, для использования данных формы (в случае, если Synergy
          не содержит реестра для этой формы) с кодом ``someFormID`` нужно
          создать шаблон индекса ``f-someFormID``.

Создание шаблонов индексов осуществляется в разделе *Management* -
*Index Patterns*. Для создания нового шаблона нужно нажать на
кнопку **+ Add New**. Откроется окно создания нового индекса:

.. figure:: _static/img/dashboards/configure_index_pattern.png

    Создание нового шаблона индексов

Установленный чекбокс **Index contains time-based events** означает,
что данные, которые входят в шаблон, содержат временные данные.

.. attention::  Не рекомендуется оставлять этот чекбокс включенным, если не
                планируется визуализация данных во времени - например, отслеживать
                нагрузку на сервер в настоящий момент. Без особой настройки диаграммы,
                использующие такие поля, будут отображать только данные, соответствующие
                текущему моменту времени.

В поле **Index name or pattern** необходимо ввести имя шаблона индекса:

.. figure:: _static/img/dashboards/configure_index_pattern_1.png

    Создание нового шаблона индексов без временных данных

В случае, если Elasticsearch содержит индексы с именами, соответствующими
указанному шаблону, отобразится доступная кнопка **Create**. Для создания
шаблона индекса нужно нажать на эту кнопку.

.. figure:: _static/img/dashboards/index_pattern.png

    Созданный шаблон индексов

После создания шаблона отображается таблица со списком индексов, входящих
в этот шаблон, и их свойствами. Эти свойства зависят от типов индексов.
Типы, с которыми индексируются данные форм Synergy, описаны в разделе
`Индексация данных форм в ARTA Synergy`_.
