TracingPlugin#

Описание плагина#

Плагин поддерживает стандарт OpenTelemetry. Плагин предназначен для:

1. формирования трассировки при следующих событиях:

   • поступление сообщения на брокер/уход сообщения с брокера(при вычитке сообщения consumer)

   • перемещение сообщения в expire, dead-letter - очереди

   • перемещение сообщения с одного брокера на другой в кластерном соединении при его дистрибуции

   • перемещение или удаление сообщения вручную (через веб-клиент Артемиса)

   • перемещение сообщения с одного брокера на другой в кластерном соединении при live-only scaleDown

2. формирования заголовка в сообщении о времени, когда сообщение покидает брокер(при его вычитке клиентом consumer)

Для трассировка необходима настройка - ru.sbt.ss.artemis.plugin.message.TracingPlugin

Подключение плагина#

Для подключения плагина к Artemis необходимо:

• сформировать конфигурационный файл tracingPlugin.conf, в котором должны быть указаны настройки плагина

• сформировать конфигурационный файл OpenTelemetry tracing.json

• в broker_instance_dir/etc/broker.xml необходимо добавить настройки плагина в разделе broker-plugins

• в classpath Artemis( e.g.:broker_instance_dir/lib) положить logger-plugin-*.jar-файл

Настройки плагина#

Для корректной работы плагина, необходимо на брокере в разделе address-settings установить настройку enable-ingress-timestamp в значение true.

При включении этой настройки, у всех сообщений, попадающих на сервер, формируется заголовок _AMQ_INGRESS_TIMESTAMP, который используется в плагине.

<address-settings>
    ...
    <address-setting match="#">
        ...
        <enable-ingress-timestamp>true</enable-ingress-timestamp>
        ...
    </address-setting>
    ...
</address-settings>

Настройки плагина, связанные с формированием трассировки#

* - идентификатор сообщения может быть указан в заголовке сообщения при его отправке на брокер. Если ни в одном из заголовков идентификатор не был найдены, то идентификатор ищется в поле userId внутреннего формата сообщения Artemis. В случае если и в userId отсутствует идентификатор, то идентификатор сообщения:UNDEFINED

** - в лог будут выведены только заголовки, которые присутствуют в сообщении

*** - по дефолту в лог трассировки не выводятся сообщения для следующих адресов: activemq.management, activemq.notifications и адресов с префиксом: $.artemis.internal., notif. Если настройка не указана или значение настройки является пустая строка, то фильтрация по BLACK_LIST_ADDRESSES отсутствует. Настройка поддерживает wildcard-синтаксис для адресов

**** - Если настройка не указана или значение настройки является пустая строка, то фильтрация по WHITE_LIST_ADDRESSES отсутствует. Настройка поддерживает wildcard-синтаксис для адресов

***** - если настройка не указана, то используется имя заголовка durable

Настройки плагина по формированию заголовка сообщения, в котором указывается время ухода сообщения с брокера#

Пример конфигурационного файла плагина tracingPlugin.conf#

  tracingPlugin: {
        OTEL_CONFIG_FILE: "./tracing.json"                  // обязательная настройка
        MODE: "ON or OFF"                                         // необязательная настройка
        MESSAGE_ID_HEADER_NAMES: "headerName_1, headerName_2"     // необязательная настройка
        HEADER_NAMES_FOR_LOG: "headerName"                        // необязательная настройка
        BLACK_LIST_ADDRESSES: "address_1, address_2, address 3"   // необязательная настройка
        WHITE_LIST_ADDRESSES: "address_21, address_22, address_33"// необязательная настройка
        DURABLE_HEADER_NAME: "_HDR_DURABLE_"                      // необязательная настройка
        TIMESTAMP_HEADERS_MODE: "ON_FOR_ALL"                      // необязательная настройка 
        FROM_SERVER_TIMESTAMP_HEADER_NAME: "TIMESTAMP_FROM_SERVER"// Обязательная настройка для режимов ON_FOR_ALL/ON_IF_EXIST
  }

При изменении настроек конфигурационного файла и его сохранении, будут применены обновленные настройки плагина

Пример настройки плагина в broker.xml#

<broker-plugins>
    <broker-plugin class-name="ru.sbt.ss.artemis.plugin.message.TracingPlugin">
        <property key="CONFIG_PATH" value="path_to_tracingPlugin_configuration" />          <!-- ОБЯЗАТЕЛЬНЫЙ путь до конфигурационного файла /-->
        <property key="RELOAD_CHECK_PERIOD_MS" value="period_in_ms" />                      <!-- необязательная периодичность проверки планировщиком обнаружения изменений в файле конфигурации в миллисекундах /-->
    </broker-plugin>
</broker-plugins>

Формат логов при трассировке сообщений#

Атрибуты в спанах#

Пример конфигурации плагина TracingPlugin tracing.json#

# тип экспортера
otel.traces.exporter=otlp 

# порт экспортера (например, Jaeger)
otel.exporter.otlp.endpoint=http://localhost:4317

# имя сервиса
otel.service.name=artemis_opentelemetry

Пример отображения трассировки в UI#

Трейс позволяет отследить путь сообщения.

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

Пример отображения логов в UI#

Наименование спана <имя сервиса>: <имя очереди> <тип операции>, где имя очереди совпадает с логом messaging.destination.name, тип операции совпадает с логом messaging.operation.