# Средства мониторинга работы системы.
Мониторинг системы реализован в двух независимых формах:
1. Средства мониторинга встроенные в сервер приложений\
   Реализованы по средствам обычных пользовательских интерфейсов системы, и расположены в меню инструментов.
2. Внешние средства мониторинга\
   Реализованы на основе протокола передачи телеметрии `OpenTelemetry`. Метрики передаются в инструмент визуализации `Grafana`

## Мониторинг в приложениях GlobalERP
Для открытия внутренних средств мониторинга необходимо выполнить операцию главного меню `Сервис` - `Инструменты` - `Монитор сессий сервера приложений`

### Монитор сессий сервера приложений
Пользовательский интерфейс, который содержит в себе набор инструментов, для просмотра состояния сервера приложений и базы данных.

#### Пользовательские сеансы
Закладка `Пользовательские сеансы` отображает список всех сессий сервера приложений. Если сервер приложений работает в режиме кластера,
то будут отображены сессии других узлов.

Перечень основных столбцов:
- `Системное имя пользователя` и `Пользователь` - информация о пользователе
- `Ip-адрес клиента` - ip-адрес, с которого подключено клиентское приложение
- `Системное имя приложения` и `Приложение` - информация о запущенном приложении `Global`
- `Системное имя активной формы` и `Активная форма` - информация о текущей активной форме
- `Действие` - информация о выполняемых действиях сессии.
- `Кластерный узел` - Имя узла, к которому подключен клиент.
- `Имя базы данных` - имя БД, выбранное в окне логина при авторизации.
- блок квот - отображает включены лы квоты на сессию, и текущие использованные ресурсы.

Перечень закладок
- `Сессии базы данных` - отображает активные подключения к БД, выбранной пользовательской сессии.
  Позволяет просмотреть выполняемый запрос, и увидеть блокирующую сессию, если она есть
- `Расшифровка` - отображает информацию об открытых формах пользовательской сессии 
- `Стек сеанса` - позволяет получить актуальный стек выполняемых действий пользовательской сессии.

#### Активные подключения к базе данных 
Закладка `Активные подключения к базе данных ` позволяет отобразить активные в данный момент запросы к БД, а так же
информацию о пользовательских сессиях, выполняющих запросы.

Перечень основных столбцов:
- `Системное имя пользователя` и `Пользователь` - информация о пользователе
- `Ip-адрес клиента` - ip-адрес, с которого подключено клиентское приложение
- `Системное имя приложения` и `Приложение` - информация о запущенном приложении `Global`
- `Системное имя активной формы` и `Активная форма` - информация о текущей активной форме
- `Действие` - информация о выполняемых действиях сессии.
- `Кластерный узел` - Имя узла, к которому подключен клиент.
- `Имя базы данных` - имя БД, выбранное в окне логина при авторизации.


### Инструмент анализа Базы данных
Расположен так же на форме `Монитор сессий сервера приложений` на закладке `Анализ базы данных`.
Позволяет увидеть состояние сессий БД, блокировки и выполняемые запросы.
#### Анализ размера таблиц
Инструмент, который позволяет увидеть текущий размер таблиц БД.
Операция `История` позволяет отследить динамику увеличения таблиц
#### Работа автовакуума
Интерфейс, который отображает информацию о работе автоматической очистке таблиц. 

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

