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

Материал из Документация Ключ-АСТРОМ
Версия от 15:52, 5 октября 2022; ENetrebin (обсуждение | вклад) (Новая страница: «Получает точки данных указанных показателей. Вы можете получить либо одну агрегированн...»)
(разн.) ← Предыдущая | Текущая версия (разн.) | Следующая → (разн.)

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

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

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

  • Количество точек данных ограничено 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 , возвращается полезная нагрузка.

ПОЛУЧИТЬ Удалось https://{your-domain}/e/{your-environment-id}/api/v2/metrics/query
SaaS https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/query
Окружающая среда ActiveGate https://{your-activegate-domain}/e/{your-environment-id}/api/v2/metrics/query

Аутентификация

Чтобы выполнить этот запрос, вам нужен токен доступа с областью действия Чтение метрик ( metrics.read) . Чтобы узнать, как его получить и использовать, см. раздел Токены и аутентификация .

Параметры

Параметр Тип Описание В Необходимый
метрическийселектор нить Выбирает метрики для запроса по их ключам. Вы можете выбрать до 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~""

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

запрос по желанию
разрешающая способность нить Желаемое разрешение точек данных.

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

  • Желаемое количество точек данных. Это опция по умолчанию. Это контрольное количество точек, которое не обязательно равно количеству возвращаемых точек данных.
  • Желаемый промежуток времени между точками данных. Это эталонный временной интервал, который не обязательно равен возвращаемому временному интервалу. Чтобы использовать эту опцию, укажите единицу измерения временного интервала.

Допустимые единицы для временного интервала:

  • m: минут
  • h: часы
  • d: дней
  • w: недели
  • M: месяцы
  • y: годы

Если не задано, по умолчанию используется 120 точек данных .

Например:

  • Получите точки данных с разницей в 10 минут:resolution=10m
  • Получите точки данных с разницей в 3 недели:resolution=3w
запрос по желанию
из нить Начало запрошенного таймфрейма.

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

  • Отметка времени в миллисекундах 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).

запрос по желанию
к нить Конец запрошенного периода времени.

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

  • Отметка времени в миллисекундах 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: годы

Если не установлено, используется текущая метка времени.

запрос по желанию
селектор объектов нить Задает область сущности запроса. В ответ включаются только точки данных, доставленные совпавшими объектами.

Вы должны установить один из этих критериев:

  • Тип объекта:type("TYPE")
  • Идентификатор объекта Dynatrace: 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")): принимает любой критерий имени сущности в качестве аргументов и делает значение чувствительным к регистру.
  • Состояние здоровья (ЗДОРОВЫЙ, НЕЗДОРОВЫЙ):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 .

Дополнительные сведения см. в разделе Селектор объектов в документации Dynatrace.

Чтобы задать несколько критериев, разделите их запятой ( ,). Например, type("HOST"),healthState("HEALTHY"). В ответ включаются только результаты, соответствующие всем критериям.

Поддерживаемая длина строки составляет 2000 символов.

Используйте GET /metrics/{metricId}вызов, чтобы получить список возможных типов сущностей для вашей метрики.

Чтобы установить универсальную область, соответствующую всем объектам, опустите этот параметр.

запрос по желанию
mzSelector нить Область зоны управления запроса. В ответ включаются только данные показателей, относящиеся к указанным зонам управления.

Вы можете установить один или несколько из следующих критериев. Значения чувствительны к регистру и используется 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").
запрос по желанию

Ответ

Коды ответов

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

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

Объект _ MetricData

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

Элемент Тип Описание
разрешающая способность нить Разрешение временного интервала в результате.
ключ следующей страницы нить Устарело. Это поле возвращено из соображений совместимости. Он всегда имеет значение null.
общее количество целое число Общее количество первичных сущностей в результате.

Имеет 0значение, если ни одна из запрошенных метрик не подходит для разбиения на страницы.

результат Коллекция метрических серий [] Список метрик и их точек данных.
предупреждения строка [] Список предупреждений

