Перейти к основному содержанию
`Ctrl`+`K`

# Средства мониторинга работы системы.

Мониторинг системы реализован в двух независимых формах:

1. Средства мониторинга встроенные в сервер приложений
   Реализованы по средствам обычных пользовательских интерфейсов системы, и расположены в меню инструментов.

2. Внешние средства мониторинга
   Реализованы на основе протокола передачи телеметрии `OpenTelemetry`. Метрики передаются в инструмент визуализации `Grafana`

## Мониторинг в приложениях GlobalERP

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

### Монитор сессий сервера приложений

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

#### Пользовательские сеансы

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

Перечень основных столбцов:

- `Системное имя пользователя` и `Пользователь` - информация о пользователе

- `Ip-адрес клиента` - ip-адрес, с которого подключено клиентское приложение

- `Системное имя приложения` и `Приложение` - информация о запущенном приложении `Global`

- `Системное имя активной формы` и `Активная форма` - информация о текущей активной форме

- `Действие` - информация о выполняемых действиях сессии.

- `Кластерный узел` - Имя узла, к которому подключен клиент.

- `Имя базы данных` - имя БД, выбранное в окне логина при авторизации.

- `Блок квот` - отображает включены лы квоты на сессию, и текущие использованные ресурсы.

Перечень закладок:

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

- `Расшифровка` - отображает информацию об открытых формах пользовательской сессии.

- `Стек сеанса` - позволяет получить актуальный стек выполняемых действий пользовательской сессии.

#### Активные подключения к базе данных

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

Перечень основных столбцов:

- `Системное имя пользователя` и `Пользователь` - информация о пользователе.

- `Ip-адрес клиента` - ip-адрес, с которого подключено клиентское приложение.

- `Системное имя приложения` и `Приложение` - информация о запущенном приложении `Global`.

- `Системное имя активной формы` и `Активная форма` - информация о текущей активной форме.

- `Действие` - информация о выполняемых действиях сессии.

- `Кластерный узел` - Имя узла, к которому подключен клиент.

- `Имя базы данных` - имя БД, выбранное в окне логина при авторизации.

### Инструменты анализа Базы данных

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

#### Анализ размера таблиц

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

#### Работа автовакуума

Интерфейс, который отображает информацию о работе автоматической очистке таблиц.

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

Документация postgresql 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. Фоновое задание с ночным расписанием выполняется в дневное время.

#### Журнал размеров аудита

Доступен во вкладке `Найстройка системы > Аудит \ Анализ размеров аудита`. Содержит в себе размеры таблиц аудита. К ним относятся системные таблицы: телеметрия сервера, блокировки БД, открытие выборок и другие, описанные выше; а также таблицы конкретных бизнес-объектов, по которым ведётся аудит. Подробнее о структурах аудита БД.

Используется для поиска объектов системы, аудит которых занимает большое количество места на хранилище сервера. Позволяет:

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

2. Разделять количество записей аудита по уровням: от бизнес-объекта, до класса и отдельного атрибута.

3. Отключить аудит конкретного атрибута.

##### Структура отчёта

- Главная выборка - размер таблиц аудита.
  Список всех таблиц, хранящихся в табличном пространстве аудита (по умолчанию `AUD`) с указанием размера и кол-ва записей.

- Детализация первого уровня - классы наследники бизнес-объекта.
  Количество записей аудита дифференцированное по классам в рамках выбранного бизнес-объекта.

- Детализация второго уровня - атрибуты класса.
  Отражает кол-во записанных действий (добавление \ изменение \ удаление) по каждому атрибуту выбранного класса.

Примечание

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

##### Доступные операции

- В группе операций `Дополнительно`:

  - `Синхронизировать историю аудита выделенных классов` - инкрементальное обновление размера аудита атрибутов по выделенным классам.

  - `Синхронизировать историю аудита всех классов` - инкрементальное обновление размера аудита атрибутов всех классов. Работает аналогично ночной работе актуализации кэша.

  - `Пересчитать историю аудита выделенных классов` - полное обновление кэша. Полезно в том случае, если атрибуты класса были удалены\изменены.

##### Принципы заполнения

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

Поэтому данные о размерах аудита атрибутов кэшируются, при чём данные обновляются инкрементально (то есть обрабатываются только новые записи, добавленные после момента последнего кэширования). Это происходит каждую ночь в 5 утра.

Примечание

Если на таблицу аудита объекта установлено задание очистки, пересчёт кэша аудита атрибутов происходит автоматически. Подробнее о заданиях очистки.

Предупреждение

При удалении и переименовании атрибутов и чистке таблиц аудита объектов для корректности отображаемых данных ТРЕБУЕТСЯ пересчитывать кэш аудита (операция `Пересчитать историю аудита выделенных классов`).

## Мониторинг телеметрии в Grafana

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

Внешний мониторинг организован следующим образом:

1. Сервер приложений, используя стандарт `OpenTelemetry` отправляет метрики, трассировки и логи во внешний сервис (коллектор).

2. Коллектор перенаправляет метрики, трассировки и логи в инструмент визуализации данных `Grafana`.

