.. _gs3_telemetry: Телеметрия ============ :term:`Сервер приложений ` предоставляет возможность экспорта телеметрической информации (трассировка, метрики и логи) во внешние аналитические системы (`Grafana `_) по стандарту `OpenTelemetry `_. Функциональность реализуется библиотекой `OpenTelemetry Sdk v.1.34.0 `_. .. seealso:: :java:type:`GTK Core Telemetry Api ` Трассировки ------------ Трассировки необходимы для понимания полного «пути», который проходит запрос в приложении. .. seealso:: - `OpenTelemetry Traces `_ - :java:type:`CoreTracer ` Диапазон трассировки (Span) `````````````````````````````````````````````` Диапазон представляет собой отдельную операцию в пределах трассировки. Диапазоны могут быть вложены друг в друга, образуя дерево трассировки. Диапазон создаётся перед выполнением (в начале) трассируемого действия вызовом метода :java:meth:`CoreTracer.startSpan()` и завершается после (в конце) трассируемого действия вызовом метода :java:meth:`CoreSpan.end()`. .. code-block:: java CoreTelemetry coreTelemetry = CoreServer$.MODULE$.getInstance().getCurrentSolution().getTelemetry(); CoreTracer tracer = coreTelemetry.getTracer("ru.bitec.app.module"); CoreSpan span = tracer.startSpan("traced_action", new HashMap<>(), new HashMap<>(), new HashMap<>()); try { span.addEvent("do_work"); } finally { span.end(); } .. seealso:: - `OpenTelemetry Span `_ - :java:type:`CoreSpan ` .. _gs3_telemetry_pausable_span: Приостанавливаемый диапазон (Pausable Span) `````````````````````````````````````````````` Каждому рабочему сеансу с графическим интерфейсом выделяется поток, обрабатывающий команды, поступающие от клиентского приложения. Обработка команд выполняется в бесконечном цикле. Если обработка команды привела к открытию :java:meth:`модального окна ` или :java:meth:`диалога ` в интерфейсе пользователя, поток входит во вложенный цикл обработки команд. Это позволяет сохранить (не раскручивать) стек вызовов, приведший к открытию модальной формы (диалога). Выход из вложенного цикла произойдёт после закрытия модального окна (диалога). Поток может находиться во вложенном цикле неограниченное время, т.к. пользователь может сколь угодно долго не закрывать модальную форму. Наличие вложенных циклов приводит к искажению картины трассировки в аналитической системе (Grafana). Из-за того что все созданные, до момента открытия формы (диалога), диапазоны трассировки остаются активными и завершение диапазонов произойдёт только после закрытия формы (диалога) и выхода из вложенного цикла обработки команд, к длительности обработки команд могут добавляться неопределённые интервалы времени. Для устранения времени ожиданий из трассировок, рабочим сеансам с графическим интерфейсом добавлен механизм приостановки активности всех диапазонов трассировки потока на время не активности потока: - диапазоны завершаются при входе потока во вложенный цикл обработки команд. - диапазоны воссоздаются перед началом обработки команды вложенным циклом. - диапазоны завершаются после обработки команды вложенным циклом. - диапазоны воссоздаются после выхода потока из вложенного цикла. .. _gs3_telemetry_lazy_span: Ленивый диапазон (Lazy Span) ``````````````````````````````` Диапазоны трассировок определяются в коде. Экземпляры :java:type:`CoreSpan` создаются не зависимо от активности трассировки в :ref:`конфигурационном файле `. С увеличением объёма бизнес-логики и числа пользователей увеличивается число трассировок. Для возможности включения трассировок для отдельных участков прикладного кода и/или пользователей реализован механизм создания ленивых диапазонов трассировок. .. code-block:: java CoreTelemetry coreTelemetry = CoreServer$.MODULE$.getInstance().getCurrentSolution().getTelemetry(); CoreTracer tracer = coreTelemetry.getTracer("ru.bitec.app.module"); CoreSpan span = tracer.startSpan("traced_action", new HashMap() {{ put(SpanOptions.LAZY, true); put(SpanOptions.MAX_LAZY_DURATION_NANOS, TimeUnit.SECONDS.toNanos(2)); }}, new HashMap<>(), new HashMap<>()); try { span.addEvent("do_work"); } finally { span.end(); } .. note:: При активации ленивого диапазона создаётся "реальный" диапазон, регистрирующий события, и отображаемый в аналитической системе. Ленивые диапазоны активируются при: - создании вложенного не ленивого диапазона. - активации вложенного ленивого диапазона. - длительность трассируемого действия превышает :java:meth:`максимальную длительность пребывания диапазона в неактивном состоянии `. Создание "реального" диапазона происходит при вызове :java:meth:`CoreSpan.end()` для ленивого диапазона. .. caution:: Ленивые диапазоны реализованы только для рабочих сеансов с графическим интерфейсом. События, записанные методами :java:meth:`CoreSpan.addEvent()` и :java:meth:`CoreSpan.recordException()` в ленивый диапазон до его активации, не будут переданы в аналитическую систему. Метрики ------------ Метрика — это измерение услуги, полученное во время выполнения. Момент регистрации измерений известен как метрическое событие, которое состоит не только из самого измерения, но также из времени, в которое оно было получено, и связанных с ним метаданных. Метрики приложений и запросов являются важными показателями доступности и производительности. Пользовательские метрики могут дать представление о том, как индикаторы доступности влияют на взаимодействие с пользователем или на бизнес. Собранные данные можно использовать для оповещения о сбое или принятия решений по планированию для автоматического масштабирования развертывания при высоком спросе. Доступные инструменты - Счётчик - Гистограмма - Спидометр .. seealso:: `OpenTelemetry Metrics `_ :java:type:`GTK Core Telemetry Api ` Логи ------------ Перенаправление стандартных Java логов на внешний сервер телеметрии. .. seealso:: `OpenTelemetry Logs `_ .. _gs3_telemetry_configuring: Конфигурирование ----------------- Конфигурирование выполняется с помощью файлов ``otel-sdk.config.yaml`` и ``otel-globalserver.config.yaml``, по умолчанию размещённых в каталоге ``{G3_HOME}\application\config``. .. seealso:: :ref:`server_command_line_params` Конфигурационные файлы `````````````````````` Значения параметров конфигурационных файлов могут ссылаться на параметры окружения, используя директиву ``${env:PARAMETER_NAME}``. otel-sdk.config.yaml ..................... Основной конфигурационный файл OpenTelemetry SDK. Управляет активностью телеметрии и настройками экспорта. .. code-block:: yaml file_format: "0.1" disabled: true resource: attributes: service.name: Global #service.name: ${env:OTEL_SERVICE_NAME} exporters: otlp: &otlp-exporter timeout: 10000 # https://opentelemetry.io/docs/specs/otel/protocol/exporter/#specify-protocol protocol: grpc endpoint: http://localhost:4318 logger_provider: processors: - batch: exporter: otlp: *otlp-exporter meter_provider: readers: - periodic: interval: 5000 timeout: 30000 exporter: otlp: *otlp-exporter tracer_provider: processors: - batch: exporter: otlp: *otlp-exporter .. seealso:: | `OpenTelemetry File Configuration `_ | `JSON Schema Definitions for OpenTelemetry File Configuration `_ | `Пример с полным перечнем опций `_ Период агрегации значений ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Настройка позволяет изменить период агрегирования измерений, передаваемых в коллектор. Возможные значения: - **cumulative** - Измерения агрегируются в течение всего срока работы инструмента. - **delta** - Для части инструментов измерения агрегируются с момента предыдущей отправки в коллектор. - **lowmemory** - Режим уменьшения использования памяти. Для части инструментов измерения агрегируются с момента предыдущей отправки в коллектор. .. code-block:: yaml meter_provider: readers: - periodic: exporter: otlp: # cumulative / delta / lowmemory temporality_preference: delta Параметр конфигурации, в зависимости от типа инструмента, влияет на само значение метрики и частоту отправки метрик в коллектор. При значении ``cumulative`` (по умолчанию): .. table:: :align: left ================= ======================== ====================== Инструмент Периодичность отправки Отправляемое значение ================= ======================== ====================== Counter Всегда Кумулятивное UpDown Всегда Кумулятивное Histogram Всегда Кумулятивное Gauge Если установлено Установленное ================= ======================== ====================== При значении ``delta``: .. table:: :align: left ================= ======================== ====================== Инструмент Периодичность отправки Отправляемое значение ================= ======================== ====================== Counter Если установлено Изменение UpDown Всегда Кумулятивное Histogram Если установлено Изменение Gauge Если установлено Установленное ================= ======================== ====================== При значении ``lowmemory``: .. table:: :align: left ================= ======================== ====================== Инструмент Периодичность отправки Отправляемое значение ================= ======================== ====================== Counter Если установлено Изменение UpDown Всегда Кумулятивное Histogram Если установлено Изменение Gauge Если установлено Установленное ================= ======================== ====================== .. note:: | ``Если установлено`` - если значение было установлено с момента предыдущей отправки метрик в коллектор. | ``Изменение`` - изменение значения с момента предыдущей отправки в коллектор. | ``Установленное`` - последнее установленное значение с момента предыдущей отправки в коллектор. otel-globalserver.config.yaml ............................. Дополнительный конфигурационный файл. Управляет настройками системной телеметрии, специфичной для сервера приложений. .. code-block:: yaml instrumentation: common: # Значение по умолчанию для всех существующих, но не указанных в конфигурационном файле опций. default-enabled: false # Активность JVM метрик (Classes, CPU, GarbageCollector, Threads, MemoryPools). runtime-telemetry: enabled: false # Активность экспериментальных JVM метрик (ExperimentalBufferPools, ExperimentalCPU, ExperimentalMemoryPools). emit-experimental-telemetry: enabled: false # Активность перенаправления логов (Logback) на сервер сбора телеметрии. logback-appender: enabled: false Перенаправление логов `````````````````````` Перенаправление логов Logback на сервер сбора телеметрии выполняется путём добавления `OpenTelemetryAppender `_ в конфигурацию Logback. Возможны 2 варианта добавления ``OpenTelemetryAppender`` в конфигурацию: ручной и автоматический. Для обоих случаев необходимы: - активность телеметрии ``otel-sdk.config.yaml``/``disabled: false`` - активность перенаправления логов ``otel-globalserver.config.yaml``/``instrumentation/logback-appender/enabled: true`` Ручное ....... Для ручной настройки, в конфигурационные файлы ``logback-LoggerContext.xml`` и/или ``logback-LoggerContext-session.xml`` необходимо добавить раздел, определяющий аппендер ``OpenTelemetryAppender``, и добавить аппендер к требуемым логгерам. .. code-block:: xml true true Автоматическое ............... Если в конфигурационных файлах отсутствуют настройки ``OpenTelemetryAppender``, они будут автоматически добавлены в корневой Logger("ROOT"). Настройки телеметрии для решения ```````````````````````````````````````````` Настройки телеметрии для решения сохраняются в таблицу "global_system.gtk_telemetrysettings". .. code-block:: sql CREATE TABLE global_system.gtk_telemetrysettings ( id int8 NOT NULL DEFAULT nextval('global_system.gtk_telemetrysettings_seq'::regclass), benabled int8 NOT NULL DEFAULT 0, nversion_dz int8 NOT NULL DEFAULT 0, CONSTRAINT gtk_telemetrysettings_pkey PRIMARY KEY (id) ); В которой поля: * ``benabled`` - флаг активности телеметрии. * ``nversion_dz`` - текущая версия настроек. Настройки считываются из базы в момент запуска решения. После внесения изменений в настройки и изменения версии в таблице ``global_system.gtk_telemetrysettings``, для уведомления всех узлов кластера об изменении настроек, необходимо вызвать метод :java:meth:`CoreTelemetry.fireSettingsVersionChanged()`. При получении уведомления об изменении настроек будет вызван метод :java:meth:`CoreTelemetryEventHandler.handleSettingsVersionChanged()` объекта, полученного из :java:meth:`CoreSolutionImageContext.telemetryEventHandler()`. Метрики сервера приложений ------------------------------ Время реакции на действия пользователя ``````````````````````````````````````` Клиент и сервер взаимодействуют используя :term:`RPC` через :term:`WebSocket`. Они фиксируют длительность выполнения каждого вызова. Телеметрическая информация о выполненных ранее вызовах передаётся с клиента вместе с очередным RPC, или через 2 секунды после получения ответа, в специальном системном сообщении. Сервер, получив телеметрическую информация от клиента, направляет её в вызов метода :java:meth:`CoreTelemetry.EventHandler.onEvent(event) `. Передаваемый в метод экземпляр :java:type:`CoreCompositeMetricRawDataEvent ` содержит в себе два экземпляра :java:type:`CoreMetricRawDataEvent ` со значениями двух метрик: - :java:field:`rpc.server.duration.nanos ` - длительность обработки RPC сервером. Число наносекунд. - :java:field:`rpc.client.duration.millis ` - длительность выполнения RPC с точки зрения клиента, равная ``длительность передачи по сети`` + ``длительность обработки RPC сервером``. Число миллисекунд. В коде прикладного модуля GTK, где реализован метод :java:meth:`CoreTelemetry.EventHandler.onEvent(event) `, производится фильтрация событий телеметрии, на основе прикладных правил, и добавление информации в инструменты OpenTelemetry. .. note:: На активность метрики влияют: - активность телеметрии для сервера, определяемая в конфигурационном файле: `otel-sdk.config.yaml`_. - активность телеметрии для решения: `настройки телеметрии для решения`_. Длительность загрузки ```````````````````````` Сервер собирает статистику и отправляет метрики в коллектор телеметрии, указанный в конфигурационном файле `otel-sdk.config.yaml`_. Передаваемые метрики: - ``server.startup.duration`` - Double Counter (s). Длительность загрузки сервера приложений. От момента создания экземпляра, до завершения запуска web-сервера и его web-узлов. Метрика отправляется только один раз за время жизни экземпляра сервера приложений. Ошибки ``````````````````````````` Сервер собирает статистику и отправляет метрики в коллектор телеметрии, указанный в конфигурационном файле `otel-sdk.config.yaml`_. Передаваемые метрики: - ``server.error.count`` - Long Counter ({error}). Общее количество ошибок (выброшенных исключений) за время работы сервера приложений. .. table:: :align: left ================= ================================= Атрибут Значение ================= ================================= ``cause_class`` Имя класса исходного исключения ================= ================================= Пулы соединений с БД ``````````````````````````` Сервер собирает статистику и отправляет метрики в коллектор телеметрии, указанный в конфигурационном файле `otel-sdk.config.yaml`_. Передаваемые метрики: - ``db.client.connection.count`` - Long UpDownCounter ({connection}). Количество соединений, которые в данный момент находятся в состоянии, описанном атрибутом ``state``. .. table:: :align: left ================= ================================= Атрибут Значение ================= ================================= ``state`` ``used`` или ``idle`` ``pool_name`` ``{SOLUTION}[-{POOL}]/{SCHEMA}``\* ================= ================================= - ``db.client.connection.idle.max`` - Long UpDownCounter ({connection}). Максимально допустимое количество неактивных открытых соединений. .. table:: :align: left ================= ================================= Атрибут Значение ================= ================================= ``pool_name`` ``{SOLUTION}[-{POOL}]/{SCHEMA}``\* ================= ================================= - ``db.client.connection.idle.min`` - Long UpDownCounter ({connection}). Минимальное количество неактивных открытых соединений. .. table:: :align: left ================= ================================= Атрибут Значение ================= ================================= ``pool_name`` ``{SOLUTION}[-{POOL}]/{SCHEMA}``\* ================= ================================= - ``db.client.connection.max`` - Long UpDownCounter ({connection}). Максимально допустимое количество открытых соединений. .. table:: :align: left ================= ================================= Атрибут Значение ================= ================================= ``pool_name`` ``{SOLUTION}[-{POOL}]/{SCHEMA}``\* ================= ================================= - ``db.client.connection.pending_requests`` - Long UpDownCounter ({request}). Количество ожидающих запросов на открытое соединение, суммарно для всего пула.. .. table:: :align: left ================= ================================= Атрибут Значение ================= ================================= ``pool_name`` ``{SOLUTION}[-{POOL}]/{SCHEMA}``\* ================= ================================= - ``db.client.connection.timeouts`` - Long Counter ({timeout}). Количество таймаутов соединения, произошедших при попытке получить соединение из пула. .. table:: :align: left ================= ================================= Атрибут Значение ================= ================================= ``pool_name`` ``{SOLUTION}[-{POOL}]/{SCHEMA}``\* ================= ================================= - ``db.client.connection.wait_time`` - Double Histogram ({s}). Время, необходимое для получения соединения из пула. .. table:: :align: left ================= ================================= Атрибут Значение ================= ================================= ``pool_name`` ``{SOLUTION}[-{POOL}]/{SCHEMA}``\* ================= ================================= \* Где: - ``{SOLUTION}`` - имя решения (алиас БД) :xsd:attr:`Configuration.Databases.Database.alias`. - ``{POOL}`` - имя пула :xsd:attr:`Configuration.Databases.Database.ExtraConnectionPool.Pool.name`. - ``{SCHEMA}`` - схема БД :xsd:attr:`Configuration.Databases.Database.schema`. HTTP-соединения ``````````````````````````` Сервер собирает статистику и отправляет метрики в коллектор телеметрии, указанный в конфигурационном файле `otel-sdk.config.yaml`_. Передаваемые метрики: - | ``http.server.request.duration`` Double Histogram (second). Длительность обработки HTTP-запроса. | `Open Telemetry Metric: http.server.request.duration `__. - | ``http.server.active_requests`` Long UpDownCounter ({requests}). Количество обрабатываемых HTTP-запросов. | `Open Telemetry Metric: http.server.request.duration `__. - | ``http.server.requests`` Long Counter ({requests}). Количество обработанных HTTP-запросов. Рабочие сеансы ``````````````````````````` Сервер собирает статистику и отправляет метрики в коллектор телеметрии, указанный в конфигурационном файле `otel-sdk.config.yaml`_. Передаваемые метрики: - | ``server.session.count`` Long UpDownCounter ({sessions}). Количество рабочих сеансов. .. table:: :align: left ================= ========================================================= Атрибут Значение ================= ========================================================= ``kind`` ``ENGINE``, ``SOAP``, ``REST``, ``SSH``, ``WS`` ``solution`` ``{SOLUTION}``\* ================= ========================================================= \* Где: - ``{SOLUTION}`` - имя решения (алиас БД) :xsd:attr:`Configuration.Databases.Database.alias`. Кластер ``````````````````````````` Сервер собирает статистику и отправляет метрики в коллектор телеметрии, указанный в конфигурационном файле `otel-sdk.config.yaml`_. Передаваемые метрики: - | ``cluster.node.count`` Long UpDownCounter ({sessions}). Количество узлов кластера. | Метрика передаётся только с узла-координатора кластера. .. table:: :align: left ================= ========================================================= Атрибут Значение ================= ========================================================= ``cluster_name`` ``{cluster_name}``\* ================= ========================================================= \* Где: - ``{cluster_name}`` - имя кластера :xsd:attr:`Configuration.Cluster.name`.