Прием пользовательских метрик для ресурса Azure с помощью REST API

Статья
01/08/2024

В этой статье показано, как отправлять пользовательские метрики для ресурсов Azure в хранилище метрик Azure Monitor через REST API. Когда метрики находятся в Azure Monitor, вы можете выполнять все действия с ними, которые вы делаете со стандартными метриками. Например, можно создавать диаграммы и оповещения, а также направлять метрики другим внешним средствам.

Примечание.

REST API позволяет отправлять пользовательские метрики только для ресурсов Azure. Чтобы отправлять метрики для ресурсов в других средах или локальных средах, используйте Аналитика приложений.

Отправка запросов REST для приема пользовательских метрик

При отправке пользовательских метрик в Azure Monitor каждая отправляемая точка данных или значение в метриках должны включать следующие сведения.

Маркер проверки подлинности
Тема
Регион
Timestamp
Пространство имен
Имя
Ключи измерения
Значения измерения
Значения метрик

Проверка подлинности

Чтобы отправить пользовательские метрики в Azure Monitor, сущность, которая отправляет метрики, требует допустимого маркера Microsoft Entra в заголовке носителя запроса. Поддерживаемые способы получить действительный маркер носителя включают следующие:

Управляемые удостоверения для ресурсов Azure. Управляемое удостоверение можно использовать для предоставления ресурсам разрешений на выполнение определенных операций. Пример разрешает ресурсам выдать собственные метрики. Ресурсу, или его управляемому удостоверению, можно дать разрешение Издатель метрик мониторинга на другой ресурс. С этим разрешением управляемое удостоверение может также выдавать метрики для других ресурсов.
Субъект-служба Microsoft Entra. В этом сценарии приложение Microsoft Entra или служба могут быть назначены разрешения на выдачу метрик о ресурсе Azure. Для проверки подлинности запроса Azure Monitor проверяет маркер приложения с помощью открытых ключей Microsoft Entra. Существующая роль Издатель метрик мониторинга имеет это разрешение, доступное на портале Azure. Доступно на портале Azure.

Субъекту-службе (в зависимости от того, для каких ресурсов будут отправляться пользовательские метрики) можно предоставить роль Издатель метрик мониторинга в необходимой области. Например, в подписке, группе ресурсов или в ресурсе.

Совет

При запросе маркера Microsoft Entra для отправки пользовательских метрик убедитесь, что для аудитории или ресурса запрашивается https://monitoring.azure.com/маркер. Убедитесь, что адрес содержит завершающую косую черту.

Получение маркера авторизации

После создания управляемого удостоверения или субъекта-службы и назначения разрешений издателя метрик мониторинга можно получить маркер авторизации с помощью следующего запроса:

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://monitoring.azure.com'

Текст ответа отображается в следующем формате:

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https://monitoring.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

Сохраните маркер доступа из ответа для использования в следующих HTTP-запросах.

Тема

Это свойство субъекта содержит ИД ресурса Azure, для которого предоставляется пользовательская метрика. Эти сведения кодируются в URL-адресе вызова API. Каждый API может отправлять значения метрик только для одного ресурса Azure.

Примечание.

Отправить пользовательские метрики с помощью идентификатора группы ресурсов или подписки невозможно.

Область/регион

В этом свойстве указывается регион Azure, где развертывается ресурс, для которого отправляются метрики. Метрики должны отправляться в конечную точку Azure Monitor того же региона, в котором развертывается ресурс. Например, пользовательские метрики для виртуальной машины, развернутой в регионе "Западная часть США", должны отправляться в конечную точку Azure Monitor региона "Западная часть США". Сведения о регионе также кодируются в URL-адресе вызова API.

Метка времени

Каждая точка данных, отправляемая в Azure Monitor, должна быть отмечена временной меткой. Эта метка времени содержит дату и время измерения или получения метрики. Azure Monitor принимает данные метрик с метками времени до 20 минут назад и до 5 минут вперед. Метка времени должна быть указана в формате ISO 8601.

Пространство имен

При помощи пространств имен можно классифицировать или группировать похожие метрики. Они позволяют обеспечить изоляцию между группами метрик, которые смогут собирать разные аналитические сведения или индикаторы производительности. Например, у вас есть пространство имен с именем contosomemorymetrics, отслеживающее метрики использования памяти, которые профилируют приложения. Другое пространство имен, которое называется contosoapptransaction, может отслеживать все метрики о пользовательских транзакциях в приложении.

Имя.

Свойство "Имя" — это имя отправляемой метрики. Как правило, оно является достаточно описательным, чтобы указать измеряемый показатель. Пример представляет собой показатель, который измеряет количество байтов памяти, используемых на виртуальной машине. Например, имя метрики Используемые байты памяти.

Ключи измерений

Измерение — это пара "ключ-значение", помогающая описывать другие характеристики собираемой метрики. С помощью других характеристик можно собирать больше данных о метрике, которые предоставляют больше аналитических сведений.

Например, у метрики Используемые байты памяти может быть ключ измерения под названием Процесс, в котором указано, сколько байтов памяти использует каждый процесс на виртуальной машине. Использование этого ключа позволяет фильтровать метрику, чтобы узнать, сколько памяти используют определенные процессы, или получить список 5 процессов, использующих больше всего памяти.

Измерения являются необязательными и могут быть не у всех метрик. У пользовательской метрики может быть до 10 измерений.

Значения измерений

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

имя метрики — Используемые байты памяти;
ключ измерения — Процесс;
значение измерения — ContosoApp.exe.

