Метрики JMX

На цій сторінці описано, як збирати метрики з JMX (Java Management Extensions) MBeans та експортувати їх до OpenTelemetry.

Огляд

JMX (Java Management Extensions) — це технологія Java, яка надає інструменти для керування та моніторингу застосунків через JMX MBeans (Managed Beans). Ці MBeans надають атрибути та операції керування, які можна спостерігати зовні.

Модуль OpenTelemetry JMX Metric Insight дозволяє інтегрувати метрики JMX в OpenTelemetry, що дає змогу:

• Моніторити метрики JVM (памʼять, збір сміття, потоки тощо)
• Збирати метрики з MBeans, специфічних для застосунку
• Експортувати дані JMX разом з іншими сигналами телеметрії OpenTelemetry
• Використовувати попередньо визначені відображення метрик для популярних цільових систем (Tomcat, Jetty, Wildfly, …)

Встановлення

Використання Java агента

Найпростіший спосіб збирати метрики JMX — використовувати OpenTelemetry Java агент з розширенням метрик JMX:

1. Завантажте OpenTelemetry Java агента (якщо він ще не встановлений):

   curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
   

2. Запустіть ваш застосунок з агентом та увімкніть метрики JMX:

   java -javaagent:opentelemetry-javaagent.jar \
     -Dotel.jmx.target.system=tomcat \
     -Dotel.jmx.config=/path/to/custom-metrics.yaml \
     -jar myapp.jar
   

Збирання метрик JMX вмикається шляхом встановлення одного (або обох) з наступних параметрів конфігурації:

• otel.jmx.target.system для вибору попередньо визначених наборів метрик
• otel.jmx.config для вказання шляху до користувацьких правил JMX

При використанні Java агента, метрики виконання JVM (CPU, памʼять, …) збираються через модуль runtime-telemetry і зазвичай увімкнені без додаткової конфігурації.

Конфігурація

Метрики JMX можна збирати двома способами:

• Зсередини JVM за допомогою внутрішнього інтерфейсу JMX з Java агентом
• Ззовні JVM за допомогою віддаленого інтерфейсу JMX з JMX Scraper

Конфігурація Java агента

При використанні OpenTelemetry Java агента, налаштуйте метрики JMX за допомогою цих властивостей:

Конфігурація JMX Scraper

При використанні автономного JMX Scraper для збору метрик з віддаленого JVM, налаштуйте його за допомогою цих властивостей (зауважте: otel.jmx.enabled не потрібен).

Повну довідку щодо налаштування див. у документації до JMX Scraper.

Зверніть увагу, що віддалений JVM повинен бути налаштований для приймання віддалених JMX-зʼєднань. Рекомендується спочатку перевірити підключення за допомогою інструментів jconsole або visualvm, щоб переконатися, що конфігурація та необовʼязкова автентифікація працюють належним чином.

Попередньо визначені цільові системи

OpenTelemetry надає попередньо визначені зіставлення метрик для популярних Java-фреймворків та серверів застосунків. Використовуйте властивість otel.jmx.target.system, щоб увімкнути їх (доступно як для Java агента, так і для JMX Scraper):

Приклад - Моніторинг Tomcat (Java агент):

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.jmx.target.system=tomcat \
  -jar myapp.jar

Для повного списку доступних цільових систем див.:

• Попередньо визначені цільові системи Java агента
• Попередньо визначені цільові системи JMX Scraper

Ви можете вказати кілька цільових систем, розділивши їх комами.

Віддалені JMX-зʼєднання

Щоб збирати метрики з віддаленого JVM, потрібно використовувати JMX Scraper. Це передбачає наявність двох окремих JVM:

1. Цільовий JVM — Застосунок, який моніториться
2. Scraper JVM — Збирач метрик JMX

Крок 1: Налаштування цільового JVM

Спочатку запустіть ваш цільовий застосунок з увімкненим віддаленим JMX:

