IKuznetsov: Новая страница: «Расширения '''JMX''' определяются с помощью '''JSON'''-файлов. Определение расширения состоит и...»

2025-12-25T23:35:44Z

Новая страница: «Расширения '''JMX''' определяются с помощью '''JSON'''-файлов. Определение расширения состоит и...»

Новая страница

Расширения '''JMX''' определяются с помощью '''JSON'''-файлов.

Определение расширения состоит из трех основных элементов: <code>metadata</code>, <code>metrics</code>, и <code>UI</code>.
{| class="wikitable"
|The basic format is as follows:

{

"version": "1.0",

"name": "custom.jmx.hornetq",

"type": "JMX",

"entity": "PROCESS_GROUP_INSTANCE",

"metricGroup": "tech.HornetQ",

"configUI" : {

"displayName": "HornetQ JMX"

},

"metrics": [ ],

"ui": {

"keycharts" : [ ],

"charts": [ ]

}

}
|}

== Метаданные ==
Каждое расширение JMX имеет следующие обязательные свойства:
{| class="wikitable"
!Поле
!Тип
!Описание
|-
|<code>version</code>
|String
|Версия расширения в формате <code>d.dd</code> должна обновляться при каждом обновлении определения расширения.
|-
|<code>name</code>
|String
|Уникальное имя расширения в формате пакета Java. Пользовательские имена расширений JMX должны соответствовать правилу <code>custom.jmx.name</code>. Можно использовать только буквы, цифры и символы "-", "_". Например, <code>custom.jmx.newPlugin-Ver2</code>
|-
|<code>type</code>
|String
|Всегда используйте <code>JMX</code>
|-
|<code>entity</code>
|String
|Всегда используйте <code>PROCESS_GROUP_INSTANCE</code>
|-
|<code>metricGroup</code>
|String
|Группа метрик используется для группировки пользовательских метрик в иерархическое пространство имен, куда могут поступать данные из различных источников, например, из нескольких расширений. Более того, группа метрик становится основной частью ключа метрики. Следовательно, после определения ее нельзя изменить. Допустимые символы: буквы, цифры, а также символы «-» и «_».
|-
|<code>configUI.displayName</code>
|String
|Удобочитаемое название расширения. Это название отображается на странице расширений Ключ-АСТРОМ Monitoring после загрузки расширения.
|}

== Метрики ==
Эта часть '''JSON''' определяет, какие метрики будут собираться расширением. Каждая метрика определяется в формате '''JSON''', аналогичном следующему:
{| class="wikitable"
|{

"timeseries": {

"key": "Queue.ConsumerCount",

"unit": "Count",

"displayname": "Queue Consumer Count",

"dimensions": [

"rx_pid"

]

},

"alert_settings": [

{

"alert_id": "too_many_consumers",

"event_type": "PERFORMANCE_EVENT",

"event_name": "Too many consumers",

"description": "The {metricname} of {severity} is {alert_condition} the threshold of {threshold}",

"threshold": 35.0,

"alert_condition": "ABOVE",

"samples":5,

"violating_samples":3,

"dealerting_samples":5,

"value_extractor": "MAX"

}

],

"source": {

"domain": "org.hornetq",

"keyProperties": {

"type": "Queue"

},

"attribute": "ConsumerCount"

}

}
|}