Публикуя значение метрики, можно указывать только по одному значению измерения на ключ. Собирая одни и те же данные об использовании памяти для нескольких процессов на виртуальной машине, можно отправить несколько значений метрик для этой метки времени. Каждое значение метрики задает отдельное значение измерения для ключа Процесс.

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

Значения метрик

При сохранении метрик Azure Monitor степень детализации составляет одну минуту. В течение данной минуты может понадобится замерять метрику несколько раз. Примером может служить загрузка ЦП. Или метрика может потребовать измерения для нескольких дискретных событий, например задержки транзакций при входе.

Чтобы ограничить количество необработанных значений, которые необходимо вывести и оплатить в Azure Monitor, локально предварительно агрегировать и вывести агрегированные значения:

Минимум — минимальное наблюдаемое значение из всех образцов или измерений за минуту.
Максимум — максимальное наблюдаемое значение из всех образцов или измерений за минуту.
Сумма — сумма всех наблюдаемых значений из всех образцов или измерений за минуту.
Количество — число образцов или измерений за минуту.

Примечание.

Azure Monitor не поддерживает определение единиц для пользовательской метрики.

Допустим, за минуту в приложении произошло четыре транзакции входа в приложение, в результате которых были получены следующие задержки:

Проводка 1	Проводка 2	Транзакция 3	Транзакция 4
7 мс	4 мс	13 мс	16 мс

Результаты публикации метрики в Azure Monitor будут следующими:

"Минимум": 4;
"Максимум": 16;
"Сумма": 40;
"Количество": 4.

Если приложение не может заранее выполнять статистическое вычисление в локальной среде и вынуждено отправлять каждый образец или событие сразу после сбора, то вы можете передавать необработанные значения показателей. Например, при каждой транзакции входа в приложении метрика будет публиковаться в Azure Monitor только с одним измерением. Таким образом, для транзакции входа, выполнение которой заняло 12 миллисекунд, будут опубликованы следующие метрики:

"Минимум": 12;
"Максимум": 12;
"Сумма": 12;
"Количество": 1.

С помощью этого процесса для одного сочетания метрики и измерения можно отправлять несколько значений за одну минуту. Затем Azure Monitor соберет все необработанные значения, переданные за эту минуту, и выполнит статистическое вычисление.

Пример публикации пользовательской метрики

В следующем примере создайте настраиваемую метрику с именем "Память байтов" в разделе "Профиль памяти пространства имен метрик" для виртуальной машины. У этой метрики есть одно измерение с именем Процесс. Значения метрики для метки времени выдаются для двух процессов.

Сохраните следующий код JSON в файле с именем custommetric.json на локальном компьютере. Обновите параметр времени, чтобы он был в течение последних 20 минут. Вы не можете поместить метрику в магазин, который превышает 20 минут.

{
    "time": "2024-01-07T11:25:20-7:00",
    "data": {

      "baseData": {

        "metric": "Memory Bytes in Use",
        "namespace": "Memory Profile",
        "dimNames": [
          "Process"
        ],
        "series": [
          {
            "dimValues": [
              "ContosoApp.exe"
            ],
            "min": 10,
            "max": 89,
            "sum": 190,
            "count": 4
          },
          {
            "dimValues": [
              "SalesApp.exe"
            ],
            "min": 10,
            "max": 23,
            "sum": 86,
            "count": 4
          }
        ]
      }
    }
  }

Отправьте следующий HTTP-запрос POST с помощью следующих переменных:

location: регион развертывания ресурса, для который вы генерируете метрики.
resourceId: идентификатор ресурса ресурса Azure, на который вы отслеживаете метрику.

accessToken: маркер авторизации, полученный на этапе получения маркера авторизации.

curl -X POST 'https://<location>/.monitoring.azure.com<resourceId>/metrics' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <accessToken>' \
-d @custommetric.json

Просмотр метрик

Войдите на портал Azure.
В меню слева выберите Монитор.
На странице Монитор щелкните Метрики.
Измените период агрегирования на Последний час.
В раскрывающемся списке "Область" выберите ресурс, для который вы отправляете метрику.
В раскрывающемся списке пространства имен метрик выберите профиль памяти.
В раскрывающемся списке метрик выберите "Память байтов" в разделе "Использование".

Устранение неполадок

Если на любом этапе процесса появится сообщение об ошибке, изучите следующие сведения об устранении неполадок:

Если вы не можете выдавать метрики для подписки или группы ресурсов или ресурса, проверка, что у приложения или субъекта-службы есть роль издателя метрик мониторинга, назначенная в элементе управления доступом (IAM).
Убедитесь, что число имен измерений соответствует количеству значений.
Убедитесь, что вы создаете метрики в правильную региональную конечную точку Azure Monitor. Например, если ресурс развернут в западной части США, необходимо отправить метрики в конечную точку региона Западной части США.
Убедитесь, что метка времени находится в течение последних 20 минут.
Убедитесь, что метка времени находится в формате ISO 8601.
Убедитесь, что имя метрики допустимо. Например, он не может содержать пробелы.

Следующие шаги

Дополнительные сведения о настраиваемых метриках см. в этой статье.

Прием пользовательских метрик для ресурса Azure с помощью REST API

Отправка запросов REST для приема пользовательских метрик

Проверка подлинности

Получение маркера авторизации

Тема

Область/регион

Метка времени

Пространство имен

Имя.

Ключи измерений

Значения измерений

Значения метрик

Пример публикации пользовательской метрики

Просмотр метрик

Устранение неполадок

Следующие шаги

Дополнительные ресурсы