Просмотр кода страницы Получение метрик

Список всех доступных показателей.

Вы можете ограничить вывод, используя нумерацию страниц:

# Укажите количество результатов на странице в параметре запроса pageSize .
# Затем используйте курсор из поля nextPageKey предыдущего ответа в параметре запроса nextPageKey для получения последующих страниц.

Запрос создает один из следующих типов полезной нагрузки, в зависимости от значения заголовка запроса Accept :

* <code>application/json</code>
* <code>text/csv; header=present</code>— таблица CSV со строкой заголовка
* <code>text/csv; header=absent</code>— таблица CSV без строки заголовка

Если с запросом не предоставлен заголовок Accept<code>application/json</code> , возвращается полезная нагрузка.
{| class="wikitable"
| rowspan="2" |GET
|Managed
|<code><nowiki>https://{your-domain}/e/{your-environment-id}/api/v2/metrics</nowiki></code>
|-
|Cреда АктивногоШлюза
|<code><nowiki>https://{your-activegate-domain}/e/{your-environment-id}/api/v2/metrics</nowiki></code>
|}

== Аутентификация ==
Чтобы выполнить этот запрос, вам нужен токен доступа с областью действия Чтение метрик ( <code>metrics.read</code>) . Чтобы узнать, как его получить и использовать, см. раздел [[Токены и аутентификация (API)|Токены и аутентификация]] .

