Ingestování vlastních metrik pro prostředek Azure pomocí rozhraní REST API

Článek
09/13/2024

V tomto článku se dozvíte, jak odesílat vlastní metriky pro prostředky Azure do úložiště metrik Služby Azure Monitor prostřednictvím rozhraní REST API. Když se metriky nacházejí ve službě Azure Monitor, můžete s nimi provádět všechny akce, které děláte se standardními metrikami. Můžete například generovat grafy a výstrahy a směrovat metriky do jiných externích nástrojů.

Poznámka:

Rozhraní REST API povoluje odesílání vlastních metrik jenom pro prostředky Azure. Pokud chcete odesílat metriky pro prostředky v jiných prostředích nebo v místním prostředí, použijte Application Insights.

Odesílání požadavků REST do ingestování vlastních metrik

Při odesílání vlastních metrik do služby Azure Monitor musí každý datový bod nebo hodnota hlášené v metrikách obsahovat následující informace.

Ověřovací token
Předmět
Oblast
Timestamp
Namespace
Název
Klíče dimenzí
Hodnoty dimenzí
Hodnoty metrik

Ověřování

K odeslání vlastních metrik do služby Azure Monitor potřebuje entita, která odesílá metriku, platný token Microsoft Entra v hlavičce nosného požadavku. Mezi podporované způsoby získání platného nosné tokenu patří:

Spravované identity pro prostředky Azure Spravovanou identitu můžete použít k udělení oprávnění k provádění určitých operací prostředků. Příkladem je povolení, aby prostředek mohl generovat metriky o sobě. Prostředek nebo jeho spravovaná identita může být udělena oprávnění vydavatele metrik monitorování u jiného prostředku. S tímto oprávněním může spravovaná identita také generovat metriky pro jiné prostředky.
Instanční objekt Microsoft Entra. V tomto scénáři může mít aplikace Nebo služba Microsoft Entra přiřazená oprávnění k generování metrik o prostředku Azure. K ověření požadavku Azure Monitor ověří token aplikace pomocí veřejných klíčů Microsoft Entra. Stávající role vydavatele metrik monitorování už má toto oprávnění. Je k dispozici na webu Azure Portal.

Instanční objekt může mít v závislosti na tom, pro jaké prostředky generuje vlastní metriky, roli Vydavatele metrik monitorování v požadovaném rozsahu. Příklady jsou předplatné, skupina prostředků nebo konkrétní prostředek.

Tip

Když požádáte o token Microsoft Entra, aby vygeneroval vlastní metriky, ujistěte se, že cílová skupina nebo prostředek, pro který je token požadován, je https://monitoring.azure.com/. Nezapomeňte uvést koncové lomítko.

Získání autorizačního tokenu

Jakmile vytvoříte spravovanou identitu nebo instanční objekt a přiřadíte oprávnění vydavatele metrik monitorování, můžete získat autorizační token. Při vyžádání tokenu zadejte resource: https://monitoring.azure.com.

Získejte ověřovací token pomocí některé z následujících metod:

Rozhraní příkazového řádku
REST API
Sada SDK

Při vyžádání tokenu musíte zadat resource parametr. Parametr resource je adresa URL prostředku, ke který chcete získat přístup.

Zdroje informací zahrnují:

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

Získání tokenu pomocí požadavku REST

K získání tokenu použijte následující volání rozhraní REST API. Tento požadavek používá k ověření požadavku ID klienta a tajný klíč klienta. ID klienta a tajný klíč klienta se získávají při registraci aplikace v Microsoft Entra ID. Další informace najdete v tématu Registrace aplikace k vyžádání autorizačních tokenů a práci s rozhraními 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'

Text odpovědi se zobrazí v následujícím formátu:

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

Získání tokenu pomocí Azure CLI

K získání tokenu pomocí rozhraní příkazového řádku můžete použít následující příkaz:

az account get-access-token

Další informace najdete v tématu az account get-access-token

Získání tokenu pomocí sad SDK

Následující ukázky kódu ukazují, jak získat token pomocí:

C#
NodeJS
Python

C#

Následující kód ukazuje, jak získat token pomocí Azure. Knihovna identit vyžaduje k ověření požadavku ID klienta a tajný klíč klienta.

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;

Případně můžete k získání tokenu použít třídu DefaultAzureCredential. Tato metoda k ověření požadavku používá výchozí přihlašovací údaje Azure a nevyžaduje ID klienta ani tajný klíč klienta.

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

Spravovanou identitu nebo přihlašovací údaje instančního objektu můžete zadat také takto:

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

Další informace naleznete v tématu DefaultAzureCredential – třída

Node.js

Informace o ověřování pomocí JavaScriptu a NodeJS najdete v tématu Ověřování javascriptových aplikací ve službách Azure pomocí sady Azure SDK pro JavaScript.

Následující kód ukazuje, jak získat token pomocí DefaultAzureCredential třídy. Tato metoda k ověření požadavku používá výchozí přihlašovací údaje Azure a nevyžaduje ID klienta ani tajný klíč klienta.

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

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

