Получение точки данных метрики
API Ключ-АСТРОМ / Эндпойнты среды / Развёртывание / Метрики v2 / Получение точки данных метрики
Получает точки данных указанных показателей.
Вы можете получить либо одну агрегированную точку данных на запись (уникальные комбинации метрика-измерение-значение измерения), либо список точек данных на запись. См. описание параметра разрешения запроса для получения дополнительной информации.
Применяются следующие ограничения:
- Количество точек данных ограничено 20 000 000.
- Количество кортежей ограничено 100 000. При превышении
:sortобрабатываются только первые 100 000 записей (на них преобразование не влияет), а остальные игнорируются. - Количество точек данных на запись ограничено 10 080.
- Количество отслеживаемых сущностей ограничено 5000 на каждый entitySelector в запросе.
Важно:
Эти ограничения применяются к точкам данных, которые запрос считывает в базе данных. Количество точек данных в конечном результате может отличаться. Например, если используется :foldпреобразование, запрос считывает несколько точек данных, но возвращает только одну агрегированную точку данных для каждой записи.
Запрос создает один из следующих типов полезной нагрузки, в зависимости от значения заголовка запроса Accept :
application/jsontext/csv; header=present— таблица CSV со строкой заголовкаtext/csv; header=absent— таблица CSV без строки заголовка
Если с запросом не предоставлен заголовок Acceptapplication/json , возвращается полезная нагрузка.
| GET | Managed | https://{your-domain}/e/{your-environment-id}/api/v2/metrics/query
|
| SaaS | https://{your-environment-id}.live.ruscomech.ru/api/v2/metrics/query
| |
| Окружающая среда АктивногоШлюза | https://{your-activegate-domain}/e/{your-environment-id}/api/v2/metrics/query
|
Аутентификация
Чтобы выполнить этот запрос, вам нужен токен доступа с областью действия Чтение метрик ( metrics.read) . Чтобы узнать, как его получить и использовать, см. раздел Токены и аутентификация .
Параметры
| Параметр | Тип | Описание | In | Необходимость |
|---|---|---|---|---|
| metricSelector | string | Выбирает метрики для запроса по их ключам. Вы можете выбрать до 10 метрик для одного запроса.
Можно указать несколько ключей метрик, разделенных запятыми (например, Если ключ метрики содержит какие-либо символы, ключ необходимо заключить в кавычки (
Например, чтобы запросить метрику с ключом ext:selfmonitoring.jmx.Agents: Введите «APACHE» , вы должны указать этот селектор:
Вы можете установить дополнительные операторы преобразования, разделенные двоеточием ( |
query | по желанию |
| resolution | string | Желаемое разрешение точек данных.
Вы можете использовать один из следующих вариантов:
Допустимые единицы для временного интервала:
Если не задано, по умолчанию используется 120 точек данных . Например:
|
query | по желанию |
| from | string | Начало запрошенного таймфрейма.
Вы можете использовать один из следующих форматов:
Если не установлено, используется относительный таймфрейм в два часа ( |
query | по желанию |
| to | string | Конец запрошенного периода времени.
Вы можете использовать один из следующих форматов:
Если не установлено, используется текущая метка времени. |
query | по желанию |
| entitySelector | string | Задает область сущности запроса. В ответ включаются только точки данных, доставленные совпавшими объектами.
Вы должны установить один из этих критериев:
Вы можете добавить один или несколько следующих критериев. Значения чувствительны к регистру, и
Дополнительные сведения см. в разделе Селектор объектов в документации Ключ-АСТРОМ. Чтобы задать несколько критериев, разделите их запятой ( Поддерживаемая длина строки составляет 2000 символов. Используйте Чтобы установить универсальную область, соответствующую всем объектам, опустите этот параметр. |
query | по желанию |
| mzSelector | string | Область зоны управления запроса. В ответ включаются только данные показателей, относящиеся к указанным зонам управления.
Вы можете установить один или несколько из следующих критериев. Значения чувствительны к регистру и используется
|
query | по желанию |
Ответ
Коды ответов
| Код | Тип | Описание |
|---|---|---|
| 200 | Данные метрики | Успех |
| 400 | Ошибка синтаксиса или проверки. Параметры from и to, entitySelector или разрешение неверны по отдельности или в их комбинированном значении. | |
| 404 | Метрика не найдена. | |
| 406 | Неприемлимо. Запрошенный тип носителя не поддерживается. Проверьте заголовок Accept вашего запроса. |
Объекты тела ответа
Объект MetricData
Список метрик и их точек данных.
| Элемент | Тип | Описание |
|---|---|---|
| resolution | string | Разрешение временного интервала в результате. |
| nextPageKey | string | Устарело. Это поле возвращено из соображений совместимости. Он всегда имеет значение null.
|
| totalCount | integer | Общее количество первичных сущностей в результате.
Имеет |
| result | MetricSeriesCollection[] | Список метрик и их точек данных. |
| warnings | string [] | Список предупреждений |
Объект MetricSeriesCollection
Точки данных метрики.
| Элемент | Тип | Описание |
|---|---|---|
| dataPointCountRatio | number | Отношение запрошенных точек данных к максимальному количеству точек данных на метрику, разрешенных в одном запросе. |
| appliedOptionalFilters | AppliedFilter[] | Список отфильтрованных ключей метрик вместе с фильтрами, примененными к этим ключам, из optionalFilterпараметра.
|
| dimensionCountRatio | number | Отношение запрошенных записей измерений к максимальному количеству записей измерений, разрешенных в одном запросе. |
| metricId | string | Ключ метрики.
Если применяется какое-либо преобразование, оно включается здесь. |
| data | MetricSeries[] | Точки данных метрики. |
| warnings | string [] | Список потенциальных предупреждений, влияющих на этот идентификатор. Например, использование устаревших функций и т. д. |
Объект AppliedFilter
Вступившие в силу дополнительные фильтры.
| Элемент | Тип | Описание |
|---|---|---|
| appliedTo | string [] | Ключи всех метрик, к которым применен этот фильтр.
Может содержать несколько метрик для сложных выражений и всегда по крайней мере один ключ. |
| filter | Filter | Фильтр измерений или рядов для метрики. |
Объект Filter
Фильтр измерений или рядов для метрики.
| Элемент | Тип | Описание |
|---|---|---|
| referenceInvocation | Invocation | Вызов функции, например, entitySelectorfunction.
|
| targetDimension | string | Если тип применяется к измерению, то содержит целевое измерение. |
| referenceString | string [] | Если тип применяется к n измерениям, то содержит целевые измерения. В настоящее время используется только для remainderфильтра.
|
| referenceString | string | Для фильтров, которые сопоставляют измерение со значением, например eqили ne, содержит значение, с которым сравнивается измерение.
|
| rollup | Rollup | Способ просмотра серии как одного значения для целей сортировки или фильтров на основе серий. |
| referenceValue | number | Для операндов seriesфильтров, совпадающих с числом, содержит число для сравнения.
|
| operands | Filter [] | Если тип not, and or or, то включает содержащиеся фильтры.andor
|
| type | string | Тип этого фильтра определяет, какие другие поля присутствуют. Может быть любым из:
Элемент может содержать эти значения
|
Объект Invocation
Вызов функции, например, entitySelectorfunction.
| Элемент | Тип | Описание |
|---|---|---|
| args | string [] | Аргументы для передачи функции, например, исходный код селектора сущностей. |
| function | string | Вызываемая функция, например entitySelector.
|
Объект Rollup
Способ просмотра серии как одного значения для целей сортировки или фильтров на основе серий.
| Элемент | Тип | Описание |
|---|---|---|
| parameter | number | - |
| type | string | -
Элемент может содержать эти значения
|
Объект MetricSeries
Точки данных для каждого параметра метрики.
Данные представлены двумя массивами одинаковой длины: timestamps и values . Записи одного и того же индекса из обоих массивов образуют точку данных с отметкой времени.
| Элемент | Тип | Описание |
|---|---|---|
| dimensionMap | object | - |
| timestamps | integer [] | Список временных меток точек данных.
Значение точки данных для каждого времени из этого массива находится в массиве значений по тому же индексу. |
| dimensions | string[] | Упорядоченный список измерений, к которым принадлежит список точек данных.
Каждая метрика может иметь определенное количество измерений. Размеры, превышающие это число, объединяются в один, как показано |
| values | number [] | Список значений точек данных.
Временная метка точки данных для каждого значения из этого массива находится в массиве временных меток по тому же индексу. |
JSON-модель тела ответа
{
"totalCount": 3,
"nextPageKey": "null",
"resolution": "1h",
"warnings": [
"The contains filter transformation is deprecated and will be removed in a future release."
],
"result": [
{
"metricId": "builtin:host.disk.avail",
"dataPointCountRatio": "0.1211",
"dimensionCountRatio": "0.0322",
"data": [
{
"dimensionMap": {
"dt.entity.disk": "DISK-F1266E1D0AAC2C3F",
"dt.entity.host": "HOST-F1266E1D0AAC2C3C"
},
"dimensions": [
"HOST-F1266E1D0AAC2C3C",
"DISK-F1266E1D0AAC2C3F"
],
"timestamps": [
3151435100000,
3151438700000,
3151442300000
],
"values": [
11.1,
22.2,
33.3
]
},
{
"dimensions": [
"HOST-F1266E1D0AAC2C3C",
"DISK-F1266E1D0AAC2C3D"
],
"timestamps": [
3151435100000,
3151438700000,
3151442300000
],
"values": [
111.1,
222.2,
333.3
]
}
]
},
{
"metricId": "builtin:host.cpu.idle",
"data": [
{
"dimensionMap": {
"dt.entity.host": "HOST-F1266E1D0AAC2C3C"
},
"dimensions": [
"HOST-F1266E1D0AAC2C3C"
],
"timestamps": [
3151435100000,
3151438700000,
3151442300000
],
"values": [
1.1,
2.2,
3.3
]
}
]
}
]
}
Примечание о таймфрейме
Ключ-АСТРОМ хранит данные во временных интервалах. Объект MetricValue показывает отметку времени окончания слота. Если время, указанное в параметрах from или to вашего запроса, попадает в временной интервал данных, этот временной интервал включается в ответ.
Если временная метка последнего слота данных выходит за пределы указанного временного интервала, последняя точка данных ответа имеет более позднюю временную метку, чем указано в параметре запроса.
Ключ-АСТРОМ не предсказывает будущие данные. Временная метка последней точки данных может лежать в будущем из-за принципа интервалов данных, описанного выше. В этом случае этот слот данных имеет неполные данные.
Примеры
В этих примерах запросы запрашивают точки данных встроенных: host.cpu.usage и встроенных: host.cpu.idle метрик.
Таймфрейм установлен на 5 минут . Для этого параметру запроса fromnow-5m присваивается значение .
В ответ включаются только данные от этих двух хостов ( HOST-0990886B7D39FE29 и HOST-0956C3557E9109C1 ). Для этого параметру запроса entitySelector присваиваетсяtype("dt.entity.host"),entityId("HOST-0990886B7D39FE29") значение .
Поскольку узел является измерением запрошенных метрик, вы можете добиться той же фильтрации, применив :filterпреобразование к самим метрикам, установив для параметра запроса metricSelectorbuiltin:host.cpu.(usage,idle):filter(or(eq("dt.entity.host","HOST-0990886B7D39FE29"),eq("dt.entity.host","HOST-0956C3557E9109C1"))) значение и опустив entitySelector как избыточный.
Разница между запросами заключается в представлении данных: первый показывает список точек данных, а второй показывает только одну агрегированную точку данных для каждого ряда ( :foldпреобразование применяется в конце).
Маркер API передается в заголовке авторизации .
Ответ в application/jsonформате.
Curl
С непреобразованными метриками и фильтром entitySelector :
curl -L -X GET 'https://mySampleEnv.live.ruscomtech.ru/api/v2/metrics/query?metricSelector=builtin:host.cpu.(usage,idle)&entitySelector=type(%22dt.entity.host%22),entityId(%22HOST-0990886B7D39FE29%22,%22HOST-0956C3557E9109C1%22)&from=now-5m' \
-H 'Authorization: Api-Token abcdefjhij1234567890' \
-H 'Accept: application/json'
С преобразованием, применяемым непосредственно к метрикам:
curl -L -X GET 'https://mySampleEnv.live.ruscomtech.ru/api/v2/metrics/query?metricSelector=builtin:host.cpu.(usage,idle):filter(or(eq(%22dt.entity.host%22,%22HOST-0990886B7D39FE29%22),eq(%22dt.entity.host%22,%22HOST-0956C3557E9109C1%22)))&from=now-5m' \
-H 'Authorization: Api-Token abcdefjhij1234567890' \
-H 'Accept: application/json'
URL-адрес запроса
С непреобразованными метриками и фильтром entitySelector :
https://mySampleEnv.live.ruscomtech.ru/api/v2/metrics/query?metricSelector=builtin:host.cpu.(usage,idle)&entitySelector=type(%22dt.entity.host%22),entityId(%22HOST-0990886B7D39FE29%22,%22HOST-0956C3557E9109C1%22)&from=now-5m
С преобразованием, применяемым непосредственно к метрикам:
https://mySampleEnv.live.ruscomtech.ru/api/v2/metrics/query?metricSelector=builtin:host.cpu.(usage,idle):filter(or(eq(%22dt.entity.host%22,%22HOST-0990886B7D39FE29%22),eq(%22dt.entity.host%22,%22HOST-0956C3557E9109C1%22)))&from=now-5m
Тело ответа
Результат усекается до трех точек данных на измерение.
{
"totalCount": 2,
"nextPageKey": null,
"result": [
{
"metricId": "builtin:host.cpu.idle",
"dataPointCountRatio": 1.8E-5,
"dimensionCountRatio": 3.0E-5,
"data": [
{
"dimensions": [
"HOST-0990886B7D39FE29"
],
"dimensionMap": {
"dt.entity.host": "HOST-0990886B7D39FE29"
},
"timestamps": [
1589456100000,
1589456160000,
1589456220000
],
"values": [
81.0,
81.0,
79.0
]
},
{
"dimensions": [
"HOST-0956C3557E9109C1"
],
"dimensionMap": {
"dt.entity.host": "HOST-0956C3557E9109C1"
},
"timestamps": [
1589456100000,
1589456160000,
1589456220000
],
"values": [
81.0,
79.0,
78.0
]
}
]
},
{
"metricId": "builtin:host.cpu.usage",
"dataPointCountRatio": 1.8E-5,
"dimensionCountRatio": 3.0E-5,
"data": [
{
"dimensions": [
"HOST-0990886B7D39FE29"
],
"dimensionMap": {
"dt.entity.host": "HOST-0990886B7D39FE29"
},
"timestamps": [
1589456100000,
1589456160000,
1589456220000
],
"values": [
19.0,
19.0,
21.0
]
},
{
"dimensions": [
"HOST-0956C3557E9109C1"
],
"dimensionMap": {
"dt.entity.host": "HOST-0956C3557E9109C1"
},
"timestamps": [
1589456100000,
1589456160000,
1589456220000
],
"values": [
19.0,
21.0,
22.0
]
}
]
}
]
}
Таблица CSV со строкой заголовка выглядит следующим образом. Чтобы получить его, измените заголовок Accepttext/csv; header=present на .
metricId,dt.entity.host,time,value
builtin:host.cpu.usage,HOST-0956C3557E9109C1,2020-05-14 11:35:00,19.0
builtin:host.cpu.usage,HOST-0956C3557E9109C1,2020-05-14 11:36:00,19.0
builtin:host.cpu.usage,HOST-0956C3557E9109C1,2020-05-14 11:37:00,21.0
builtin:host.cpu.usage,HOST-0990886B7D39FE29,2020-05-14 11:35:00,19.0
builtin:host.cpu.usage,HOST-0990886B7D39FE29,2020-05-14 11:36:00,21.0
builtin:host.cpu.usage,HOST-0990886B7D39FE29,2020-05-14 11:37:00,22.0
Код ответа
200
