Настройка расширений JMX

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

Определение расширения состоит из трех основных элементов: metadata, metrics, и UI.

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 имеет следующие обязательные свойства:

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

Метрики

Эта часть JSON определяет, какие метрики будут собираться расширением. Каждая метрика определяется в формате JSON, аналогичном следующему:

{     "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"     }   }

Временные ряды

В этом разделе указываются метаданные метрики.

Поле	Тип	Описание
key	String	Название метрики. Должно быть уникальным в пределах данного расширения. Допускаются только буквы, цифры и символы "-", "_".
unit	String	Метрическая единица. Должна быть одна из доступных единиц, описанных ниже.
dimensions	String array	Необходимо указать в rx_pid индекс 0. Это гарантирует, что атрибуты JMX получат идентификатор системного процесса (PID) в качестве измерения. Дополнительные измерения могут использоваться, например, для предоставления одной метрики для каждого ObjectName значения свойства ключа JMX (например, QueueName, ThreadPoolName, или ConnectionPoolName). Допускаются только буквы, цифры и символы «-», «_».
displayname	String	Отображаемое имя метрики в Ключ-АСТРОМ. Это поле обязательно для заполнения. Оно должно отличаться от ключа метрики.

Доступные единицы: NanoSecond, MicroSecond, MilliSecond, Second, Byte, KiloByte, MegaByte, BytePerSecond, BytePerMinute, KiloBytePerSecond, KiloBytePerMinute, MegaBytePerSecond, MegaBytePerMinute, Count, PerSecond, PerMinute

Настройки оповещений

В этом разделе задаются параметры конфигурации одного или нескольких оповещений для заданного временного ряда.

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

Источник

В этом разделе описывается, как собирается метрика с использованием JMX. Для всех метрик требуются следующие атрибуты:

Поле	Тип	Описание
domain	String	Доменное имя MBean
keyProperties	Key, Value pairs	Основные свойства MBean. Значения могут содержать подстановочные знаки (*).
attribute	String	Название атрибута, содержащего значение метрики.

К необязательным атрибутам относятся:

Поле	Тип	Описание
attributePath	String	См. CompositeData
allowAdditionalKeys	Boolean	Если значение равно false, свойства ключа должны точно совпадать. Наличие дополнительных ключей в имени приведет к несоответствию. Если значение равно true, то допускаются и игнорируются дополнительные свойства ключа, помимо указанных в "keyProperties".
calculateDelta	bool	Если верно, вычислите изменение значений заданного атрибута. Значение = атрибут(t) - атрибут(t-1). Это полезно для монотонно возрастающих значений.
calculateRate	bool	Если значение истинно, вычислите скорость изменений в секунду. Это используется в сочетании с функцией calculateDelta для преобразования абсолютного значения атрибута (например, количества запросов) в значение скорости (например, запросов в секунду). Значение = атрибут / интервал запросов
aggregation	String	Используется для агрегирования нескольких значений, если более одного MBean соответствует фильтру по домену и ключевому свойству. Возможные значения: SUM, AVG, MIN, MAX.
splitting	Object	Разделение наборов

Разделение

Разделение данных можно использовать для определения дополнительного измерения для метрики. Это измерение должно быть определено в свойствах dimension временного ряда и в splitting свойствах источника.

"splitting": {     "name": "name",     "type": "keyProperty",     "keyProperty": "name"   }

Для определения нескольких вариантов разделения используйте следующий формат:

"splittings":[    {       "name":"name",       "type":"keyProperty",       "keyProperty":"name"    },    {       "name":"context",       "type":"keyProperty",       "keyProperty":"context"    } ]

Для каждого разделения должны присутствовать следующие атрибуты:

Поле	Тип	Описание
name	String	Должно совпадать с именем измерения, определенным для временного ряда.
type	String	Всегда должно быть keyProperty
keyProperty	String	Определяет, какое ключевое свойство MBean используется для ObjectName

Пример метрики с дополнительным разделением

В следующем примере показано, как определить метрику, которая предоставляет несколько временных рядов в рамках одной метрики:

{     "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"       }     }   }

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

CompositeData

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

Например, предположим, вы хотите извлечь значение used из атрибута HeapMemoryUsage. HeapMemoryUsage— это тип CompositeData, который возвращает следующий список пар «значение-ключ»:

{     committed: integer,     init: integer,     max: integer,     used: integer }

Определите метрику, указывающую на MBean с атрибутом HeapMemoryUsage, и в разделе source укажите attributePath ключ used. Например:

"source": {       "domain": "java.lang",       "keyProperties": {         "type": "Memory",       },       "attribute": "HeapMemoryUsage",       "attributePath": "get(\"used\")"     }

Конфигурация пользовательского интерфейса

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

{         "ui": {             "keymetrics" : [              {                     "key" : "requestCount",                     "aggregation" : "avg",                     "mergeaggregation" : "sum",                     "displayname" : "Requests"              }             ],             "keycharts" : [ ],             "charts": [ ]         }     }

Раздел keymetrics является полностью необязательным и позволяет определить до двух показателей, которые должны быть включены в инфографику процесса. Он имеет следующие атрибуты:

Поле	Тип	Описание
key	String	Условные обозначения для временного ряда, которые необходимо отобразить на графике. Допускаются только буквы, цифры, а также символы "-" и "_".
aggregation	String	Агрегация определяет метод агрегирования минутных значений при работе с более длительными временными интервалами. Ключ-АСТРОМ фиксирует значение каждые 10 секунд, но отправляет только одно агрегированное значение в минуту. Это определяет, как агрегировать эти 10-секундные значения.
mergeaggregation	String	Если метрика содержит несколько измерений, это определяет, как объединять значения измерений в одно измерение.
displayname	String	Название, которое будет отображаться в инфографике.

Каждый раздел диаграммы имеет одинаковый формат и выглядит следующим образом:

{                 "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"                  }                 ]          }

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

В обоих разделах можно определить массив диаграмм. Диаграмма должна обладать следующими обязательными атрибутами:

Поле	Тип	Описание
group	String	Название раздела, в который следует поместить диаграмму.
title	String	Название диаграммы
series	Array	Набор определений временных рядов и графиков. Один график может содержать несколько показателей.

Серия обладает следующими характеристиками:

Поле	Тип	Описание
key	String	Ключ к построению графика временного ряда
displayname	String	Отображаемое имя для метрики. Переопределяет отображаемое имя метрики. По умолчанию: отображаемое имя метрики.
aggregation	String	Как следует агрегировать значения за несколько минут на графиках при просмотре более длительного временного интервала. Возможные значения: SUM, AVG, MIN,MAX
mergeaggregation	String	Ключевые диаграммы не отображают несколько измерений. Если метрика содержит несколько измерений, это определяет, как агрегировать значения измерений в одно измерение.
color	String	HTML-обозначение цвета (RGB или RGBA).
seriestype	String	Тип диаграммы. Возможные значения: line, area, иbar
rightaxis	Boolean	Если это так, то показатель будет размещен на правой оси вместо левой. Обратите внимание, что Ключ-АСТРОМ поддерживает двухосевые диаграммы.
stacked	Boolean	В истинном случае несколько показателей накладываются друг на друга. Это работает только для площадных и столбчатых диаграмм.