K získání přihlašovacích údajů můžete použít InteractiveBrowserCredential také třídu. Tato metoda poskytuje prostředí pro ověřování na základě prohlížeče pro uživatele, kteří se můžou ověřovat pomocí služeb Azure.

Další informace naleznete v tématu DefaultAzureCredential – třída a Třída InteractiveBrowserCredential

Případně můžete k získání tokenu použít třídu ClientSecretCredential. Tato metoda k ověření požadavku vyžaduje ID klienta a tajný klíč klienta.

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");

Další informace naleznete v tématu ClientSecretCredential – třída

Python

from azure.identity import DefaultAzureCredential

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

Další informace naleznete v tématu DefaultAzureCredential – třída a Třída InteractiveBrowserCredential

Případně můžete k získání tokenu použít třídu ClientSecretCredential. Tato metoda k ověření požadavku vyžaduje ID klienta a tajný klíč klienta.

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)

Další informace naleznete v tématu ClientSecretCredential – třída

Uložte přístupový token z odpovědi pro použití v následujících požadavcích HTTP.

Předmět

Vlastnost předmětu zaznamenává, pro které ID prostředku Azure se vlastní metrika hlásí. Tyto informace jsou kódovány v adrese URL volání rozhraní API. Každé rozhraní API může odesílat hodnoty metrik pouze pro jeden prostředek Azure.

Poznámka:

Nemůžete generovat vlastní metriky pro ID prostředku skupiny prostředků nebo předplatného.

Oblast

Vlastnost oblasti zachycuje oblast Azure, ve které se nasazuje prostředek, pro který generujete metriky. Metriky se musí generovat do stejného regionálního koncového bodu služby Azure Monitor jako oblast, ve které je prostředek nasazený. Například vlastní metriky pro virtuální počítač nasazený v oblasti USA – západ musí být odeslány do koncového bodu služby Azure Monitor v oblasti USA – západ. Informace o oblasti jsou také kódovány v adrese URL volání rozhraní API.

Časové razítko

Každý datový bod odeslaný do služby Azure Monitor musí být označen časovým razítkem. Toto časové razítko zachycuje datum a čas, kdy se hodnota metriky měří nebo shromažďuje. Azure Monitor přijímá data metrik s časovými razítky do 20 minut za posledních a 5 minut v budoucnu. Časové razítko musí být ve formátu ISO 8601.

Obor názvů

Obory názvů představují způsob, jak kategorizovat nebo seskupit podobné metriky. Pomocíoborůch Můžete mít například obor názvů s názvem contosomemorymetrics, který sleduje metriky využití paměti, které profilují vaši aplikaci. Jiný obor názvů s názvem contosoapptransaction může sledovat všechny metriky o uživatelských transakcích ve vaší aplikaci.

Název

Vlastnost name je název metriky, která se hlásí. Název je obvykle dostatečně popisný, aby vám pomohl zjistit, co se měří. Příkladem je metrika, která měří počet bajtů paměti používaných na virtuálním počítači. Může mít název metriky, jako jsou bajty paměti, které se používají.

Klíče dimenzí

Dimenze je pár klíč/hodnota, který pomáhá popsat další charakteristiky metriky, která se shromažďuje. Pomocí dalších charakteristik můžete shromáždit další informace o metrice, což umožňuje podrobnější přehledy.

Metrika Využití bajtů paměti může mít například klíč dimenze s názvem Proces , který zachycuje, kolik bajtů paměti každý proces na virtuálním počítači spotřebuje. Pomocí tohoto klíče můžete metriku filtrovat, abyste viděli, kolik procesů specifických pro paměť používá, nebo abyste identifikovali prvních pět procesů podle využití paměti.

Dimenze jsou volitelné a ne všechny metriky mají dimenze. Vlastní metrika může mít až 10 dimenzí.

Hodnoty dimenzí

Když hlásíte datový bod metriky, pro každý klíč dimenze na hlášené metrice existuje odpovídající hodnota dimenze. Můžete například chtít nahlásit paměť, kterou ContosoApp používá na vašem virtuálním počítači:

Název metriky by byl využitý bajty paměti.
Klíč dimenze by byl Proces.
Hodnota dimenze by byla ContosoApp.exe.

Při publikování hodnoty metriky můžete zadat pouze jednu hodnotu dimenze na klíč dimenze. Pokud na virtuálním počítači shromáždíte stejné využití paměti pro více procesů, můžete pro toto časové razítko hlásit více hodnot metrik. Každá hodnota metriky by pro klíč dimenze procesu určila jinou hodnotu dimenze.

I když jsou dimenze volitelné, pokud příspěvek metriky definuje klíče dimenzí, jsou odpovídající hodnoty dimenzí povinné.

Hodnoty metriky

