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

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

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

See also

GTK Core Telemetry Api

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

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

See also

OpenTelemetry Traces

5.10.2. Метрики#

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

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

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

  • Счётчик

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

  • Спидометр

See also

OpenTelemetry Metrics

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}*

* Где: