Эксплуатация и диагностика Camel

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

Запуск и перезапуск

Событие Поведение

Старт ERP, camel.enabled=true

Создаётся CamelContext, затем компоненты и маршруты.

Старт ERP, camel.enabled=false

Контекст не создаётся.

Изменение конфигурации с id из camel.configId

Активный контекст полностью останавливается и создаётся заново. При выключенном плагине контекст только останавливается.

Изменение другой глобальной конфигурации

Camel не перезапускается.

Перекомпиляция зарегистрированного динамического обработчика

Выполняется полная реинициализация.

Перекомпиляция незарегистрированного динамического класса

Camel не перезапускается.

На локальном стенде динамический обработчик появится только при настроенном dynamic.src.dir и успешной загрузке dyn-проекта. При старте dyn-классы могут отсутствовать во время первой инициализации Camel и добавиться после события перекомпиляции — это допустимо, если затем в журнале появилась строка регистрации обработчика.

Сообщения журнала

Сообщение Что означает

Реинициализация плагина…​

Началась полная пересборка контекста.

Camel остановлен

Предыдущий контекст остановлен.

Зарегистрирован компонент: <id>

Компонент успешно добавлен в новый контекст.

Добавлен обработчик: <class>

Класс загружен, экземпляр создан, маршруты добавлены.

Класс не найден: <class>

Класс отсутствует в основном или динамическом classloader.

У класса …​ нет подходящих конструкторов

Нет публичного конструктора без аргументов.

Method …​ skipped because it has unsupported number of parameters

Метод с @From имеет не один аргумент.

Ошибка инициализации компонента

Не удалось подключить компонент; проверьте обязательные поля и доступность брокера.

An exception occurred in '<class>:<method>'

Прикладной обработчик завершился исключением.

Ошибка одного компонента или обработчика не обязательно останавливает весь плагин. Проверяйте регистрацию каждого ожидаемого класса отдельно.

Метрики

После каждой попытки обработки сообщения создаются две метрики, в том числе при ошибке десериализации до вызова прикладного метода:

camel_processing_count_total

Счётчик завершённых обработок.

camel_processing_duration_milliseconds

Гистограмма времени выполнения обработчика.

Обе метрики имеют теги:

endpoint

Входной URI Camel.

className

Полное имя класса обработчика.

method

Имя метода.

status

success или failure.

Экспортируемые Prometheus-имена, bucket гистограммы и общие правила работы с метриками описаны в каталоге телеметрии.

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

Проверка через ActiveMQ

Для ручного теста можно использовать REST API брокера, если он включён на стенде:

curl -u '<login>:<password>' \
  -H 'Content-Type: text/plain' \
  --data-binary @message.json \
  'http://<broker-host>:8161/api/message/<queue>?type=queue'

Для JSON необходимо явно передавать Content-Type: text/plain и тело как есть. При application/x-www-form-urlencoded брокер может передать пустое тело, после чего transformer завершится ошибкой либо обработчик получит некорректное значение.

Очистку тестовой очереди безопаснее выполнять штатной операцией управления брокера или через Jolokia для точного имени destination:

/api/jolokia/exec/org.apache.activemq:type=Broker,brokerName=<broker>,destinationType=Queue,destinationName=<queue>/purge()

Перед очисткой убедитесь, что выбраны тестовый брокер и тестовая очередь. Удаление сообщений из общей очереди необратимо.

Диагностика

Симптом Что проверить

Сообщения остаются в очереди

camel.enabled, id конфигурации, регистрацию компонента и обработчика, точное имя endpoint, подключение ERP к брокеру.

Класс есть в коде, но маршрут не появился

Наличие camel.handler.<n>.class, публичного пустого конструктора, метода с @From и ровно одного аргумента.

Динамический класс не найден

Загрузку dyn-проекта, dynamic.src.dir, результат компиляции и полное имя класса в конфигурации.

Сообщение ушло в DLQ

Заголовок error, журнал прикладного обработчика, формат JSON и совместимость DTO.

Обработчик вызывается несколько раз

Параметры durable subscription, уникальность clientId, число экземпляров ERP и политику redelivery.

После правки конфигурации ничего не изменилось

Совпадает ли id изменённой глобальной конфигурации со значением camel.configId.

Часть маршрутов работает, часть отсутствует

Ошибки регистрации конкретных классов: инициализация продолжается после локальной ошибки.

Растёт Metaspace после перекомпиляций dyn

Число старых DatabaseClassLoader и CamelContext, частоту перекомпиляций и необходимость планового перезапуска JVM.

Эксплуатационные ограничения

  • Реинициализация пересоздаёт весь CamelContext, даже если изменился один обработчик.

  • Остановка контекста выполняется синхронно и не имеет настроенного в плагине таймаута.

  • Частые перекомпиляции динамических обработчиков связаны с накоплением старых dyn-classloader в Metaspace. Старые CamelContext корректно останавливаются, но JVM-кеши могут продолжать удерживать классы; до устранения причины следует контролировать Metaspace и планировать перезапуск процесса.

  • Версии Camel 3.0.0-M2 и ActiveMQ 5.7.0 устарели. При изменении маршрутов нельзя полагаться на поведение современной стабильной версии без проверки на фактических зависимостях проекта.

  • Плагин не маскирует реквизиты компонента при выводе ComponentConfig. Не включайте полную конфигурацию с паролем в диагностические сообщения.

  • Плагин не настраивает JMX самостоятельно. Наличие Camel management-зависимостей не гарантирует доступность JMX на стенде.