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

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

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

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

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

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

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

• Управляемые удостоверения для ресурсов Azure. Управляемое удостоверение можно использовать для предоставления ресурсам разрешений на выполнение определенных операций. Примером может служить позволение ресурсу публиковать свои собственные метрики. Ресурсу или его управляемому удостоверению могут быть даны разрешения Monitoring Metrics Publisher на другой ресурс. С этим разрешением управляемое удостоверение может также выдавать метрики для других ресурсов.

• Учетная запись службы Microsoft Entra. В этом сценарии приложению или службе Microsoft Entra могут быть разрешены полномочия на сбор метрик об Azure ресурсе. Для проверки подлинности запроса Azure Monitor проверяет токен приложения с помощью открытых ключей Microsoft Entra. У существующей роли Monitoring Metrics Publisher уже есть это разрешение. Он доступен на портале Azure.

  Учетной записи службы, в зависимости от ресурсов, для которых она генерирует пользовательские метрики, может быть назначена роль Monitoring Metrics Publisher в требуемой области. Примеры включают подписку, группу ресурсов или конкретный ресурс.

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

После создания управляемого удостоверения или субъекта-службы и назначения разрешений Издателя метрик мониторинга вы можете получить токен авторизации. При запросе указать resource: https://monitoring.azure.comтокен.

Получите токен аутентификации, используя один из следующих методов:

• интерфейс командной строки (CLI)
• REST API
• Пакет SDK

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={resource URI of the service you want to access, e.g. https://monitoring.azure.com>'}'

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "{resource URI of the service you want to access, e.g. https://monitoring.azure.com>'}",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

az account get-access-token

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

Тема

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

Регион

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

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

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

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

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

Имя

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

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

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

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

Размеры являются необязательными, и не все метрики их имеют. Пользовательская метрика может содержать до 10 измерений.

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

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

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

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

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

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

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

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

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

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

Затем результирующая публикация метрик для 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 
  

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

1. Войдите на портал Azure.

2. В меню слева выберите Монитор.

3. На странице Монитор щелкните Метрики.

   Скриншот, демонстрирующий как выбрать Метрики на портале Azure.

4. Измените период агрегирования на Последний час.

5. В раскрывающемся списке "Область" выберите ресурс, для который вы отправляете метрику.

6. В раскрывающемся списке пространства имен метрик выберите профиль памяти.

7. В раскрывающемся списке метрик выберите используемое количество байтов памяти.

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

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

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

Дальнейшие действия

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