Объект _ MetricSeriesCollection

Точки данных метрики.

Элемент Тип Описание
dataPointCountRatio количество Отношение запрошенных точек данных к максимальному количеству точек данных на метрику, разрешенных в одном запросе.
примененные необязательные фильтры Примененный фильтр [] Список отфильтрованных ключей метрик вместе с фильтрами, примененными к этим ключам, из optionalFilterпараметра.
измерениеCountRatio количество Отношение запрошенных кортежей измерений к максимальному количеству кортежей измерений, разрешенных в одном запросе.
идентификатор метрики нить Ключ метрики.

Если применяется какое-либо преобразование, оно включается здесь.

данные Метрическая серия [] Точки данных метрики.
предупреждения строка [] Список потенциальных предупреждений, влияющих на этот идентификатор. Например, использование устаревших функций и т. д.

Объект _ AppliedFilter

Вступившие в силу дополнительные фильтры.

Элемент Тип Описание
применительно к строка [] Ключи всех метрик, к которым применен этот фильтр.

Может содержать несколько метрик для сложных выражений и всегда по крайней мере один ключ.

фильтр Фильтр Фильтр измерений или рядов для метрики.

Объект _ Filter

Фильтр измерений или рядов для метрики.

Элемент Тип Описание
ссылкаВызов Вызов Вызов функции, например, entitySelectorfunction.
targetDimension нить Если тип применяется к измерению, то содержит целевое измерение.
targetDimensions строка [] Если тип применяется к n измерениям, то содержит целевые измерения. В настоящее время используется только для remainderфильтра.
ссылкаСтрока нить Для фильтров, которые сопоставляют измерение со значением, например eqили ne, содержит значение, с которым сравнивается измерение.
свернуть Свернуть Способ просмотра серии как одного значения для целей сортировки или фильтров на основе серий.
исходная величина количество Для операндов seriesфильтров, совпадающих с числом, содержит число для сравнения.
операнды Фильтр [] Если тип — или not, то содержит содержащиеся фильтры.andor
тип нить Тип этого фильтра определяет, какие другие поля присутствуют. Может быть любым из:
  • eq,
  • ne,
  • prefix,
  • in,
  • remainder,
  • suffix,
  • contains,
  • existsKey,
  • series,
  • or,
  • and,
  • not,
  • ge,
  • gt,
  • le,
  • lt,
  • otherwise.

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

Объект _ Invocation

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

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

Объект _ Rollup

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

Элемент Тип Описание
параметр количество -
тип нить -

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

  • AUTO
  • AVG
  • MAX
  • MEDIAN
  • MIN
  • PERCENTILE
  • SUM

Объект _ MetricSeries

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

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

Элемент Тип Описание
измерениеКарта объект -
временные метки целое [] Список временных меток точек данных.

Значение точки данных для каждого времени из этого массива находится в массиве значений по тому же индексу.

Габаритные размеры строка [] Упорядоченный список измерений, к которым принадлежит список точек данных.

Каждая метрика может иметь определенное количество измерений. Размеры, превышающие это число, объединяются в один, как показано nullздесь.

ценности номер [] Список значений точек данных.

Временная метка точки данных для каждого значения из этого массива находится в массиве временных меток по тому же индексу.

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

Примечание о таймфрейме

Dynatrace хранит данные во временных интервалах. Объект MetricValue показывает отметку времени окончания слота. Если время, указанное в параметрах from или to вашего запроса, попадает в временной интервал данных, этот временной интервал включается в ответ.

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

Dynatrace не предсказывает будущие данные. Временная метка последней точки данных может лежать в будущем из-за принципа интервалов данных, описанного выше. В этом случае этот слот данных имеет неполные данные.

Примеры

В этих примерах запросы запрашивают точки данных встроенных: 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формате.

Завиток

С непреобразованными метриками и фильтром entitySelector :

curl -L -X GET 'https://mySampleEnv.live.dynatrace.com/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.dynatrace.com/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.dynatrace.com/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.dynatrace.com/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