java -Dcom.sun.management.jmxremote \
  -Dcom.sun.management.jmxremote.port=9999 \
  -Dcom.sun.management.jmxremote.authenticate=false \
  -Dcom.sun.management.jmxremote.ssl=false \
  -jar myapp.jar

Крок 2: Запуск JMX Scraper

Завантажте JMX Scraper зі сторінки OpenTelemetry Java Contrib releases (шукайте opentelemetry-jmx-scraper-<version>-all.jar).

Потім запустіть scraper, вказавши вашу цільову JVM:

java -Dotel.jmx.service.url=service:jmx:rmi:///jndi/rmi://tomcat.example.com:9999/jmxrmi \
  -Dotel.jmx.target.system=tomcat \
  -jar opentelemetry-jmx-scraper.jar

Ви можете налаштувати scraper, використовуючи ті ж властивості, що й Java агент (цільова система, інтервал збору тощо).

Для отримання додаткової інформації див. документацію JMX Scraper.

Зіставлення власних метрик

Для специфічних MBean вашого застосунку або власних вимог до моніторингу, ви можете створювати власні зіставлення метрик за допомогою конфігураційного файлу YAML.

Створення власної конфігурації YAML

Створіть файл YAML, який визначає, як зіставляти атрибути JMX з метриками OpenTelemetry:

Приклад — custom-jmx-metrics.yaml:

rules:
  - bean: com.myapp:type=CustomMetrics
    mapping:
      RequestCount:
        metric: myapp.requests.count
        type: counter
        description: Total request count
        unit: '1'
      ResponseTime:
        metric: myapp.response.time
        type: gauge
        description: Average response time
        unit: ms
      ActiveSessions:
        metric: myapp.sessions.active
        type: updowncounter
        description: Active sessions
        unit: '1'

Використайте файл з вашим застосунком:

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.jmx.config=/path/to/custom-jmx-metrics.yaml \
  -jar myapp.jar

Для повного посилання на синтаксис YAML див. документацію з конфігурації JMX Metrics.

Перевірка

Щоб перевірити, що метрики JMX збираються:

1. Перевірте журнали — Шукайте повідомлення, що вказують на початок збору метрик JMX
2. Використовуйте експортер журналів — налаштуйте експортер журналів, щоб переглядати метрики в консолі без необхідності в бекенді
3. Використовуйте бекенд метрик — Налаштуйте OTLP експортер і переглядайте метрики у вашій платформі спостереження
4. Використовуйте JConsole — Підключіться до вашого застосунку за допомогою JConsole, щоб перевірити доступність MBeans

Приклад з експортером журналів (Java агент):

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.metrics.exporter=logging \
  -jar myapp.jar

Приклад з OTLP експортером (Java агент):

java -javaagent:opentelemetry-javaagent.jar \
  -Dotel.metrics.exporter=otlp \
  -Dotel.exporter.otlp.endpoint=http://localhost:4318 \
  -jar myapp.jar

Приклад з OTLP експортером (JMX Scraper):

java -Dotel.jmx.service.url=service:jmx:rmi:///jndi/rmi://myapp.example.com:9999/jmxrmi \
  -Dotel.jmx.target.system=tomcat \
  -Dotel.metrics.exporter=otlp \
  -Dotel.exporter.otlp.endpoint=http://localhost:4318 \
  -jar opentelemetry-jmx-scraper.jar

Додаткові ресурси

• Документація JMX Scraper — Повний довідник з конфігурації та приклади
• Посібник з міграції JMX Scraper — Міграція з застарілого JMX Metric Gatherer
• Метрики JMX (Java агент) — Документація з метрик JMX для Java агента
• Попередньо визначені цільові системи — Вбудовані набори метрик для популярних фреймворків
• Документація Java агента — Загальна конфігурація Java агента
• Посібник з конфігурації — Параметри конфігурації OpenTelemetry SDK

Повʼязані теми

• Екосистема інструментування — Інші варіанти інструментування
• Shims — Міст між іншими бібліотеками спостереження
• Metrics API — Створення власних метрик