Azure Monitor ukládá všechny metriky v 1minutových intervalech členitosti. Během dané minuty může být potřeba metriku několikrát vzorkovat. Například podle využití procesoru. Nebo se může vyžadovat měření metriky u mnoha diskrétních událostí, jako jsou latence transakcí přihlašování.

Pokud chcete omezit počet nezpracovaných hodnot, které musíte generovat a platit ve službě Azure Monitor, místně předaggujte a vygenerujte agregované hodnoty:

Min: Minimální pozorovaná hodnota ze všech vzorků a měření během minuty.
Max: Maximální pozorovaná hodnota ze všech vzorků a měření během minuty.
Součet: Součet všech pozorovaných hodnot ze všech vzorků a měření během minuty.
Počet: Počet vzorků a měření provedených během minuty.

Poznámka:

Azure Monitor nepodporuje definování jednotek pro vlastní metriku.

Pokud například během minuty došlo k čtyř transakcím přihlašování do vaší aplikace, může být výsledná měřená latence pro každou z těchto transakcí:

Transakce 1	Transakce 2	Transakce 3	Transakce 4
7 ms	4 ms	13 ms	16 ms

Výsledná publikace metriky pro Azure Monitor by pak byla:

Min: 4
Max: 16
Součet: 40
Počet: 4

Pokud vaše aplikace nemůže předem oddělit místně a potřebuje vygenerovat každou diskrétní ukázku nebo událost okamžitě po kolekci, můžete vygenerovat nezpracované hodnoty měr. Například při každé transakci přihlášení ve vaší aplikaci publikujete metriku do služby Azure Monitor pouze s jedním měřením. V případě přihlašovací transakce, která trvala 12 milisekund, by publikace metriky byla:

Min: 12
Max: 12
Součet: 12
Počet: 1

V tomto procesu můžete během dané minuty vygenerovat více hodnot pro stejnou kombinaci metrik/dimenzí. Azure Monitor pak vezme všechny nezpracované hodnoty vygenerované za danou minutu a agreguje je.

Ukázková vlastní publikace metrik

V následujícím příkladu vytvořte vlastní metriku nazvanou Bajty paměti, které se používají v rámci profilu paměti oboru názvů metriky pro virtuální počítač. Metrika má jednu dimenzi s názvem Proces. Pro časové razítko se hodnoty metrik vygenerují pro dva procesy.

Do souboru s názvem custommetric.json na místním počítači uložte následující KÓD JSON. Aktualizujte parametr času tak, aby byl během posledních 20 minut. Metriku nemůžete umístit do úložiště, které je starší než 20 minut.

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

Pomocí následujících proměnných odešlete následující požadavek HTTP POST:

location: Oblast nasazení prostředku, pro který generujete metriky.
resourceId: ID prostředku Azure, se kterou metriku sledujete.

accessToken: Autorizační token získaný z kroku Získání autorizačního tokenu .

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

Zobrazení metrik

Přihlaste se k portálu Azure.
V nabídce vlevo vyberte Sledovat.
Na stránce Monitorování vyberte Metriky.
Změňte agregační období na poslední hodinu.
V rozevíracím seznamu Obor vyberte prostředek, pro který odešlete metriku.
V rozevíracím seznamu Metrika Namespace vyberte Profil paměti.
V rozevíracím seznamu Metriky vyberte v části Použít bajty paměti.

Řešení problému

Pokud se zobrazí chybová zpráva s určitou částí procesu, zvažte následující informace o řešení potíží:

Pokud nemůžete vydávat metriky pro předplatné nebo skupinu prostředků nebo prostředek, zkontrolujte, jestli má vaše aplikace nebo instanční objekt přiřazenou roli Vydavatele metrik monitorování v řízení přístupu (IAM).
Zkontrolujte, jestli počet názvů dimenzí odpovídá počtu hodnot.
Zkontrolujte, že generujete metriky do správného regionálního koncového bodu služby Azure Monitor. Pokud je například váš prostředek nasazený v oblasti USA – západ, musíte generovat metriky do regionálního koncového bodu USA – západ.
Zkontrolujte, jestli časové razítko spadá do posledních 20 minut.
Zkontrolujte, jestli časové razítko je ve formátu ISO 8601.
Zkontrolujte, jestli je název metriky platný. Například nemůže obsahovat mezery.

Další kroky

Přečtěte si další informace o vlastních metrikách.

Sdílet prostřednictvím

Ingestování vlastních metrik pro prostředek Azure pomocí rozhraní REST API

Odesílání požadavků REST do ingestování vlastních metrik

Ověřování

Získání autorizačního tokenu

Získání tokenu pomocí požadavku REST

Získání tokenu pomocí Azure CLI

Získání tokenu pomocí sad SDK

C#

Node.js

Python

Předmět

Oblast

Časové razítko

Obor názvů

Název

Klíče dimenzí

Hodnoty dimenzí

Hodnoty metriky

Ukázková vlastní publikace metrik

Zobrazení metrik

Řešení problému

Další kroky

Váš názor

Další materiály