=== Временные ряды ===
В этом разделе указываются метаданные метрики.
{| class="wikitable"
!Поле
!Тип
!Описание
|-
|<code>key</code>
|String
|Название метрики. Должно быть уникальным в пределах данного расширения. Допускаются только буквы, цифры и символы "-", "_".
|-
|<code>unit</code>
|String
|Метрическая единица. Должна быть одна из доступных единиц, описанных ниже.
|-
|<code>dimensions</code>
|String array
|Необходимо указать в <code>rx_pid</code> индекс <code>0</code>. Это гарантирует, что атрибуты JMX получат идентификатор системного процесса (PID) в качестве измерения. Дополнительные измерения могут использоваться, например, для предоставления одной метрики для каждого <code>ObjectName</code> значения свойства ключа JMX (например, <code>QueueName</code>, <code>ThreadPoolName</code>, или <code>ConnectionPoolName</code>). Допускаются только буквы, цифры и символы «-», «_».
|-
|<code>displayname</code>
|String
|Отображаемое имя метрики в Ключ-АСТРОМ. Это поле обязательно для заполнения. Оно должно отличаться от ключа метрики.
|}
Доступные единицы: <code>NanoSecond</code>, <code>MicroSecond</code>, <code>MilliSecond</code>, <code>Second</code>, <code>Byte</code>, <code>KiloByte</code>, <code>MegaByte</code>, <code>BytePerSecond</code>, <code>BytePerMinute</code>, <code>KiloBytePerSecond</code>, <code>KiloBytePerMinute</code>, <code>MegaBytePerSecond</code>, <code>MegaBytePerMinute</code>, <code>Count</code>, <code>PerSecond</code>, <code>PerMinute</code>

=== Настройки оповещений ===
В этом разделе задаются параметры конфигурации одного или нескольких оповещений для заданного временного ряда.
{| class="wikitable"
!Поле
!Тип
!Описание
|-
|<code>alert_id</code>
|String
|Уникальный идентификатор оповещения. Допускаются только буквы, цифры, а также символы "-" и "_".
|-
|<code>event_type</code>
|String
|Допустимые типы: <code>PERFORMANCE_EVENT</code>, <code>ERROR_EVENT</code>, <code>AVAILABILITY_EVENT</code>.
|-
|<code>description</code>
|String
|В описании определяется сообщение об ошибке; можно использовать следующие фрагменты кода: <code>{threshold}</code> значение пользовательского порогового значения, которое было нарушено, <code>{severity}</code> значение, вызвавшее нарушение, <code>{entityname}</code> отображаемое имя сущности, в которой произошло нарушение метрики, <code>{violating_samples}</code> количество выборок, вызвавших нарушение, <code>{dimensions}</code> строка, содержащая параметры метрики, вызвавшие нарушение, <code>{alert_condition}</code> строка, указывающая, происходит ли оповещение о превышении или невыполнении порогового значения.
|-
|<code>event_name</code>
|String
|Название события отображается на страницах пользовательского интерфейса.
|-
|<code>threshold</code>
|Float
|Значение порогового значения.
|-
|<code>alert_condition</code>
|String
|UP или DOWN.
|-
|<code>samples</code>
|Integer
|Размер «окна», в котором подсчитываются образцы, нарушающие правила.
|-
|<code>violating_samples</code>
|Integer
|Количество образцов, нарушающих правила и вызывающих тревогу.
|-
|<code>dealerting_samples</code>
|Integer
|Количество образцов, не нарушающих правила, при которых срабатывает оповещение.
|-
|<code>value_extractor</code>
|String
|Ключ-АСТРОМ фиксирует значение каждые 10 секунд, но отправляет только одно агрегированное значение в минуту. Это определяет способ агрегирования этих 10-секундных значений. Возможные значения: <code>MIN</code>, <code>MAX</code>, <code>SUM</code>, <code>COUNT</code>, <code>AVG</code>, <code>MEDIAN</code>, <code>P90</code>. Значение по умолчанию:<code>AVG</code>
|}

