MBean и JMX в ERP

MBean — read-only представление внутреннего состояния ERP в стандартном JMX MBeanServer JVM. Через него публикуются размеры пулов, состояние реплик, число сессий, показатели API-клиентов и несколько прикладных счётчиков.

В ERP нет отдельного экрана MBean. Данные читаются средствами JVM, например JConsole, VisualVM или подключённым к процессу JMX-exporter.

Как устроена регистрация

При запуске Server.initJmx() объект MBeanHandler получает platform MBeanServer через ManagementFactory.getPlatformMBeanServer(). Затем регистрируются основные MBean приложения. Остальные появляются лениво при инициализации WebSocket-модулей, BPMN, конструктора интеграций или компонентов API-клиентов.

реализация MBean
  -> MBeanHandler.register(...)
  -> ObjectNameBuilder
  -> platform MBeanServer
  -> JConsole / JMX-exporter / другой JMX-клиент

Все объекты ERP находятся в домене BGCRM. Имя строится из трёх частей:

BGCRM:type=<type>[,name=<name>][,description=<description>]

type обязателен на практике. Пустые name и description пропускаются. Символы *, ?, :, =, ,, перевод строки и двойная кавычка удаляются из значений.

Например:

BGCRM:type=App
BGCRM:type=ConnectionPool,name=master
BGCRM:type=SlaveStatus,name=slave-erp-slave
BGCRM:type=CircuitBreaker,name=api-billing,description=Billing
description является частью ObjectName, а не только пояснительным текстом. Два объекта с одинаковыми type и name, но разными description, считаются разными MBean.

Включение и отключение

server.jmx.pools=true

Значение по умолчанию — true. Несмотря на слово pools, параметр проверяется общим MBeanHandler и отключает регистрацию всех MBean домена BGCRM, включая приложение, WebSocket, Elasticsearch и API-компоненты.

Проверка выполняется при каждой регистрации. Если параметр выключить после того, как объекты уже зарегистрированы, существующие MBean автоматически не удалятся. Для предсказуемого результата изменяйте параметр до запуска и перезапускайте ERP.

Этот параметр управляет только публикацией объектов в platform MBeanServer. Он не открывает сетевой JMX-порт и не настраивает аутентификацию.

Доступ к данным

Для локальной диагностики можно подключить JConsole к PID процесса ERP и открыть домен BGCRM. Удалённый доступ требует отдельно настроенного JMX connector или javaagent; код ERP этого не делает.

На стендах MBean может читать JMX-exporter. Конкретные имена Prometheus-метрик зависят от конфигурации и версии экспортера, поэтому контрактом модуля являются ObjectName и JMX-атрибуты, а не автоматически получившееся имя метрики.

Экспортер с правилом pattern: '.*' читает не только BGCRM, но и все MBean JVM и Tomcat. Некоторые атрибуты могут выполнять дорогую работу. Ограничивайте список собираемых доменов и атрибутов на стороне экспортера.

Жизненный цикл и ошибки

  • Повторная регистрация с тем же полным ObjectName сначала удаляет прежний объект, затем добавляет новый.

  • Регистрация одинакового имени синхронизирована локом с таймаутом 3 секунды. При таймауте операция пропускается без сообщения.

  • Ошибки JMX-регистрации записываются в лог и не останавливают запуск приложения.

  • Общего снятия всех MBean при остановке нет: большинство объектов живёт до завершения JVM.

  • unregister требует те же type, name и description, которые использовались при регистрации.

Полный перечень объектов приведён в каталоге MBean. Правила добавления нового объекта — в руководстве разработчика.

Известные ограничения

  • Название server.jmx.pools не отражает фактическую область действия параметра.

  • ObjectNameBuilder.init() не вызывается из штатной инициализации. Валидные имена работают, но ошибка построения имени может быть замаскирована неинициализированным логгером builder-а.

  • MBean кешей конструктора интеграций объявлен интерфейсом ClientEngineFactoryCachesMbean с неверным регистром b. Это нарушает стандартное соглашение <ImplementationClass>MBean; объект может завершить регистрацию с NotCompliantMBeanException. Подробности отмечены в каталоге.