5.10. Телеметрия#

Сервер приложений предоставляет возможность экспорта телеметрической информации (трассировка, метрики и логи) во внешние аналитические системы (Grafana) по стандарту OpenTelemetry.

Функциональность реализуется библиотекой OpenTelemetry Sdk v.1.34.0.

See also

GTK Core Telemetry Api

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

Трассировки необходимы для понимания полного «пути», который проходит запрос в приложении.

See also

5.10.1.1. Диапазон трассировки (Span)#

Диапазон представляет собой отдельную операцию в пределах трассировки. Диапазоны могут быть вложены друг в друга, образуя дерево трассировки. Диапазон создаётся перед выполнением (в начале) трассируемого действия вызовом метода CoreTracer.startSpan() и завершается после (в конце) трассируемого действия вызовом метода CoreSpan.end().

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();
}

See also

5.10.1.2. Приостанавливаемый диапазон (Pausable Span)#

Каждому рабочему сеансу с графическим интерфейсом выделяется поток, обрабатывающий команды, поступающие от клиентского приложения. Обработка команд выполняется в бесконечном цикле. Если обработка команды привела к открытию модального окна или диалога в интерфейсе пользователя, поток входит во вложенный цикл обработки команд. Это позволяет сохранить (не раскручивать) стек вызовов, приведший к открытию модальной формы (диалога). Выход из вложенного цикла произойдёт после закрытия модального окна (диалога). Поток может находиться во вложенном цикле неограниченное время, т.к. пользователь может сколь угодно долго не закрывать модальную форму.

Наличие вложенных циклов приводит к искажению картины трассировки в аналитической системе (Grafana). Из-за того что все созданные, до момента открытия формы (диалога), диапазоны трассировки остаются активными и завершение диапазонов произойдёт только после закрытия формы (диалога) и выхода из вложенного цикла обработки команд, к длительности обработки команд могут добавляться неопределённые интервалы времени.

Для устранения времени ожиданий из трассировок, рабочим сеансам с графическим интерфейсом добавлен механизм приостановки активности всех диапазонов трассировки потока на время не активности потока:

  • диапазоны завершаются при входе потока во вложенный цикл обработки команд.

  • диапазоны воссоздаются перед началом обработки команды вложенным циклом.

  • диапазоны завершаются после обработки команды вложенным циклом.

  • диапазоны воссоздаются после выхода потока из вложенного цикла.

5.10.1.3. Ленивый диапазон (Lazy Span)#

Диапазоны трассировок определяются в коде. Экземпляры CoreSpan создаются не зависимо от активности трассировки в конфигурационном файле. С увеличением объёма бизнес-логики и числа пользователей увеличивается число трассировок. Для возможности включения трассировок для отдельных участков прикладного кода и/или пользователей реализован механизм создания ленивых диапазонов трассировок.