=== Источник ===
В этом разделе описывается, как собирается метрика с использованием JMX. Для всех метрик требуются следующие атрибуты:
{| class="wikitable"
!Поле
!Тип
!Описание
|-
|<code>domain</code>
|String
|Доменное имя MBean
|-
|<code>keyProperties</code>
|Key, Value pairs
|Основные свойства MBean. Значения могут содержать подстановочные знаки (<code>*</code>).
|-
|<code>attribute</code>
|String
|Название атрибута, содержащего значение метрики.
|}
К необязательным атрибутам относятся:
{| class="wikitable"
!Поле
!Тип
!Описание
|-
|<code>attributePath</code>
|String
|См. CompositeData
|-
|<code>allowAdditionalKeys</code>
|Boolean
|Если значение равно false, свойства ключа должны точно совпадать. Наличие дополнительных ключей в имени приведет к несоответствию. Если значение равно true, то допускаются и игнорируются дополнительные свойства ключа, помимо указанных в "keyProperties".
|-
|<code>calculateDelta</code>
|bool
|Если верно, вычислите изменение значений заданного атрибута. Значение = атрибут(t) - атрибут(t-1). Это полезно для монотонно возрастающих значений.
|-
|<code>calculateRate</code>
|bool
|Если значение истинно, вычислите скорость изменений в секунду. Это используется в сочетании с функцией calculateDelta для преобразования абсолютного значения атрибута (например, количества запросов) в значение скорости (например, запросов в секунду). Значение = атрибут / интервал запросов
|-
|<code>aggregation</code>
|String
|Используется для агрегирования нескольких значений, если более одного MBean соответствует фильтру по домену и ключевому свойству. Возможные значения: SUM, AVG, MIN, MAX.
|-
|<code>splitting</code>
|Object
|Разделение наборов
|}

==== Разделение ====
Разделение данных можно использовать для определения дополнительного измерения для метрики. Это измерение должно быть определено в свойствах <code>dimension</code> временного ряда и в <code>splitting</code> свойствах источника.
{| class="wikitable"
|"splitting": {

"name": "name",

"type": "keyProperty",

"keyProperty": "name"

}
|}
Для определения нескольких вариантов разделения используйте следующий формат:
{| class="wikitable"
|"splittings":[

{

"name":"name",

"type":"keyProperty",

"keyProperty":"name"

},

{

"name":"context",

"type":"keyProperty",

"keyProperty":"context"

}

]
|}

Для каждого разделения должны присутствовать следующие атрибуты:
{| class="wikitable"
!Поле
!Тип
!Описание
|-
|<code>name</code>
|String
|Должно совпадать с именем измерения, определенным для временного ряда.
|-
|<code>type</code>
|String
|Всегда должно быть <code>keyProperty</code>
|-
|<code>keyProperty</code>
|String
|Определяет, какое ключевое свойство MBean используется для <code>ObjectName</code>
|}

==== Пример метрики с дополнительным разделением ====
В следующем примере показано, как определить метрику, которая предоставляет несколько временных рядов в рамках одной метрики:
{| class="wikitable"
|{

"timeseries": {

"key": "XY.Size",

"unit": "Count",

"displayname": "Queue Consumer Count",

"dimensions": [

"rx_pid",

"name"

]

}

"source": {

"domain": "com.sample",

"keyProperties": {

"type": "XY",

"name": "*"

},

"attribute": "Size",

"splitting": {

"name": "name",

"type": "keyProperty",

"keyProperty": "name"

}

}

}
|}
Например, <code>MBeans com.sample:type=XY,name=A and com.sample:type=XY,name=B</code> в результате будут получены два временных ряда: первый для "А", а второй для "В".

==== CompositeData ====
Для извлечения значений отдельных ключей, возвращаемых атрибутом <code>CompositeData</code> в качестве типа, необходимо использовать соответствующий механизм <code>attributePath</code> и указать на интересующий вас ключ.

Например, предположим, вы хотите извлечь значение <code>used</code> из атрибута <code>HeapMemoryUsage</code>. <code>HeapMemoryUsage</code>— это тип <code>CompositeData</code>, который возвращает следующий список пар «значение-ключ»:
{| class="wikitable"
|{

committed: integer,

init: integer,

max: integer,

used: integer

}
|}
Определите метрику, указывающую на MBean с атрибутом <code>HeapMemoryUsage</code>, и в разделе <code>source</code> укажите <code>attributePath</code> ключ <code>used</code>. Например:
{| class="wikitable"
|"source": {

"domain": "java.lang",

"keyProperties": {

"type": "Memory",

},

"attribute": "HeapMemoryUsage",

"attributePath": "get(\"used\")"

}
|}

== Конфигурация пользовательского интерфейса ==
Эта часть '''JSON'''-файла определяет, как метрики отображаются на странице процесса. Она содержит обязательный раздел «График» и необязательный раздел «Ключевые диаграммы». Каждый раздел имеет одинаковый формат и выглядит следующим образом:
{| class="wikitable"
|{

"ui": {

"keymetrics" : [

{

"key" : "requestCount",

"aggregation" : "avg",

"mergeaggregation" : "sum",

"displayname" : "Requests"

}

],

"keycharts" : [ ],

"charts": [ ]

}

}
|}
Раздел <code>keymetrics</code> является полностью необязательным и позволяет определить до двух показателей, которые должны быть включены в инфографику процесса. Он имеет следующие атрибуты:
{| class="wikitable"
!Поле
!Тип
!Описание
|-
|<code>key</code>
|String
|Условные обозначения для временного ряда, которые необходимо отобразить на графике. Допускаются только буквы, цифры, а также символы "-" и "_".
|-
|<code>aggregation</code>
|String
|Агрегация определяет метод агрегирования минутных значений при работе с более длительными временными интервалами. Ключ-АСТРОМ фиксирует значение каждые 10 секунд, но отправляет только одно агрегированное значение в минуту. Это определяет, как агрегировать эти 10-секундные значения.
|-
|<code>mergeaggregation</code>
|String
|Если метрика содержит несколько измерений, это определяет, как объединять значения измерений в одно измерение.
|-
|<code>displayname</code>
|String
|Название, которое будет отображаться в инфографике.
|}
Каждый раздел диаграммы имеет одинаковый формат и выглядит следующим образом:
{| class="wikitable"
|{

"group": "Section Name",

"title": "Chart Name",

"series": [

{

"key": "MetricName",

"aggregation": "avg",

"displayname": "Display name for metric",

"seriestype": "area"

},

{

"key": "Other Metric Name",

"aggregation": "avg",

"displayname": "Display name for metric",

"color": "rgba(42, 182, 244, 0.6)",

"seriestype": "area"

}

]

}
|}
В разделе «Диаграммы» описано, как построить график для каждого показателя в разделе «Подробности» на странице процесса (доступен при выборе пункта «Дополнительные сведения»).

В обоих разделах можно определить массив диаграмм. Диаграмма должна обладать следующими обязательными атрибутами:
{| class="wikitable"
!Поле
!Тип
!Описание
|-
|<code>group</code>
|String
|Название раздела, в который следует поместить диаграмму.
|-
|<code>title</code>
|String
|Название диаграммы
|-
|<code>series</code>
|Array
|Набор определений временных рядов и графиков. Один график может содержать несколько показателей.
|}
Серия обладает следующими характеристиками:
{| class="wikitable"
!Поле
!Тип
!Описание
|-
|<code>key</code>
|String
|Ключ к построению графика временного ряда
|-
|<code>displayname</code>
|String
|Отображаемое имя для метрики. Переопределяет отображаемое имя метрики. По умолчанию: отображаемое имя метрики.
|-
|<code>aggregation</code>
|String
|Как следует агрегировать значения за несколько минут на графиках при просмотре более длительного временного интервала. Возможные значения: <code>SUM</code>, <code>AVG</code>, <code>MIN</code>,<code>MAX</code>
|-
|<code>mergeaggregation</code>
|String
|Ключевые диаграммы не отображают несколько измерений. Если метрика содержит несколько измерений, это определяет, как агрегировать значения измерений в одно измерение.
|-
|<code>color</code>
|String
|HTML-обозначение цвета (RGB или RGBA).
|-
|<code>seriestype</code>
|String
|Тип диаграммы. Возможные значения: <code>line</code>, <code>area</code>, и<code>bar</code>
|-
|<code>rightaxis</code>
|Boolean
|Если это так, то показатель будет размещен на правой оси вместо левой. Обратите внимание, что Ключ-АСТРОМ поддерживает двухосевые диаграммы.
|-
|<code>stacked</code>
|Boolean
|В истинном случае несколько показателей накладываются друг на друга. Это работает только для площадных и столбчатых диаграмм.
|}

Настройка расширений JMX - История изменений

IKuznetsov: Новая страница: «Расширения '''JMX''' определяются с помощью '''JSON'''-файлов. Определение расширения состоит и...»