3. В `Grafana` реализованы дашборды визуализации метрик и трассировки.

#### Конфигурирование сервера приложений

В сервере приложений в каталоге с конфигурациями (../application/config) располагаются конфигурационные файлы телеметрии:

- `otel-globalserver.config.yaml` - основной конфигурационный файл OpenTelemetry SDK. Управляет активностью телеметрии и настройками экспорта.

- `otel-sdk.config.yaml` - дополнительный конфигурационный файл. Управляет настройками системной телеметрии, специфичной для сервера приложений.

Документация телеметрии сервера приложений

Основные моменты:

1. Для включения телеметрии сервера приложений необходимо настроить файл `otel-globalserver.config.yaml`:

   - включить телеметрию общим флагом (`disabled: false`);

   - настроить `endpoint`-ы для коллекторов метрик, логов и трассировки.

2. Изменения конфигурационных файлов применятся только после перезагрузки экземпляра сервера приложений.

#### Grafana как средство визуализации

Grafana — это платформа с открытым исходным кодом для визуализации, мониторинга и анализа данных.

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

В нашем мониторинге используются следующие источники данных:

- `Prometheus` - база данных метрик;

- `Loki` - база данных логов;

- `Tempo` - система хранения трассировок.

#### Основы стандарта OpenTelemetry

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

Три основных типа сигналов:

- `метрики`;

- `трассировка`;

- `логи`.

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

- `Имя пользователя`;

- `Кластерный узел`;

- и тд.

##### Метрики

`Метрики` - количественные данные о работе системы. Например:

- Время выполнение операции.

- Количество успешно выполненных операций.

- Количество ошибок при выполнении операций.

- Время выполнения запроса к БД.

- и тд.

Метрики делятся на несколько типов:

- `Counter (увеличивающийся счетчик)` - представляет из себя метрику, которая увеличивается с течением времени. Например, количество запросов к БД.

- `UpDownCounter (увеличивающийся и уменьшающийся счетчик)` - представляет из себя метрику, которая может как увеличиваться так и уменьшаться с течением времени. Например, количество подключений к БД.

- `Gauge (измеритель, спидометр)` - представляет из себя метрику, которая используется для измерения чего-либо в конкретный момент времени. Например, время выполнения запроса к БД.

- `Histogram (гистограмма)` - позволяет накапливать исторические данные на клиентской стороне, и затем отправлять их сигналом во внешний мир.

##### Трассировка

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

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

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

    + Выполнение операции
      |_+ Выполнение запроса к серверу приложений
        |_+ Выполнение запроса к БД
        |_+ Обработка результатов запроса к БД

##### Логи

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

### Типы и виды метрик сервера приложений

Сервер приложений посылает различные виды сигналов. Часть из них отправляется сервером приложений, другая же часть прикладным решением.

#### Системные метрики

Метрики сервера приложений, настраиваемые через `Администратор метрик`:

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

  - `rpc.server.duration.nanos` - длительность обработки `RPC` сервером. Число наносекунд.

  - `rpc.client.duration.millis` - длительность выполнения `RPC` с точки зрения клиента, равная длительность передачи по сети + длительность обработки `RPC` сервером. Число миллисекунд.

Полный перечень метрик сервера приложений

#### Прикладные метрики и трассировки

Метрики и трассировки, отправляемые из кода прикладного решения.

##### Метрики пользовательских операций

Специальные метрики, которые отслеживают выполнение пользователем операций в пользовательском интерфейсе. На каждое выполнение операции осуществляется отправка различных метрик:

- `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):

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

2. Использование метрики в коде:

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

###### Пример работы с объектной трассировкой

1. Объявление трассировки:

       //Объявление трассировки с именем Some_Trace_Name, которая относится к Адм. объекту Some_ObjectName
       Btk_AcObjectTraceApi().register(
          Btk_AcObjectApi().findByMnemoCode("Some_ObjectName"),
          "Some_Trace_Name",
          "Пример метрики прикладного кода",
          "Демонстрация использования прикладной метрики "
       )

2. Использование трассировки:

       //получение счетчика
       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`.

#### Запрос трассировки

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

1. В меню выберите `Explore`.

2. Выберите источник данных `Tempo`.

3. Добавьте новый запрос, если требуется.

4. Укажите `QueryType` = `Search`.

5. Укажите один из фильтров:

   - `Service Name` - имя сервиса, поставщика метрик. (globalserver, globalscheduller и тд.).

   - `Span Name` - имя трассировки.

6. Выполните запрос, нажав `Run query`.

#### Просмотр логов

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

1. В меню выберите `Explore`.

2. Выберите источник данных `Loki`.

3. Добавьте новый запрос, если требуется.

4. Укажите один из фильтров:

   - `filename` - имя файла логов.

   - `log` - имя сервиса, чьи логи требуется просмотреть (globalserver, globalscheduller и тд.).

   - `podname` - имя кластерного узла.

5. Выполните запрос, нажав `Run query`.

#### Дашборды

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

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

1. В меню выберите `Dashboards`.

2. В появившемся списке выберите нужный дашборд.