API метрик — GET метрики: различия между версиями
Новая страница: «= API метрик — GET метрики = Отображает список всех доступных метрик. Вы можете ограничить вывод информации, используя пагинацию: * Укажите количество результатов на странице в параметре запроса <code>pageSize</code>. * Затем используйте курсор из поля <code>nextPageKey</cod...» Метка: визуальный редактор отключён |
|||
| Строка 14: | Строка 14: | ||
* <code>text/csv; header=absent</code> — CSV-таблица без строки заголовка | * <code>text/csv; header=absent</code> — CSV-таблица без строки заголовка | ||
Если в запросе не указан заголовок <code>Accept</code>, возвращается полезная нагрузка <code>application/json</code>. | Если в запросе не указан заголовок <code>Accept</code>, возвращается полезная нагрузка <code>application/json</code>.<pre> | ||
<pre> | |||
SaaS: https://{your-environment-id}.live.astromkey.com/api/v2/metrics | SaaS: https://{your-environment-id}.live.astromkey.com/api/v2/metrics | ||
</pre> | </pre> | ||
<pre> | <pre> | ||
Среда Активного Шлюза / Кластер Активного Шлюза: https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/metrics | Среда Активного Шлюза / Кластер Активного Шлюза: https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/metrics | ||
Текущая версия от 01:28, 23 июля 2026
API метрик — GET метрики
Отображает список всех доступных метрик.
Вы можете ограничить вывод информации, используя пагинацию:
- Укажите количество результатов на странице в параметре запроса
pageSize. - Затем используйте курсор из поля
nextPageKeyпредыдущего ответа в параметре запросаnextPageKey, чтобы получить последующие страницы.
В зависимости от значения заголовка Accept запроса, запрос генерирует один из следующих типов полезной нагрузки:
application/jsontext/csv; header=present— CSV-таблица с заголовкомtext/csv; header=absent— CSV-таблица без строки заголовка
Если в запросе не указан заголовок Accept, возвращается полезная нагрузка application/json.
SaaS: https://{your-environment-id}.live.astromkey.com/api/v2/metrics
Среда Активного Шлюза / Кластер Активного Шлюза: https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/metrics
Аутентификация
Для выполнения этого запроса вам потребуется токен доступа с областью действия metrics.read.
Чтобы узнать, как получить и использовать его, см. раздел «Токены и аутентификация».
Параметры
| Параметр | Тип | Описание | В | Необходимый |
|---|---|---|---|---|
nextPageKey |
string | Курсор для перехода на следующую страницу результатов. Его можно найти в поле nextPageKey предыдущего ответа.
Если параметр запроса | ||
pageSize |
integer | Количество метрических схем в одном ответном пакете данных.
Максимально допустимый размер страницы — 500. Если значение не задано, используется значение 100. Если используется значение больше 500, на каждой странице будет возвращено только 500 результатов. || query || Необязательный | ||
metricSelector |
string | Выбирает метрики для запроса по их ключам.
Вы можете указать несколько ключей метрик, разделенных запятыми (например,
Например, чтобы запросить метрику по ключу | ||
text |
string | Поисковый запрос в реестре метрик. Отображать только те метрики, которые содержат этот термин в своем ключе, отображаемом имени или описании. Используйте параметр metricSelector вместо этого, чтобы выбрать полную иерархию метрик вместо текстового поиска. |
query | Необязательный |
fields |
string | Определяет список свойств метрик, включаемых в ответ.
Чтобы добавить свойства, перечислите их, начиная с плюса | ||
writtenSince |
string | Фильтрует полученный набор метрик, оставляя только те, которые содержат данные за указанный период времени.
Вы можете использовать один из следующих форматов:
| ||
writtenSinceMode |
string | Управляет способом применения фильтра writtenSince.
Если не указано иное, по умолчанию используется значение | ||
metadataSelector |
string | Область действия метаданных запроса. В ответ включаются только метрики с указанными свойствами.
Вы можете задать один или несколько из следующих критериев. Значения чувствительны к регистру, и используется оператор
Чтобы задать несколько критериев, разделите их запятой ( |
Ответ
Коды ответов
| Код | Тип | Описание |
|---|---|---|
| 200 | Сборник дескрипторов метрик | Успех |
| 400 | - | Синтаксическая или валидационная ошибка. В селекторе метрик или полях обнаружены синтаксические или семантические ошибки. |
| 404 | - | Показатель не найден. |
| 406 | - | Неприемлемо. Запрошенный тип носителя не поддерживается. Проверьте заголовок Accept вашего запроса.
|
| 4XX | Оболочка ошибки | Ошибка на стороне клиента. |
| 5XX | Оболочка ошибки | Ошибка на стороне сервера. |
Объекты тела ответа
Объект MetricDescriptorCollection
Список метрик с их описаниями.
| Элемент | Тип | Описание |
|---|---|---|
metrics |
MetricDescriptor [] | Список метрик с их описаниями. |
nextPageKey |
string | Курсор для перехода на следующую страницу результатов. Имеет значение null на последней странице.
Используйте его в параметре запроса |
totalCount |
integer | Примерное количество метрик в результате. |
warnings |
string [] | Список возможных предупреждений о запросе. Например, об использовании устаревших функций и т.д. |
Объект MetricDescriptor
Описание метрики.
| Элемент | Тип | Описание |
|---|---|---|
aggregationTypes |
string [] | Список допустимых агрегаций для данного показателя. |
billable |
boolean | Если true, использование метрики оплачивается. Метрические выражения не возвращают это поле.
|
created |
integer | Отметка времени создания метрики. Встроенные метрики и выражения метрик имеют значение null.
|
dduBillable |
boolean | Если true, использование метрики потребляет единицы данных ИИ. Устарело и всегда false используется для подписки на платформу Ключ-АСТРОМ. Заменено на isBillable. Метрические выражения не возвращают это поле.
|
defaultAggregation |
MetricDefaultAggregation | Агрегирование метрики по умолчанию. |
description |
string | Краткое описание метрики. |
dimensionCardinalities |
MetricDimensionCardinality [] | Мощность метрических измерений MINT. |
dimensionDefinitions |
MetricDimensionDefinition [] | Детальное метрическое деление (например, группа процессов и идентификатор процесса для некоторых показателей, связанных с процессом). При обработке входящих метрик исключаются измерения, по которым не было данных за последние 15 дней. |
displayName |
string | Название метрики в пользовательском интерфейсе. |
entityType |
string [] | Список допустимых основных типов сущностей для этой метрики. Может использоваться в качестве type предиката в entitySelector.
|
impactRelevant |
boolean | Показатель имеет (true) или не имеет (false) значения для оценки воздействия. Показатель, имеющий значение для оценки воздействия, в значительной степени зависит от других показателей и изменяется, поскольку изменился основной показатель, являющийся первопричиной проблемы. Метрические выражения не возвращают это поле.
|
lastWritten |
integer | Отметка времени, когда метрика была записана в последний раз. Имеет значение null для метрических выражений или если данные никогда не были записаны.
|
latency |
integer | Задержка по данному показателю, в минутах. Задержка — это ожидаемая задержка в формировании отчета между моментом получения данных метрики и их доступностью в Ключ-АСТРОМ. Допустимый диапазон значений составляет от 1 до 60 минут. Метрические выражения не возвращают это поле. |
maximumValue |
number | Максимально допустимое значение показателя. Метрические выражения не возвращают это поле. |
metricId |
string | Полный ключ метрики. Если использовалось преобразование, это отражается в ключе метрики. |
metricSelector |
string | Селектор метрики, используемый при запросе к функции :metric.
|
metricValueType |
MetricValueType | Тип значения для метрики. |
minimumValue |
number | Минимально допустимое значение показателя. Метрические выражения не возвращают это поле. |
resolutionInfSupported |
boolean | Если значение равно true, то параметр resolution=Inf может быть применен к запросу метрики.
|
rootCauseRelevant |
boolean | Показатель имеет (true) или не имеет (false) отношения к первопричине. Показатель, позволяющий выявить первопричину неисправности, является надежным индикатором наличия неисправного компонента. Метрические выражения не возвращают это поле.
|
scalar |
boolean | Указывает, преобразуется ли метрическое выражение в скаляр (true) или в ряд (false). Скалярный результат всегда содержит одну точку данных. Количество точек данных в результате ряда зависит от используемого разрешения.
|
tags |
string [] | Метки, присвоенные метрике. Метрические выражения не возвращают это поле. |
transformations |
string [] | Операторы преобразования, которые можно добавить к текущему списку преобразований. |
unit |
string | Единица метрической системы. |
unitDisplayFormat |
string | Исходное значение хранится в битах или байтах. Пользовательский интерфейс может отображать его в следующих системах счисления:
Если не указано иное, используется десятичная система счисления. Метрические выражения не возвращают это поле. |
warnings |
string [] | Список потенциальных предупреждений, затрагивающих этот идентификатор. Например, использование устаревших функций и т. д. |
Объект MetricDefaultAggregation
Агрегирование метрики по умолчанию.
| Элемент | Тип | Описание |
|---|---|---|
parameter |
number | Процент, который необходимо выполнить. Допустимые значения находятся в диапазоне от 0 до 100. Применимо только к percentile типу агрегации.
|
type |
string | Тип агрегирования по умолчанию. |
Объект MetricDimensionCardinality
Мощность размерностей метрики.
| Элемент | Тип | Описание |
|---|---|---|
estimate |
integer | Оценка мощности размерности. |
key |
string | Ключ к измерению. Оно должно быть уникальным в рамках данной метрики. |
relative |
number | Относительная мощность измерения, выраженная в процентах. |
Объект MetricDimensionDefinition
Размерность метрики.
| Элемент | Тип | Описание |
|---|---|---|
displayName |
string | Отображаемое название измерения. |
index |
integer | Уникальный индекс измерения, начинающийся с 0. Добавление преобразований, таких как :names или :parents, может изменять индексы измерений. null используется для измерений метрики с гибкими измерениями, на которые можно ссылаться по их ключу измерения, но которые не имеют внутреннего порядка, который можно было бы использовать для индекса.
|
key |
string | Ключ к измерению. Оно должно быть уникальным в рамках данной метрики. |
name |
string | Название измерения. |
type |
string | Тип измерения. Может принимать значения: ENTITY, NUMBER, OTHER, STRING, VOID.
|
Объект MetricValueType
Тип значения для метрики.
| Элемент | Тип | Описание |
|---|---|---|
type |
string | Тип значения метрики: error, score, unknown.
|
Модели JSON тела ответа
Успешный ответ (200)
{
"metrics": [
{
"aggregationTypes": [
"auto",
"value"
],
"created": 1597400123451,
"dduBillable": false,
"defaultAggregation": {
"type": "value"
},
"description": "Процент используемого в данный момент процессорного времени в пользовательском пространстве для каждого хоста.",
"dimensionDefinitions": [
{
"displayName": "Host",
"index": 0,
"key": "dt.entity.host",
"name": "Host",
"type": "ENTITY"
}
],
"displayName": "Пользователь ЦП",
"entityType": [
"HOST"
],
"lastWritten": 1597400717783,
"metricId": "builtin:host.cpu.user:splitBy(\"dt.entity.host\"):max:fold",
"metricValueType": {
"type": "unknown"
},
"tags": [],
"transformations": [
"filter",
"fold",
"limit",
"merge",
"names",
"parents",
"timeshift",
"rate",
"sort",
"last",
"splitBy"
],
"unit": "Percent"
},
{
"aggregationTypes": [
"auto",
"value"
],
"created": 1597400123451,
"dduBillable": false,
"defaultAggregation": {
"type": "value"
},
"description": "Процент используемого в данный момент процессорного времени в пользовательском пространстве для каждого хоста.",
"dimensionDefinitions": [
{
"displayName": "Host",
"index": 0,
"key": "dt.entity.host",
"name": "Host",
"type": "ENTITY"
}
],
"displayName": "Пользователь ЦП",
"entityType": [
"HOST"
],
"lastWritten": 1597400717783,
"metricId": "builtin:host.cpu.user:splitBy()",
"metricValueType": {
"type": "unknown"
},
"tags": [],
"transformations": [
"filter",
"fold",
"limit",
"merge",
"names",
"parents",
"timeshift",
"rate",
"sort",
"last",
"splitBy"
],
"unit": "Percent"
}
],
"nextPageKey": "ABCDEFABCDEFABCDEF_",
"totalCount": 3
}
|
Ответ с ошибкой
{
"error": {
"code": 1,
"constraintViolations": [
{
"location": "string",
"message": "string",
"parameterLocation": "HEADER",
"path": "string"
}
],
"message": "string"
}
}
|
Пример
В этом примере запрос запрашивает все встроенные метрики (параметр metricSelector установлен в значение builtin:*), доступные в среде mySampleEnv. В ответ включены следующие поля: metricId, unit, aggregationTypes. Для этого параметр запроса fields устанавливается в значение unit,aggregationTypes.
API-токен передается в заголовке Authorization.
cURL
curl -L -X GET 'https://mySampleEnv.live.astromkey.com/api/v2/metrics?fields=unit,aggregationTypes&metricSelector=builtin:*' \ -H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \ -H 'Accept: application/json'
URL запроса
https://mySampleEnv.live.astromkey.com/api/v2/metrics?fields=unit,aggregationTypes&metricSelector=builtin:*
Тело ответа (JSON)
{
"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"
]
}
]
}
|
Тело ответа (CSV с заголовком)
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]"
Код ответа: 200
