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

API Ключ-АСТРОМ / Эндпойнты среды / Развёртывание / Метрики v2 / Получение точки данных метрики

Получает точки данных указанных показателей.

Вы можете получить либо одну агрегированную точку данных на запись (уникальные комбинации метрика-измерение-значение измерения), либо список точек данных на запись. См. описание параметра разрешения запроса для получения дополнительной информации.

Применяются следующие ограничения:

• Количество точек данных ограничено 20 000 000.
• Количество кортежей ограничено 100 000. При превышении :sortобрабатываются только первые 100 000 записей (на них преобразование не влияет), а остальные игнорируются.
• Количество точек данных на запись ограничено 10 080.
• Количество отслеживаемых сущностей ограничено 5000 на каждый entitySelector в запросе.

Важно:

Эти ограничения применяются к точкам данных, которые запрос считывает в базе данных. Количество точек данных в конечном результате может отличаться. Например, если используется :foldпреобразование, запрос считывает несколько точек данных, но возвращает только одну агрегированную точку данных для каждой записи.

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

• application/json
• text/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 метрик для одного запроса. Можно указать несколько ключей метрик, разделенных запятыми (например, metrickey1,metrickey2). Чтобы выбрать несколько метрик, принадлежащих одному и тому же родителю, перечислите последнюю часть необходимых ключей метрик в круглых скобках, разделенных запятыми, не затрагивая общую часть. Например, чтобы перечислить метрику builtin:host.cpu.idleи , напишите: .builtin:host.cpu.userbuiltin:host.cpu.(idle,user) Если ключ метрики содержит какие-либо символы, ключ необходимо заключить в кавычки ( "). Следующие символы внутри заключенного в кавычки ключа метрики должны быть экранированы тильдой ( ~): Цитаты ( ") Тильды ( ~) Например, чтобы запросить метрику с ключом ext:selfmonitoring.jmx.Agents: Введите «APACHE» , вы должны указать этот селектор: "ext:selfmonitoring.jmx.Agents: Type ~"APACHE~"" Вы можете установить дополнительные операторы преобразования, разделенные двоеточием ( :). Дополнительную информацию о доступных преобразованиях результатов и синтаксисе см. в разделе Преобразования селектора показателей в документации Ключ-АСТРОМ.	query	по желанию
resolution	string	Желаемое разрешение точек данных. Вы можете использовать один из следующих вариантов: Желаемое количество точек данных. Это опция по умолчанию. Это контрольное количество точек, которое не обязательно равно количеству возвращаемых точек данных. Желаемый промежуток времени между точками данных. Это эталонный временной интервал, который не обязательно равен возвращаемому временному интервалу. Чтобы использовать эту опцию, укажите единицу измерения временного интервала. Допустимые единицы для временного интервала: m: минуты h: часы d: дней w: недели M: месяцы y: годы Если не задано, по умолчанию используется 120 точек данных . Например: Получите точки данных с разницей в 10 минут:resolution=10m Получите точки данных с разницей в 3 недели:resolution=3w	query	по желанию
from	string	Начало запрошенного таймфрейма. Вы можете использовать один из следующих форматов: Отметка времени в миллисекундах UTC. Человекочитаемый формат 2021-01-25T05:57:01.123+01:00. Если часовой пояс не указан, используется UTC. Вы можете использовать пробел вместо T. Секунды и доли секунды не являются обязательными. Относительный таймфрейм, назад. Формат: now-NU/A, где Nколичество времени, Uединица времени и Aвыравнивание. Выравнивание округляет все меньшие значения до ближайшего нуля в прошлом. Например, now-1y/wэто один год назад, выровненный на неделю. Вы также можете указать относительный таймфрейм без выравнивания: now-NU. Поддерживаемые единицы времени для относительного таймфрейма: m: минуты h: часы d: дней w: недели M: месяцы y: годы Если не установлено, используется относительный таймфрейм в два часа ( now-2h).	query	по желанию
to	string	Конец запрошенного периода времени. Вы можете использовать один из следующих форматов: Отметка времени в миллисекундах UTC. Человекочитаемый формат 2021-01-25T05:57:01.123+01:00. Если часовой пояс не указан, используется UTC. Вы можете использовать пробел вместо T. Секунды и доли секунды не являются обязательными. Относительный таймфрейм, назад. Формат: now-NU/A, где Nколичество времени, Uединица времени и Aвыравнивание. Выравнивание округляет все меньшие значения до ближайшего нуля в прошлом. Например, now-1y/wэто один год назад, выровненный на неделю. Вы также можете указать относительный таймфрейм без выравнивания: now-NU. Поддерживаемые единицы времени для относительного таймфрейма: m: минуты h: часы d: дней w: недели M: месяцы y: годы Если не установлено, используется текущая метка времени.	query	по желанию
entitySelector	string	Задает область сущности запроса. В ответ включаются только точки данных, доставленные совпавшими объектами. Вы должны установить один из этих критериев: Тип объекта:type("TYPE") Идентификатор объекта Ключ-АСТРОМ: entityId("id"). Вы можете указать несколько идентификаторов, разделенных запятой ( entityId("id-1","id-2")). Все запрошенные сущности должны быть одного типа. Вы можете добавить один или несколько следующих критериев. Значения чувствительны к регистру, и EQUALSоператор используется, если не указано иное. Тег: tag("value"). Теги в форматах [context]key:value, key:valueи valueобнаруживаются и анализируются автоматически. Любые двоеточия ( :), которые являются частью ключа или значения, должны быть экранированы обратной косой чертой ( \), в противном случае она будет интерпретироваться как разделитель между ключом и значением. Все значения тегов чувствительны к регистру. Идентификатор зоны управления:mzId(123) Название зоны управления:mzName("value") Имя сущности: entityName.equals: выполняет EQUALSзапрос без учета регистра. entityName.startsWith: изменяет оператор на BEGINS WITH. entityName.in: позволяет указать несколько значений. Оператор EQUALSобращается. caseSensitive(entityName.equals("value")): принимает любой критерий имени сущности в качестве аргументов и делает значение чувствительным к регистру. Состояние здоровья (HEALTHY,UNHEALTHY):healthState("HEALTHY") Отметка времени первого увиденного: firstSeenTms.<operator>(now-3h). Используйте любой формат метки времени из параметров from / to . Доступны следующие операторы: lte: раньше или в указанное время lt: раньше указанного времени gte: позже или в указанное время gt: позже указанного времени Атрибут объекта: <attribute>("value1","value2")и <attribute>.exists(). Чтобы получить список доступных атрибутов, выполните запрос типа сущности GET и проверьте поле свойств ответа. Отношения: fromRelationships.<relationshipName>()и toRelationships.<relationshipName>(). Критерий принимает селектор объектов в качестве атрибута. Чтобы получить список доступных отношений, выполните запрос типа сущности GET и проверьте поля fromRelationships и toRelationships . Отрицание: not(<criterion>). Инвертирует любой критерий, кроме type . Дополнительные сведения см. в разделе Селектор объектов в документации Ключ-АСТРОМ. Чтобы задать несколько критериев, разделите их запятой ( ,). Например, type("HOST"),healthState("HEALTHY"). В ответ включаются только результаты, соответствующие всем критериям. Поддерживаемая длина строки составляет 2000 символов. Используйте GET /metrics/{metricId}вызов, чтобы получить список возможных типов сущностей для вашей метрики. Чтобы установить универсальную область, соответствующую всем объектам, опустите этот параметр.	query	по желанию
mzSelector	string	Область зоны управления запроса. В ответ включаются только данные показателей, относящиеся к указанным зонам управления. Вы можете установить один или несколько из следующих критериев. Значения чувствительны к регистру и используется EQUALSоператор. Если указано несколько значений, применяется логика ИЛИ . mzId(123,456) mzName("name-1","name-2") Чтобы задать несколько критериев, разделите их запятой ( ,). Например, mzName("name-1","name-2"),mzId(1234). В ответ включаются только результаты, соответствующие всем критериям. Например, чтобы вывести список показателей с идентификатором 123 ИЛИ 234 И именем name-1 ИЛИ name-2 , используйте этот mzSelector : `mzId(123,234),mzName(" имя-1","имя-2").	query	по желанию

Ответ

Коды ответов

Код	Тип	Описание
200	Данные метрики	Успех
400		Ошибка синтаксиса или проверки. Параметры from и to, entitySelector или разрешение неверны по отдельности или в их комбинированном значении.
404		Метрика не найдена.
406		Неприемлимо. Запрошенный тип носителя не поддерживается. Проверьте заголовок Accept вашего запроса.

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

Объект MetricData

Список метрик и их точек данных.

Элемент	Тип	Описание
resolution	string	Разрешение временного интервала в результате.
nextPageKey	string	Устарело. Это поле возвращено из соображений совместимости. Он всегда имеет значение null.
totalCount	integer	Общее количество первичных сущностей в результате. Имеет 0значение, если ни одна из запрошенных метрик не подходит для разбиения на страницы.
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	Тип этого фильтра определяет, какие другие поля присутствуют. Может быть любым из: eq, ne, prefix, in, remainder, suffix, contains, existsKey, series, or, and, not, ge, gt, le, lt, otherwise. Элемент может содержать эти значения and contains eq existsKey ge gt in le lt ne not or otherwise prefix remainder series suffix

Объект Invocation

Вызов функции, например, entitySelectorfunction.

Элемент	Тип	Описание
args	string []	Аргументы для передачи функции, например, исходный код селектора сущностей.
function	string	Вызываемая функция, например entitySelector.

Объект Rollup

Способ просмотра серии как одного значения для целей сортировки или фильтров на основе серий.

Элемент	Тип	Описание
parameter	number	-
type	string	- Элемент может содержать эти значения AUTO AVG MAX MEDIAN MIN PERCENTILE SUM

Объект MetricSeries

Точки данных для каждого параметра метрики.

Данные представлены двумя массивами одинаковой длины: timestamps и values . Записи одного и того же индекса из обоих массивов образуют точку данных с отметкой времени.

Элемент	Тип	Описание
dimensionMap	object	-
timestamps	integer []	Список временных меток точек данных. Значение точки данных для каждого времени из этого массива находится в массиве значений по тому же индексу.
dimensions	string[]	Упорядоченный список измерений, к которым принадлежит список точек данных. Каждая метрика может иметь определенное количество измерений. Размеры, превышающие это число, объединяются в один, как показано nullздесь.
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