== Параметры ==
{| class="wikitable"
!Параметр
!Тип
!Описание
!В
!Необходимый
|-
|nextPageKey
|string
|Курсор для следующей страницы результатов. Вы можете найти его в поле nextPageKey предыдущего ответа.

Первая страница всегда возвращается, если вы не укажете параметр запроса nextPageKey .

Когда nextPageKey настроен на получение последующих страниц, вы должны опустить все остальные параметры запроса.
|запрос
|по желанию
|-
|pageSize
|integer
|Количество метрических схем в полезной нагрузке одного ответа.

Максимально допустимый размер страницы – 500.

Если не установлено, используется 100.

Если используется значение выше 500, возвращается только 500 результатов на страницу.
|запрос
|по желанию
|-
|metricSelector
|string
|Выбирает метрики для запроса по их ключам.

Можно указать несколько ключей метрик, разделенных запятыми (например, <code>metrickey1,metrickey2</code>). Чтобы выбрать несколько метрик, принадлежащих одному и тому же родителю, перечислите последнюю часть необходимых ключей метрик в круглых скобках, разделенных запятыми, не затрагивая общую часть. Например, чтобы перечислить метрику <code>builtin:host.cpu.idle</code>и , напишите: .<code>builtin:host.cpu.userbuiltin:host.cpu.(idle,user)</code>

<code>*</code>Вы можете выбрать полный набор связанных показателей, используя подстановочный знак звездочки ( ). Например, <code>builtin:host.*</code>выбирает все метрики на основе хоста и <code>builtin:*</code>выбирает все метрики, предоставленные Ключ-АСТРОМ.

Вы можете установить дополнительные операторы преобразования, разделенные двоеточием ( <code>:</code>). Дополнительную информацию о доступных преобразованиях результатов и синтаксисе см. в разделе Преобразования селектора показателей в документации Ключ-АСТРОМ.

Эта конечная точка поддерживает только преобразования , <code>aggregation</code>, <code>merge</code>и <code>parents</code>.<code>splitBy</code>

Если ключ метрики содержит какие-либо символы, ключ необходимо заключить в кавычки ( <code>"</code>). Следующие символы внутри заключенного в кавычки метрического ключа должны быть экранированы тильдой ( <code>~</code>):

* Цитаты ( <code>"</code>)
* Тильд ( <code>~</code>)

Например, чтобы запросить метрику с ключом ext:selfmonitoring.jmx.Agents: Введите «APACHE» , вы должны указать этот селектор:

<code>"ext:selfmonitoring.jmx.Agents: Type ~"APACHE~""</code>

Чтобы найти метрики на основе условия поиска, а не metricId, используйте текстовый параметр запроса вместо этого.
|запрос
|по желанию
|-
|text
|string
|Критерий поиска реестра метрик. Показывать только те метрики, которые содержат термин в своем ключе, отображаемом имени или описании. Используйте этот <code>metricSelector</code>параметр вместо этого, чтобы выбрать полную иерархию метрик вместо текстового поиска.
|запрос
|по желанию
|-
|fields
|string
|Определяет список свойств метрик, включенных в ответ.

<code>metricId</code>всегда включается в результат. Доступны следующие дополнительные свойства:

* <code>displayName</code>: имя метрики в пользовательском интерфейсе. Включено по умолчанию.
* <code>description</code>: краткое описание метрики. Включено по умолчанию.
* <code>unit</code>: единица измерения. Включено по умолчанию.
* <code>tags</code>: теги метрики.

* <code>dduBillable</code>: индикатор того, расходуются ли при использовании метрики единицы данных Дейвиса .

* <code>created</code>: Отметка времени (в миллисекундах UTC), когда метрика была создана.
* <code>lastWritten</code>: Отметка времени (в миллисекундах UTC), когда точки данных метрики были записаны в последний раз.
* <code>aggregationTypes</code>: список разрешенных агрегаций для метрики. Обратите внимание, что после применения преобразования оно может измениться .
* <code>defaultAggregation</code>: Агрегирование метрики по умолчанию. Он используется, когда агрегация не указана или задано <code>:auto</code>преобразование.
* <code>dimensionDefinitions</code>: точное разделение метрик (например, группа процессов и идентификатор процесса для некоторой связанной с процессом метрики).
* <code>transformations</code>: список преобразований , которые можно применить к метрике.
* <code>entityType</code>: список типов объектов, поддерживаемых метрикой.
* <code>minimumValue</code>: минимально допустимое значение метрики.
* <code>maximumValue</code>: Максимально допустимое значение метрики.
* <code>rootCauseRelevant</code>: Связана ли (истина или ложь) метрика с первопричиной проблемы. Метрика, относящаяся к первопричине, представляет собой надежный индикатор неисправного компонента.
* <code>impactRelevant</code>: Относится ли метрика к влиянию проблемы (верно или нет). Метрика, имеющая отношение к влиянию, сильно зависит от других метрик и изменений, поскольку базовая метрика первопричины изменилась.
* <code>metricValueType</code>: тип значения метрики. У вас есть следующие варианты:
** <code>score</code>: Метрика оценки — это метрика, где высокие значения указывают на хорошую ситуацию, а низкие значения указывают на проблемы. Примером такой метрики является показатель успешности.
** <code>error</code>: Метрика ошибок — это метрика, высокие значения которой указывают на проблему, а низкие значения указывают на хорошую ситуацию. Примером такой метрики является счетчик ошибок.
* <code>latency</code>: задержка метрики в минутах. Задержка — это ожидаемая задержка в отчетах (например, вызванная ограничениями поставщиков облачных услуг или других сторонних источников данных) между наблюдением за точкой данных метрики и ее доступностью в Ключ-АСТРОМ. Допустимый диапазон значений от <code>1</code>до <code>60</code>минут.
* <code>metricSelector</code>: Базовый селектор метрик, используемый func: metric.
* <code>scalar</code>: указывает, разрешается ли выражение метрики в скаляр ( <code>true</code>) или в ряд ( <code>false</code>). Скалярный результат всегда содержит одну точку данных. Количество точек данных в результате серии зависит от используемого разрешения.
* <code>resolutionInfSupported</code>: если <code>true</code>, разрешение=Inf может быть применено к запросу метрики.

Чтобы добавить свойства, перечислите их с начальным плюсом <code>+</code>. Чтобы исключить свойства по умолчанию, перечислите их с начальным минусом <code>-</code>.

Чтобы указать несколько свойств, соедините их запятой (например, <code>fields=+aggregationTypes,-description</code>).

Если указать только одно свойство, ответ будет содержать ключ метрики и указанное свойство. Чтобы вернуть только ключи метрик, укажите <code>metricId</code>здесь.
|запрос
|по желанию
|-
|writtenSince
|string
|Фильтрует результирующий набор метрик до тех, которые имеют точки данных в пределах указанного периода времени.

Вы можете использовать один из следующих форматов:

* Отметка времени в миллисекундах UTC.
* Человекочитаемый формат <code>2021-01-25T05:57:01.123+01:00</code>. Если часовой пояс не указан, используется UTC. Вы можете использовать пробел вместо <code>T</code>. Секунды и доли секунды не являются обязательными.
* Относительный таймфрейм, назад. Формат: <code>now-NU/A</code>, где <code>N</code>количество времени, <code>U</code>единица времени и <code>A</code>выравнивание. Выравнивание округляет все меньшие значения до ближайшего нуля в прошлом. Например, <code>now-1y/w</code>это один год назад, выровненный на неделю. Вы также можете указать относительный таймфрейм без выравнивания: <code>now-NU</code>. Поддерживаемые единицы времени для относительного таймфрейма:
** <code>m</code>: минуты
** <code>h</code>: часы
** <code>d</code>: дни
** <code>w</code>: недели
** <code>M</code>: месяцы
** <code>y</code>: годы
|запрос
|по желанию
|-
|metadataSelector
|string
|Область метаданных запроса. В ответ включаются только метрики с указанными свойствами.

Вы можете установить один или несколько из следующих критериев. Значения чувствительны к регистру и используется <code>EQUALS</code>оператор. Если указано несколько значений, применяется логика ИЛИ .

* <code>unit("unit-1","unit-2")</code>
* <code>tags("tag-1","tag-2")</code>
* <code>dimensionKey("dimkey")</code>Вы можете указать только одно значение. Фильтрация применяется только к измерениям, которые были записаны в течение последних 14 дней.

Чтобы задать несколько критериев, разделите их запятой ( <code>,</code>). Например, <code>tags("feature","cloud"),unit("Percent"),dimensionKey("location")</code>. В ответ включаются только результаты, соответствующие всем критериям.

Например, чтобы вывести список метрик, у которых есть функция тегов '''feature''' AND '''cloud''' с единицей измерения '''Percent''' OR '''MegaByte''' AND измерение с измерением ключа '''location''' , используйте следующий '''metadataSelector ''': <code>tags("feature"),unit("Percent","MegaByte"),tags("cloud"),dimensionKey("location")</code>.
|запрос
|по желанию
|}

== Ответ ==

=== Коды ответов ===
{| class="wikitable"
!Код
|Тип
!Описание
|-
|200
|MetricDescriptorCollection
|Успех
|-
|400
|
|Ошибка синтаксиса или проверки. metricSelector или поля содержат синтаксические или семантические ошибки.
|-
|404
|
|Метрика не найдена.
|-
|406
|
|Неприемлимо. Запрошенный тип носителя не поддерживается. Проверьте заголовок Accept вашего запроса.
|}

=== Объекты тела ответа ===

==== Объект <code>MetricDescriptorCollection</code> ====
Список метрик вместе с их дескрипторами.
{| class="wikitable"
!Элемент
!Тип
!Описание
|-
|nextPageKey
|string
|Курсор для следующей страницы результатов. Имеет значение <code>null</code>на последней странице.

Используйте его в параметре запроса nextPageKey для получения последующих страниц результата.
|-
|totalCount
|integer
|Предполагаемое количество метрик в результате.
|-
|metrics
|MetricDescriptor[]
|Список метрик вместе с их дескрипторами
|-
|warnings
|string []
|Список возможных предупреждений о запросе. Например, использование устаревших функций и т. д.
|}

==== Объект <code>MetricDescriptor</code> ====
Дескриптор метрики.
{| class="wikitable"
!Элемент
!Тип
!Описание
|-
|dimensionCardinalities
|MetricDimensionCardinality[]
|Количество элементов метрических измерений MINT.
|-
|minimumValue
|number
|Минимально допустимое значение метрики.

Выражения показателей не возвращают это поле.
|-
|maximumValue
|number
|Максимально допустимое значение метрики.

Выражения показателей не возвращают это поле.
|-
|latency
|integer
|Задержка показателя в минутах.

Задержка — это ожидаемая задержка в отчетах (например, вызванная ограничениями поставщиков облачных услуг или других сторонних источников данных) между наблюдением за точкой данных метрики и ее доступностью в Ключ-АСТРОМ.

Допустимый диапазон значений составляет от 1 до 60 минут.

Выражения показателей не возвращают это поле.
|-
|resolutionInfSupported
|boolean
|Если установлено значение «true», разрешение=Inf может быть применено к запросу метрики.
|-
|unitDisplayFormat
|string
|Необработанное значение хранится в битах или байтах. Пользовательский интерфейс может отображать его в следующих системах счисления:

Двоичный: 1 МБ = 1024 КиБ = 1 048 576 байт.

Десятичный: 1 МБ = 1000 КБ = 1 000 000 байт.

Если не задано, используется десятичная система.

Выражения показателей не возвращают это поле.

Элемент может содержать эти значения

* <code>binary</code>
* <code>decimal</code>
|-
|rootCauseRelevant
|boolean
|Метрика является ( <code>true</code>) или не является ( <code>false</code>) релевантной для основной причины.

Метрика, относящаяся к первопричине, представляет собой надежный индикатор неисправного компонента.

Выражения показателей не возвращают это поле.
|-
|dduBillable
|boolean
|Если <code>true</code>использование метрики потребляет единицы данных Дэвиса .

Выражения показателей не возвращают это поле.
|-
|defaultAggregation
|MetricDefaultAggregation
|Агрегирование метрики по умолчанию.
|-
|lastWritten
|integer
|Отметка времени последней записи метрики.

Имеет значение <code>null</code>для метрических выражений или если данные никогда не записывались.
|-
|impactRelevant
|boolean
|Метрика является ( <code>true</code>) или не является ( <code>false</code>) релевантной для воздействия.

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

Выражения показателей не возвращают это поле.
|-
|dimensionDefinitions
|MetricDimensionDefinition[]
|Точное разделение метрик (например, группа процессов и идентификатор процесса для некоторой метрики, связанной с процессом).

Для загруженных показателей параметры, по которым не было данных за последние 15 дней, опускаются.
|-
|metricValueType
|MetricValueType
|Тип значения для метрики.
|-
|tags
|string []
|Теги, примененные к метрике.

Выражения показателей не возвращают это поле.
|-
|entityType
|string []
|Список допустимых основных типов сущностей для этой метрики. Может использоваться для <code>type</code>предиката в <code>entitySelector</code>.
|-
|metricId
|string
|Полный ключ метрики.

Если использовалось преобразование, оно отражается в ключе метрики.
|-
|metricSelector
|string
|Селектор метрик, который используется при запросе метрики func:.
|-
|scalar
|boolean
|Указывает, разрешается ли метрическое выражение в скаляр ( <code>true</code>) или в ряд ( <code>false</code>). Скалярный результат всегда содержит одну точку данных. Количество точек данных в результате серии зависит от используемого разрешения.
|-
|aggregationTypes
|string []
|Список разрешенных агрегаций для этой метрики.

Элемент может содержать эти значения

* <code>auto</code>
* <code>avg</code>
* <code>count</code>
* <code>max</code>
* <code>median</code>
* <code>min</code>
* <code>percentile</code>
* <code>sum</code>
* <code>value</code>
|-
|displayName
|string
|Имя метрики в пользовательском интерфейсе.
|-
|description
|string
|Краткое описание метрики.
|-
|transformations
|string []
|Операторы преобразования, которые можно добавить к текущему списку преобразований.

Элемент может содержать эти значения

* <code>asGauge</code>
* <code>default</code>
* <code>delta</code>
* <code>evaluateModel</code>
* <code>filter</code>
* <code>fold</code>
* <code>last</code>
* <code>lastReal</code>
* <code>limit</code>
* <code>merge</code>
* <code>names</code>
* <code>parents</code>
* <code>partition</code>
* <code>rate</code>
* <code>rollup</code>
* <code>setUnit</code>
* <code>smooth</code>
* <code>sort</code>
* <code>splitBy</code>
* <code>timeshift</code>
* <code>toUnit</code>
|-
|unit
|string
|Единица измерения.
|-
|warnings
|string[]
|Список потенциальных предупреждений, влияющих на этот идентификатор. Например, использование устаревших функций и т. д.
|-
|created
|integer
|Отметка времени создания метрики.

Встроенные метрики и выражения метрик имеют значение <code>null</code>.
|}

==== Объект  <code>MetricDimensionCardinality</code> ====
Количество элементов измерения метрики.
{| class="wikitable"
!Элемент
!Тип
!Описание
|-
|relative
|number
|Относительная кардинальность измерения, выраженная в процентах
|-
|estimate
|integer
|Оценка количества элементов измерения.
|-
|key
|string
|Ключ измерения.

Он должен быть уникальным в пределах метрики.
|}

==== Объект <code>MetricDefaultAggregation</code> ====
Агрегирование метрики по умолчанию.
{| class="wikitable"
!Элемент
!Тип
!Описание
|-
|parameter
|number
|Доставляемый процентиль. Допустимые значения находятся между <code>0</code>и <code>100</code>.

Применимо только к <code>percentile</code>типу агрегации.
|-
|type
|string
|Тип агрегации по умолчанию.

Элемент может содержать эти значения

* <code>auto</code>
* <code>avg</code>
* <code>count</code>
* <code>max</code>
* <code>median</code>
* <code>min</code>
* <code>percentile</code>
* <code>sum</code>
* <code>value</code>
|}

==== Объект <code>MetricDimensionDefinition</code> ====
Размерность метрики.
{| class="wikitable"
!Элемент
!Тип
!Описание
|-
|displayName
|string
|Отображаемое имя измерения.
|-
|name
|string
|Имя измерения.
|-
|key
|string
|Ключ измерения.

Он должен быть уникальным в пределах метрики.
|-
|type
|string
|Тип измерения.

Элемент может содержать эти значения

* <code>ENTITY</code>
* <code>NUMBER</code>
* <code>OTHER</code>
* <code>STRING</code>
* <code>VOID</code>
|-
|index
|integer
|Уникальный индекс измерения, начинающийся с 0.

Добавление преобразований, таких как :names или :parents, может изменить индексы измерений. <code>null</code>используется для измерений метрики с гибкими измерениями, на которые можно ссылаться с помощью их ключа измерения, но у которых нет внутреннего порядка, который можно было бы использовать для индекса.
|}

==== Объект <code>MetricValueType</code> ====
Тип значения для метрики.
{| class="wikitable"
!Элемент
!Тип
!Описание
|-
|type
|string
|Тип значения метрики

Элемент может содержать эти значения

* <code>error</code>
* <code>score</code>
* <code>unknown</code>
|}

=== JSON-модель тела ответа ===
 <code>{
   "totalCount": 3,
   "nextPageKey": "ABCDEFABCDEFABCDEF_",
   "metrics": [
     {
       "metricId": "builtin:host.cpu.user:splitBy(\"dt.entity.host\"):max:fold",
       "displayName": "CPU user",
       "description": "Percentage of user-space CPU time currently utilized, per host.",
       "unit": "Percent",
       "dduBillable": false,
       "created": 1597400123451,
       "lastWritten": 1597400717783,
       "entityType": [
         "HOST"
       ],
       "aggregationTypes": [
         "auto",
         "value"
       ],
       "transformations": [
         "filter",
         "fold",
         "limit",
         "merge",
         "names",
         "parents",
         "timeshift",
         "rate",
         "sort",
         "last",
         "splitBy"
       ],
       "defaultAggregation": {
         "type": "value"
       },
       "dimensionDefinitions": [
         {
           "key": "dt.entity.host",
           "name": "Host",
           "displayName": "Host",
           "index": 0,
           "type": "ENTITY"
         }
       ],
       "tags": [],
       "metricValueType": {
         "type": "unknown"
       }
     },
     {
       "metricId": "builtin:host.cpu.user:splitBy()",
       "displayName": "CPU user",
       "description": "Percentage of user-space CPU time currently utilized, per host.",
       "unit": "Percent",
       "dduBillable": false,
       "created": 1597400123451,
       "lastWritten": 1597400717783,
       "entityType": [
         "HOST"
       ],
       "aggregationTypes": [
         "auto",
         "value"
       ],
       "transformations": [
         "filter",
         "fold",
         "limit",
         "merge",
         "names",
         "parents",
         "timeshift",
         "rate",
         "sort",
         "last",
         "splitBy"
       ],
       "defaultAggregation": {
         "type": "value"
       },
       "dimensionDefinitions": [
         {
           "key": "dt.entity.host",
           "name": "Host",
           "displayName": "Host",
           "index": 0,
           "type": "ENTITY"
         }
       ],
       "tags": [],
       "metricValueType": {
         "type": "unknown"
       }
     }
   ]
 }</code>

== Пример ==
В этом примере запрос запрашивает все встроенные метрики ( для metricSelector установлено значение <code>builtin:*</code>), доступные в среде mySampleEnv . В ответ включаются следующие поля:

* идентификатор метрики
* Ед. изм
* типы агрегации

Для этого для параметра запроса полей<code>unit,aggregationTypes</code> установлено значение .

Маркер API передается в заголовке авторизации .

Ответ имеет <code>application/json</code>формат и усекается до четырех записей.

==== Curl ====
 <code>curl -L -X GET '<nowiki>https://mySampleEnv.live.ruscomtech.ru/api/v2/metrics?fields=unit,aggregationTypes&metricSelector=builtin:*'</nowiki> \
 -H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
 -H 'Accept: application/json'</code>

==== URL-адрес запроса ====
 <code><nowiki>https://mySampleEnv.live.ruscomtech.ru/api/v2/metrics?fields=unit,aggregationTypes&metricSelector=builtin:*</nowiki></code>

==== Тело ответа ====
 <code>{
   "totalCount": 1808,
   "nextPageKey": "___a7acX3q0AAAAGAQAJYnVpbHRpbjoqAQA",
   "metrics": [
     {
       "metricId": "builtin:host.cpu.idle",
       "unit": "Percent",
       "aggregationTypes": [
         "auto",
         "avg",
         "max",
         "min"
       ]
     },
     {
       "metricId": "builtin:host.cpu.load",
       "unit": "Ratio",
       "aggregationTypes": [
         "auto",
         "avg",
         "max",
         "min"
       ]
     },
     {
       "metricId": "builtin:service.errors.server.count",
       "unit": "Count",
       "aggregationTypes": [
         "auto",
         "value"
       ]
     },
     {
       "metricId": "builtin:service.keyRequest.count.client",
       "unit": "Count",
       "aggregationTypes": [
         "auto",
         "value"
       ]
     }
   ]
 }</code>
Таблица CSV со строкой заголовка выглядит следующим образом. Чтобы получить его, измените заголовок Accept<code>text/csv; header=present</code> на .
 <code>metricId,unit,aggregationTypes
 builtin:host.cpu.idle,Percent,"[auto, avg, max, min]"
 builtin:host.cpu.load,Ratio,"[auto, avg, max, min]"
 builtin:service.errors.server.count,Count,"[auto, value]"
 builtin:service.keyRequest.count.client,Count,"[auto, value]"</code>

==== Код ответа ====
200