[Документация postgresql vacuum](https://postgrespro.ru/docs/postgrespro/9.5/sql-vacuum)

На этой закладке, основное внимание требуется уделять таблицам с выключенным автовакуумом. При нормальной работе системы, все таблицы
должны автоматически очищаться.

Доступные операции:
- `Запуск vacuum full`\
   Команда на полную очистку таблицы с опцией `full`.

   Выбирает режим «полной» очистки, который может освободить больше пространства, но выполняется гораздо дольше и запрашивает исключительную блокировку таблицы. Этот режим также требует дополнительное место на диске, так как он записывает новую копию таблицы и не освобождает старую до завершения операции. Обычно это следует использовать, только когда требуется высвободить значительный объём пространства, выделенного таблице.
- `Запуск vacuum analyze`\
  Обновляет статистику, которую использует планировщик для выбора наиболее эффективного способа выполнения запроса.

Операции следует запускать, только если автовакуум был отключен, или таблица часто изменяется, и автоматическая очистка не справляется.  


#### Анализ активных запросов	 
Инструмент, который позволяет отобразить текущие активные запросы к БД, и информацию о вызвавших их пользовательских сессиях.

Перечень основных столбцов:
- `pid` - pid процесса БД, по которому можно идентифицировать сессию БД.
- `Время выполнения` - время выполнения запроса в минутах.
- `Состояние` - состояние сессии БД\
   Основные состояния:
   - `idle` - сессия БД находится в режиме ожидания. Т.е. подключение к БД есть, но в данный момент никаких запросов не выполняется.
     Стандартное ожидание для неактивных подключений, которые находятся в `пуле подключений сервера приложений`
   - `active` - сессия БД в данный момент выполняет запрос.
   - `idle in transaction` - сессия БД находится в режиме ожидания, но есть открытая транзакция. 
      Опасное состояние сессии, т.к. длинные открытые транзакции отрицательно влияют на производительность `postgresql`.
      Наличие такой сессии сигнализирует о проблеме.
- `Системное имя пользователя` и `Пользователь` - информация о пользователе
- `Ip-адрес клиента` - ip-адрес, с которого подключено клиентское приложение
- `Системное имя приложения` и `Приложение` - информация о запущенном приложении `Global`
- `Форма` - информация о текущей активной форме
- `Кластерный узел` - Имя узла, к которому подключен клиент.
- `Действие` - информация о выполняемых действиях сессии.
   Эта колонка будет заполнена, если:
   - сессия принадлежит выполняемому фоновому заданию, в том числе интеграция
   - выполняется построение печатной формы

Операция `История` позволяет просмотреть исторические данные активных запросов, чья длительность превышала 15 минут.

#### Блокировки
Отображает дерево блокировок сессий БД.

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

Корневыми записями этого дерева будут сессии, вызывающие какие-либо блокировки других сессий.
Записи второго и следующих уровней показывают сессии, которые ожидают освобождения блокировок.

Таким образом можно проследить цепочки сессий, ожидающих освобождения блокировок.

Операция `История` позволяет просмотреть исторические данные по блокировкам БД.

#### Журнал алертов
Специальный журнал, в который периодически пишется информация о выявленных проблемах.

Журнал заполняется по средствам фоновых заданий:
1. `Сохранить Долгий запрос` - `Btk_SlowQueryHistoryUpdate`
2. `Сохранить размер таблиц на дату` - `Btk_TableSizeHistoryUpdate`

События записываемые в журнал:
1. Запрос БД выполняется более 15 минут
2. Резкое увеличение размеров таблиц
3. На таблице выключен автовакуум
4. Транзакция в БД выполняется более 15 минут
5. Фоновое задание с ночным расписанием выполняется в дневное время

## Мониторинг телеметрии в Grafana
### Общая информация о внешних средствах мониторинга и телеметрии

Внешний мониторинг организован следующим образом:
1. Сервер приложений, используя стандарт `OpenTelemetry` отправляет метрики, трассировки и логи во внешний сервис (коллектор).
2. Коллектор перенаправляет метрики, трассировки и логи в инструмент визуализации данных `Grafana`
4. В `Grafana` реализованы дашборды визуализации метрик и трассировки.

#### Конфигурирование сервера приложений
В сервере приложений в каталоге с конфигурациями (../application/config) располагаются конфигурационные файлы телеметрии:
- `otel-globalserver.config.yaml`\
   Основной конфигурационный файл OpenTelemetry SDK. Управляет активностью телеметрии и настройками экспорта.
- `otel-sdk.config.yaml`\
   Дополнительный конфигурационный файл. Управляет настройками системной телеметрии, специфичной для сервера приложений.

[Документация телеметрии сервера приложений](https://docs.global-system.ru/as/dev/spec/services/telemetry/index.html#gs3-telemetry)

Основные моменты:
1. Для включения телеметрии сервера приложений необходимо настроить файл `otel-globalserver.config.yaml`
   - включить телеметрию общим флагом (`disabled: false`)
   - настроить `endpoint`-ы для коллекторов метрик, логов и трассировки
2. Изменения конфигурационных файлов применятся только после перезагрузки экземпляра сервера приложений.   


#### Grafana как средство визуализации
[Grafana](https://grafana.com) — это платформа с открытым исходным кодом для визуализации, мониторинга и анализа данных.

Позволяет отображать данные в графическом виде из разных источников данных.

В нашем мониторинге используются следующие источники данных:
- `Prometheus` - база данных метрик 
- `Loki` - база данных логов
- `Tempo` - система хранения трассировок



#### Основы стандарта OpenTelemetry
[OpenTelemetry](https://opentelemetry.io) - стандарт сбора и передачи телеметрических данных.
Стандарт описывает набор практик и инструментов, определяющих, какие сигналы может генерировать приложение.

Три основных типа сигналов:
- `метрики`
- `трассировка`
- `логи`

Каждый сигнал может обладать рядом дополнительных свойств, которые могут характеризовать событие, с которым связан сигнал.
Например:
- `Имя пользователя`
- `Кластерный узел`
- и тд.

##### Метрики
`Метрики` - количественные данные о работе системы.
Например:
- Время выполнение операции
- Количество успешно выполненных операций
- Количество ошибок при выполнении операций. 
- Время выполнения запроса к БД
- и тд.

Метрики делятся на несколько типов:
- `Counter (увеличивающийся счетчик)`\
  Представляет из себя метрику, которая увеличивается с течением времени. Например, количество запросов к БД.
- `UpDownCounter (увеличивающийся и уменьшающийся счетчик)`\
  Представляет из себя метрику, которая может как увеличиваться так и уменьшаться с течением времени. Например, количество подключений к БД 
- `Gauge (измеритель, спидометр)`\
  Представляет из себя метрику, которая используется для измерения чего-либо в конкретный момент времени. Например, время выполнения запроса к БД   
- `Histogram (гистограмма)`\
  Позволяет накапливать исторические данные на клиентской стороне, и затем отправлять их сигналом во внешний мир.   

##### Трассировка
В стандарте `OpenTelemetry` реализована через объекты с типом `span`.

`Span` - сигнал, который имеет начало и конец, а так же может иметь родительский `span`. С помощью этих сигналов можно
построить дерево трассировки, вкладывая `span`-ы друг в друга, и отмечая начало и конец события.

Пример дерева `span-ов`:

```
+ Выполнение операции 
  |_+ Выполнение запроса к серверу приложений
    |_+ Выполнение запроса к БД
    |_+ Обработка результатов запроса к БД
```
##### Логи
Сигнал, который из себя представляет логовую запись, сделанную системой. 

### Типы и виды метрик сервера приложений
Сервер приложений посылает различные виды сигналов. Часть из них отправляется сервером приложений, другая же часть прикладным решением.
#### Системные метрики
Метрики сервера приложений, настраиваемые через `Администратор метрик`:
- `Время реакции на действие пользователя`
  - `rpc.server.duration.nanos` - длительность обработки `RPC` сервером. Число наносекунд.
  - `rpc.client.duration.millis` - длительность выполнения `RPC` с точки зрения клиента, равная длительность передачи по сети + длительность обработки `RPC` сервером. Число миллисекунд

[Полный перечень метрик сервера приложений](https://docs.global-system.ru/as/dev/spec/services/telemetry/index.html#id13)  


#### Прикладные метрики и трассировки
Метрики и трассировки, отправляемые из кода прикладного решения.
##### Метрики пользовательских операций
Специальные метрики, которые отслеживают выполнение пользователем операций в пользовательском интерфейсе. 
На каждое выполнение операции осуществляется отправка различных метрик:
- `btk_item_telemetry.user_operation_exec_time` - время выполнения операции
- `btk_item_telemetry.user_operation_calls_total` - количество вызовов операции
- `btk_item_telemetry.user_operation_calls_successful` - количество успешных вызовов операции
- `btk_item_telemetry.user_operation_calls_failed` - количество неуспешных вызовов операции

Атрибуты метрик:
- `solution` - Имя решения из конфигурации сервера приложений 
- `userName` - Имя пользователя
- `session.sid` - Sid сессии сервера приложений
- `work.session.sid` - Sid рабочего сеанса сервера приложений
- `cluster.node` - имя кластерного узла
- `selection.name` - имя выборки
- `representation.name` - имя отображения
- `selection.caption` - наименование выборки
- `oper.name` - имя операции
- `oper.caption` - наименование операции
- `form.name` - имя главной выборки формы
- `form.caption` - наименование главной выборки формы
- `form.representation.name` - имя отображения главной выборки формы 

##### Трассировки пользовательских операций
- `btk_item_telemetry.user_operation_trace` - трассировка выполнения операции.
  
  Пишется при выполнении пользователем какой-либо операции или сеттера.
  На каждое пользовательское действие создается `span`, если это действие вызвало другие операции или события, они будут добавлены в дерево трассировки.

- `btk_item_telemetry.open_selection_trace` - трассировка открытия выборки.

  Пишется, если на выборку целиком включена трассировка или для пользователя включена вся телеметрия.
  Представляет из себя дерево `span`-ов, в котором будут отображены все операции, события и сеттеры, выполняемые при открытии выборки.

  Если выборка имеет дочерние выборки, то трассировка их открытия, так же будет добавлена в дерево `span-ов.

Атрибуты трейсов:
- `solution` - Имя решения из конфигурации сервера приложений 
- `userName` - Имя пользователя
- `session.sid` - Sid сессии сервера приложений
- `work.session.sid` - Sid рабочего сеанса сервера приложений
- `cluster.node` - имя кластерного узла
- `selection.name` - имя выборки
- `representation.name` - имя отображения
- `selection.caption` - наименование выборки
- `oper.name` - имя операции
- `oper.caption` - наименование операции
- `form.name` - имя главной выборки формы
- `form.caption` - наименование главной выборки формы
- `form.representation.name` - имя отображения главной выборки формы   


##### Метрики и трассировки, объявленные в прикладных модулях
Разработчики в прикладном коде могут объявлять собственные метрики и трассировки для реализации телеметрии в каких-либо высоко-нагруженных местах.

######  Пример работы с объектной метрикой
1. Объявление метрики (вызов требуется добавить в dataInstall)
   ```scala
   //Объявление метрики с именем Some_Metric_Name, которая относится к Адм. объекту Some_ObjectName
   Btk_AcObjectMetricApi().register(
      Btk_AcObjectApi().findByMnemoCode("Some_ObjectName"),
      "Some_Metric_Name",
      "Пример метрики прикладного кода",
      "Демонстрация использования прикладной метрики "
   )
   ```

2. Использование метрики в коде   
   ```scala
   //получение счетчика
   Btk_TelemetryPkg().getAcObjectLongCounter("Some_Metric_Name", "Some_Metric_Name").foreach{counter =>
      //увеличение счетчика, если эта метрика включена в администраторе метрик
      counter.add(42)
   }
   ```

######  Пример работы с объектной трассировкой
1. Объявление трассировки
   ```scala
   //Объявление трассировки с именем Some_Trace_Name, которая относится к Адм. объекту Some_ObjectName
   Btk_AcObjectTraceApi().register(
      Btk_AcObjectApi().findByMnemoCode("Some_ObjectName"),
      "Some_Trace_Name",
      "Пример метрики прикладного кода",
      "Демонстрация использования прикладной метрики "
   )
   ```
2. Использование трассировки
   ```scala
   //получение счетчика
   Btk_TelemetryPkg().getAcObjectTrace("Some_Trace_Name", "Some_Metric_Name").foreach{spanBuilder =>
     //выполнение действий с созданием span-а. Перед началом действия создается span, по окончанию действия - span закрывается.
     spanBuilder.forSpan{span =>
       try {
         //код выполнения
         Thread.sleep(5000)
       } finally {
         //закрытие span-а
         span.end()
       }
     }
   }
   ```


##### Ядровые метрики приложения
- `app.transaction.active.count` - Кол-во открытых транзакций БД 
- `app.jexl.count` - Кол-во выполненных jexl скриптов
- `app.rest.count` - Кол-во полученных Rest-запросов
- `app.error.count` - Кол-во ошибок (бизнес-логика)
- `app.setting.change.count` - Число измененных системных настроек

##### Метрики использованных ячеек памяти
- `app.work_session.ui_cell.count` - Кол-во ui-ячеек
- `app.work_session.ui_row.count` - Кол-во ui-строк
- `app.work_session.read_cell.count`  - Кол-во загруженных ячеек
- `app.work_session.insert_cell.count` - Кол-во созданных ячеек 
- `app.work_session.update_cell.count` - Кол-во измененных ячеек

Атрибуты метрик:
- `solution` - Имя решения из конфигурации сервера приложений
- `user` - Имя пользователя
- `session_id` - Sid сессии сервера приложений
- `session_kind` - Тип сессии сервера приложений

#### Метрики фоновых заданий
- `app.job.active.count` - Количество активных джобов
- `app.job.run.failed` - Количество ошибок джобов

Включение и фильтрация прикладных метрик осуществляется через `Администратор метрик`

### Администратор метрик
Инструмент, который позволяет управлять активностью и фильтрацией прикладных и серверных метрик.

Расположен `Приложение Администратор` - `Настройки` - `Телеметрия`.

В интерфейсе слева располагается список с возможными настройкам, справа - отображается выборка этих настроек.

#### Управление прикладными метриками
##### Адм. объекты
Эта настойка позволяет включить метрики и трассировку для операций пользовательского интерфейса.
Представляет из себя дерево, где корневым узлом является `администрируемый объект`, на втором уровне расположены выборки, входящие в этот объект.

Варианты включения:
- Конкретная операция
- Выборка целиком
- Бизнес объект целиком
- для всех пользователей
- для конкретных пользователей

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

##### Пользователи
Настройка, которая позволяет включить все прикладные метрики и трассировки для конкретного пользователя.
Если пользователь добавлен в этот список, и включен признак `Включена вся телеметрия`, то будет оправляться телеметрия по всем операциям и объектным метрикам и трассировкам.

##### Объектные метрики и трассировки
Инструмент, предназначенный для объявления метрик и трассировок прикладного кода. Позволяет разработчикам объявить
свои собственные метрики и трассировки, и использовать как телеметрию для особо-нагруженных или проблемных участков 
кода приложения.

Основной принцип работы:
1. Разработчик регистрирует метрику или трассировку в специализированном справочнике, присвоив им уникальное системное имя.
2. В прикладном коде в необходимых местах отправляет значения метрик или трассировки, используя методы пакета `ru.bitec.app.btk.telemetry.Btk_TelemetryPkg`
3. В `администраторе метрик` администратор включает или выключает активность объектных метрик и трассировок.



#### Управление системными метриками
Управляется через закладку `Серверная телеметрия`.
Позволяет настроить необходимость отправки метрик сервера приложений для всех пользователей и для конкретных.

Управляет метриками `Время реакции на действие пользователя` сервера приложений.

### Grafana
Графана поставляется как отдельный сервис.
Если система развернута в виде кластера `Kubernetes`, то по умолчанию для подключения к веб-интерфейсу используется 3000 порт основного адреса.
Т.е. если для входа в систему используется адрес `http://192.168.29.17`, то для подключения к веб-интерфейсу графаны используется адрес `http://192.168.29.17:3000/`. 
Это может быть изменено, и конфигурируется системным администратором.

Для проектов, где система развернута не через кластер `Kubernetes`, адрес подключения определяется системным администратором.
#### Запрос метрик
Для просмотра логов выполните следующие действия:
1. В меню выберите `Explore`
2. Выберите источник данных `Prometheus`
3. Добавьте новый запрос, если требуется
4. Укажите один из фильтров:
   - `metric` - имя конкретной метрики
   - `label` - дополнительные атрибуты метрики:
      - `program_name` - имя сервиса, поставщика метрик. (globalserver, globalscheduller и тд. ) 
      - `podname` - имя кластерного узла
      - и тд.
5. Выполните запрос, нажав `Run query`   

![](./img/monitoring_metrics.png)

#### Запрос трассировки
Для просмотра трассировки выполните следующие действия:
1. В меню выберите `Explore`
2. Выберите источник данных `Tempo`
3. Добавьте новый запрос, если требуется
4. Укажите `QueryType` = `Search`
5. Укажите один из фильтров:
   - `Service Name` - имя сервиса, поставщика метрик. (globalserver, globalscheduller и тд. ) 
   - `Span Name` - имя трассировки
6. Выполните запрос, нажав `Run query`   

![](./img/monitoring_trace.png)

#### Просмотр логов	
Для просмотра логов выполните следующие действия:
1. В меню выберите `Explore`
2. Выберите источник данных `Loki`
3. Добавьте новый запрос, если требуется
4. Укажите один из фильтров:
   - `filename` - имя файла логов
   - `log` - имя сервиса, чьи логи требуется просмотреть (globalserver, globalscheduller и тд. ) 
   - `podname` - имя кластерного узла
5. Выполните запрос, нажав `Run query`   

![](./img/monitoring_logs.png)

#### Дашборды
Графана поставляется с преднастроенными дашбордами, которые позволяют отобразить ту или иную информацию.


Для просмотра логов выполните следующие действия:
1. В меню выберите `Dashboards`
2. В появившемся списке выберите нужный дашборд.

![](./img/monitoring_dashboards.png)