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

Статья
11/05/2024

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

Примечание.

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

Отправка запросов 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/маркер. Убедитесь, что адрес содержит завершающую косую черту.

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

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

Получите маркер проверки подлинности с помощью любого из следующих методов:

CLI
REST API
SDK

При запросе маркера необходимо указать resource параметр. Параметр resource — это URL-адрес ресурса, к которому требуется получить доступ.

В число доступных ресурсов входят:

https://management.azure.com
https://api.loganalytics.io
https://monitoring.azure.com

Получение маркера с помощью запроса REST

Чтобы получить маркер, используйте следующий вызов REST API. Этот запрос использует идентификатор клиента и секрет клиента для проверки подлинности запроса. Идентификатор клиента и секрет клиента получаются при регистрации приложения с помощью идентификатора Microsoft Entra. Дополнительные сведения см. в статье "Регистрация приложения для запроса маркеров авторизации" и работы с API

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

Получение маркера с помощью Azure CLI

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

az account get-access-token

Дополнительные сведения см. в статье az account get-access-token

Получение маркера с помощью пакетов SDK

В следующих примерах кода показано, как получить маркер с помощью:

C#
NodeJS
Python

C#

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

var context = new AuthenticationContext("https://login.microsoftonline.com/<tennant ID>");
var clientCredential = new ClientCredential("<your apps client ID>", "<your apps client secret>");
var result = context.AcquireTokenAsync("https://monitoring.azure.com", clientCredential).Result;

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

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

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

string userAssignedClientId = "<your managed identity client ID>";
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = userAssignedClientId
    });

var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

Дополнительные сведения см. в разделе DefaultAzureCredential Class

Node.js

Сведения о проверке подлинности с помощью JavaScript и NodeJS см. в статье "Проверка подлинности приложений JavaScript в службах Azure с помощью пакета SDK Azure для JavaScript"

В следующем коде показано, как получить маркер с помощью класса DefaultAzureCredential. Этот метод использует учетные данные Azure по умолчанию для проверки подлинности запроса и не требует идентификатора клиента или секрета клиента.

const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const accessToken = await credential.getToken("https://management.azure.com/.default");

Вы также можете использовать InteractiveBrowserCredential класс для получения учетных данных. Этот метод предоставляет интерфейс проверки подлинности на основе браузера для пользователей для проверки подлинности с помощью служб Azure.

Дополнительные сведения см. в разделе DefaultAzureCredential Class и InteractiveBrowserCredential Class

Кроме того, для получения маркера можно использовать класс ClientSecretCredential. Для проверки подлинности запроса этот метод требует идентификатора клиента и секрета клиента.

const { ClientSecretCredential } = require("@azure/identity");
credential = ClientSecretCredential(
    client_id="<client_id>",
    username="<username>",
    password="<password>"
   )
const accessToken = await credential.getToken("https://management.azure.com/.default");

Дополнительные сведения см. в разделе "Класс ClientSecretCredential"

Python

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token('https://management.azure.com/.default')
print(token.token)

Дополнительные сведения см. в разделе DefaultAzureCredential Class и InteractiveBrowserCredential Class

from azure.identity import ClientSecretCredential

credential = ClientSecretCredential (
     tenant_id="<tenant id>",
     client_id="<Client id>",
     client_secret="client secret"
    )
token =  credential.get_token("https://management.azure.com/.default")
print(token.token)

Дополнительные сведения см. в разделе "Класс ClientSecretCredential"

Сохраните маркер доступа из ответа для использования в следующих 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 для приема пользовательских метрик

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

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

Получение маркера с помощью запроса REST

Получение маркера с помощью Azure CLI

Получение маркера с помощью пакетов SDK

C#

Node.js

Python

Тема

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

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

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

Имя.

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

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

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

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

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

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

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

Обратная связь

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