CoreTelemetry coreTelemetry = CoreServer$.MODULE$.getInstance().getCurrentSolution().getTelemetry();
CoreTracer tracer = coreTelemetry.getTracer("ru.bitec.app.module");
CoreSpan span = tracer.startSpan("traced_action",
     new HashMap<String, Object>() {{
         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

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

Ленивые диапазоны активируются при:

Caution

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

События, записанные методами CoreSpan.addEvent() и CoreSpan.recordException() в ленивый диапазон до его активации, не будут переданы в аналитическую систему.

5.10.2. Метрики#

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

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

Доступные инструменты

  • Счётчик

  • Гистограмма

  • Спидометр

See also

OpenTelemetry Metrics GTK Core Telemetry Api

5.10.3. Логи#

Перенаправление стандартных Java логов на внешний сервер телеметрии.

See also

OpenTelemetry Logs

5.10.4. Конфигурирование#

Конфигурирование выполняется с помощью файлов otel-sdk.config.yaml и otel-globalserver.config.yaml, по умолчанию размещённых в каталоге {G3_HOME}\application\config.

See also

Параметры запуска программы

5.10.4.1. Конфигурационные файлы#

Значения параметров конфигурационных файлов могут ссылаться на параметры окружения, используя директиву ${env:PARAMETER_NAME}.

5.10.4.1.1. otel-sdk.config.yaml#

Основной конфигурационный файл OpenTelemetry SDK. Управляет активностью телеметрии и настройками экспорта.

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

See also

OpenTelemetry File Configuration
JSON Schema Definitions for OpenTelemetry File Configuration
Пример с полным перечнем опций
5.10.4.1.1.1. Период агрегации значений#

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

Возможные значения:

  • cumulative - Измерения агрегируются в течение всего срока работы инструмента.

  • delta - Для части инструментов измерения агрегируются с момента предыдущей отправки в коллектор.

  • lowmemory - Режим уменьшения использования памяти. Для части инструментов измерения агрегируются с момента предыдущей отправки в коллектор.

meter_provider:
  readers:
    - periodic:
        exporter:
          otlp:
            # cumulative / delta / lowmemory
            temporality_preference: delta

Параметр конфигурации, в зависимости от типа инструмента, влияет на само значение метрики и частоту отправки метрик в коллектор.

При значении cumulative (по умолчанию):

Инструмент

Периодичность отправки

Отправляемое значение

Counter

Всегда

Кумулятивное

UpDown

Всегда

Кумулятивное

Histogram

Всегда

Кумулятивное

Gauge

Если установлено

Установленное

При значении delta:

Инструмент

Периодичность отправки

Отправляемое значение

Counter

Если установлено

Изменение

UpDown

Всегда

Кумулятивное

Histogram

Если установлено

Изменение

Gauge

Если установлено

Установленное

При значении lowmemory:

Инструмент

Периодичность отправки

Отправляемое значение

Counter

Если установлено

Изменение

UpDown

Всегда

Кумулятивное

Histogram

Если установлено

Изменение

Gauge

Если установлено

Установленное

Note

Если установлено - если значение было установлено с момента предыдущей отправки метрик в коллектор.
Изменение - изменение значения с момента предыдущей отправки в коллектор.
Установленное - последнее установленное значение с момента предыдущей отправки в коллектор.

5.10.4.1.2. otel-globalserver.config.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

5.10.4.2. Перенаправление логов#

Перенаправление логов Logback на сервер сбора телеметрии выполняется путём добавления OpenTelemetryAppender в конфигурацию Logback. Возможны 2 варианта добавления OpenTelemetryAppender в конфигурацию: ручной и автоматический. Для обоих случаев необходимы:

  • активность телеметрии otel-sdk.config.yaml/disabled: false

  • активность перенаправления логов otel-globalserver.config.yaml/instrumentation/logback-appender/enabled: true

5.10.4.2.1. Ручное#

Для ручной настройки, в конфигурационные файлы logback-LoggerContext.xml и/или logback-LoggerContext-session.xml необходимо добавить раздел, определяющий аппендер OpenTelemetryAppender, и добавить аппендер к требуемым логгерам.

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <appender name="OpenTelemetry"
              class="io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender">
        <captureExperimentalAttributes>true</captureExperimentalAttributes>
        <captureKeyValuePairAttributes>true</captureKeyValuePairAttributes>
    </appender>
    <root level="INFO">
        <appender-ref ref="OpenTelemetry"/>
    </root>
</configuration>

5.10.4.2.2. Автоматическое#

Если в конфигурационных файлах отсутствуют настройки OpenTelemetryAppender, они будут автоматически добавлены в корневой Logger(“ROOT”).

5.10.4.3. Настройки телеметрии для решения#

Настройки телеметрии для решения сохраняются в таблицу “global_system.gtk_telemetrysettings”.

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, для уведомления всех узлов кластера об изменении настроек, необходимо вызвать метод CoreTelemetry.fireSettingsVersionChanged().

При получении уведомления об изменении настроек будет вызван метод CoreTelemetryEventHandler.handleSettingsVersionChanged() объекта, полученного из CoreSolutionImageContext.telemetryEventHandler().

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

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

Клиент и сервер взаимодействуют используя RPC через WebSocket. Они фиксируют длительность выполнения каждого вызова. Телеметрическая информация о выполненных ранее вызовах передаётся с клиента вместе с очередным RPC, или через 2 секунды после получения ответа, в специальном системном сообщении.

Сервер, получив телеметрическую информация от клиента, направляет её в вызов метода CoreTelemetry.EventHandler.onEvent(event). Передаваемый в метод экземпляр CoreCompositeMetricRawDataEvent содержит в себе два экземпляра CoreMetricRawDataEvent со значениями двух метрик:

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

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

В коде прикладного модуля GTK, где реализован метод CoreTelemetry.EventHandler.onEvent(event), производится фильтрация событий телеметрии, на основе прикладных правил, и добавление информации в инструменты OpenTelemetry.

Note

На активность метрики влияют:

5.10.5.2. Длительность загрузки#

Сервер собирает статистику и отправляет метрики в коллектор телеметрии, указанный в конфигурационном файле otel-sdk.config.yaml.

Передаваемые метрики:

  • server.startup.duration - Double Counter (s). Длительность загрузки сервера приложений. От момента создания экземпляра, до завершения запуска web-сервера и его web-узлов. Метрика отправляется только один раз за время жизни экземпляра сервера приложений.

5.10.5.3. Ошибки#

Сервер собирает статистику и отправляет метрики в коллектор телеметрии, указанный в конфигурационном файле otel-sdk.config.yaml.

Передаваемые метрики:

  • server.error.count - Long Counter ({error}). Общее количество ошибок (выброшенных исключений) за время работы сервера приложений.

    Атрибут

    Значение

    cause_class

    Имя класса исходного исключения

5.10.5.4. Пулы соединений с БД#

Сервер собирает статистику и отправляет метрики в коллектор телеметрии, указанный в конфигурационном файле otel-sdk.config.yaml.

Передаваемые метрики:

  • db.client.connection.count - Long UpDownCounter ({connection}). Количество соединений, которые в данный момент находятся в состоянии, описанном атрибутом state.

    Атрибут

    Значение

    state

    used или idle

    pool_name

    {SOLUTION}[-{POOL}]/{SCHEMA}*

  • db.client.connection.idle.max - Long UpDownCounter ({connection}). Максимально допустимое количество неактивных открытых соединений.

    Атрибут

    Значение

    pool_name

    {SOLUTION}[-{POOL}]/{SCHEMA}*

  • db.client.connection.idle.min - Long UpDownCounter ({connection}). Минимальное количество неактивных открытых соединений.

    Атрибут

    Значение

    pool_name

    {SOLUTION}[-{POOL}]/{SCHEMA}*

  • db.client.connection.max - Long UpDownCounter ({connection}). Максимально допустимое количество открытых соединений.

    Атрибут

    Значение

    pool_name

    {SOLUTION}[-{POOL}]/{SCHEMA}*

  • db.client.connection.pending_requests - Long UpDownCounter ({request}). Количество ожидающих запросов на открытое соединение, суммарно для всего пула..

    Атрибут

    Значение

    pool_name

    {SOLUTION}[-{POOL}]/{SCHEMA}*

  • db.client.connection.timeouts - Long Counter ({timeout}). Количество таймаутов соединения, произошедших при попытке получить соединение из пула.

    Атрибут

    Значение

    pool_name

    {SOLUTION}[-{POOL}]/{SCHEMA}*

  • db.client.connection.wait_time - Double Histogram ({s}). Время, необходимое для получения соединения из пула.

    Атрибут

    Значение

    pool_name

    {SOLUTION}[-{POOL}]/{SCHEMA}*

* Где:

5.10.5.5. HTTP-соединения#

Сервер собирает статистику и отправляет метрики в коллектор телеметрии, указанный в конфигурационном файле otel-sdk.config.yaml.

Передаваемые метрики:

5.10.5.6. Рабочие сеансы#

Сервер собирает статистику и отправляет метрики в коллектор телеметрии, указанный в конфигурационном файле otel-sdk.config.yaml.

Передаваемые метрики:

  • server.session.count Long UpDownCounter ({sessions}). Количество рабочих сеансов.

    Атрибут

    Значение

    kind

    ENGINE, SOAP, REST, SSH, WS

    solution

    {SOLUTION}*

* Где:

5.10.5.7. Кластер#

Сервер собирает статистику и отправляет метрики в коллектор телеметрии, указанный в конфигурационном файле otel-sdk.config.yaml.

Передаваемые метрики:

  • cluster.node.count Long UpDownCounter ({sessions}). Количество узлов кластера.
    Метрика передаётся только с узла-координатора кластера.

    Атрибут

    Значение

    cluster_name

    {cluster_name}*

* Где: