Udostępnij za pośrednictwem

Pozyskiwanie metryk niestandardowych dla zasobu platformy Azure przy użyciu interfejsu API REST

  • Artykuł

W tym artykule pokazano, jak wysyłać metryki niestandardowe dla zasobów platformy Azure do magazynu metryk usługi Azure Monitor za pośrednictwem interfejsu API REST. Gdy metryki znajdują się w usłudze Azure Monitor, możesz wykonać wszystkie czynności z nimi, które wykonujesz za pomocą standardowych metryk. Można na przykład generować wykresy i alerty oraz kierować metryki do innych narzędzi zewnętrznych.

Uwaga

Interfejs API REST zezwala tylko na wysyłanie metryk niestandardowych dla zasobów platformy Azure. Aby wysyłać metryki dla zasobów w innych środowiskach lub lokalnie, użyj usługi Application Insights.

Wysyłanie żądań REST do pozyskiwania metryk niestandardowych

W przypadku wysyłania metryk niestandardowych do usługi Azure Monitor każdy punkt danych lub wartość zgłaszana w metrykach musi zawierać następujące informacje.

Uwierzytelnianie

Aby przesłać metryki niestandardowe do usługi Azure Monitor, jednostka przesyłana przez metrykę wymaga prawidłowego tokenu Microsoft Entra w nagłówku elementu nośnego żądania. Obsługiwane sposoby uzyskiwania prawidłowego tokenu elementu nośnego obejmują:

  • Tożsamości zarządzane dla zasobów platformy Azure. Tożsamość zarządzana umożliwia nadanie zasobom uprawnień do wykonywania określonych operacji. Przykładem jest umożliwienie zasobowi emitowania metryk dotyczących siebie. Zasób lub tożsamość zarządzana mogą mieć uprawnienia Wydawca metryk monitorowania w innym zasobie. Przy użyciu tego uprawnienia tożsamość zarządzana może również emitować metryki dla innych zasobów.

  • Jednostka usługi Microsoft Entra. W tym scenariuszu aplikację lub usługę Firmy Microsoft można przypisać uprawnienia do emitowania metryk dotyczących zasobu platformy Azure. Aby uwierzytelnić żądanie, usługa Azure Monitor weryfikuje token aplikacji przy użyciu kluczy publicznych firmy Microsoft Entra. Istniejąca rola wydawcy metryk monitorowania ma już to uprawnienie. Jest ona dostępna w witrynie Azure Portal.

    Jednostka usługi, w zależności od zasobów, dla których emituje metryki niestandardowe, może mieć rolę Wydawca metryk monitorowania w wymaganym zakresie. Przykłady to subskrypcja, grupa zasobów lub określony zasób.

Napiwek

Gdy zażądasz tokenu entra firmy Microsoft w celu emitowania metryk niestandardowych, upewnij się, że odbiorcy lub zasób, dla którego żądano tokenu, to https://monitoring.azure.com/. Pamiętaj, aby uwzględnić końcowy ukośnik.

Uzyskiwanie tokenu autoryzacji

Po utworzeniu tożsamości zarządzanej lub jednostki usługi i przypisaniu uprawnień wydawcy metryk monitorowania można uzyskać token autoryzacji. Podczas żądania tokenu określ wartość resource: https://monitoring.azure.com.

Pobierz token uwierzytelniania przy użyciu dowolnej z następujących metod:

  • Interfejs wiersza polecenia
  • Interfejs API REST
  • SDK

Podczas żądania tokenu należy podać resource parametr. Parametr resource jest adresem URL zasobu, do którego chcesz uzyskać dostęp.

Dostępne są m.in. następujące zasoby:

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

Uzyskiwanie tokenu przy użyciu żądania REST

Użyj następującego wywołania interfejsu API REST, aby uzyskać token. To żądanie używa identyfikatora klienta i klucza tajnego klienta do uwierzytelniania żądania. Identyfikator klienta i klucz tajny klienta są uzyskiwane podczas rejestrowania aplikacji przy użyciu identyfikatora Entra firmy Microsoft. Aby uzyskać więcej informacji, zobacz Rejestrowanie aplikacji w celu żądania tokenów autoryzacji i pracy z interfejsami 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'

Treść odpowiedzi jest wyświetlana w następującym formacie:

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

Zapisz token dostępu z odpowiedzi na potrzeby użycia w następujących żądaniach HTTP.

Temat

Właściwość tematu przechwytuje identyfikator zasobu platformy Azure, dla którego jest zgłaszana metryka niestandardowa. Te informacje są kodowane w adresie URL wywołania interfejsu API. Każdy interfejs API może przesyłać wartości metryk tylko dla pojedynczego zasobu platformy Azure.

Uwaga

Nie można emitować metryk niestandardowych względem identyfikatora zasobu grupy zasobów lub subskrypcji.

Region (Region)

Właściwość region przechwytuje region świadczenia usługi Azure, w którym wdrożono zasób emitujący metryki. Metryki muszą być emitowane do tego samego regionalnego punktu końcowego usługi Azure Monitor co region, w którym wdrożono zasób. Na przykład metryki niestandardowe maszyny wirtualnej wdrożonej w regionie Zachodnie stany USA muszą być wysyłane do regionalnego punktu końcowego usługi Azure Monitor w regionie WestUS. Informacje o regionie są również kodowane w adresie URL wywołania interfejsu API.

Sygnatura czasowa

Każdy punkt danych wysyłany do usługi Azure Monitor musi być oznaczony znacznikiem czasu. Ten znacznik czasu przechwytuje datę i godzinę, w której wartość metryki jest mierzona lub zbierana. Usługa Azure Monitor akceptuje dane metryk ze znacznikami czasu do 20 minut w ciągu ostatnich i 5 minut w przyszłości. Znacznik czasu musi mieć format ISO 8601.

Przestrzeń nazw

Przestrzenie nazw to sposób kategoryzowania lub grupowania podobnych metryk. Korzystając z przestrzeni nazw, można uzyskać izolację między grupami metryk, które mogą zbierać różne szczegółowe informacje lub wskaźniki wydajności. Na przykład może istnieć przestrzeń nazw o nazwie contosomemorymetrics , która śledzi metryki użycia pamięci, które profiluje aplikację. Inna przestrzeń nazw o nazwie contosoapptransaction może śledzić wszystkie metryki dotyczące transakcji użytkowników w aplikacji.

Nazwisko

Właściwość name jest nazwą zgłaszanej metryki. Zazwyczaj nazwa jest wystarczająco opisowa, aby ułatwić zidentyfikowanie mierzonych danych. Przykładem jest metryka, która mierzy liczbę bajtów pamięci używanych na maszynie wirtualnej. Może mieć nazwę metryki, taką jak Bajty pamięci w użyciu.

Klucze wymiarów

Wymiar to para klucz/wartość, która pomaga opisać inne cechy metryki, która jest zbierana. Korzystając z innych cech, możesz zebrać więcej informacji na temat metryki, co pozwala uzyskać bardziej szczegółowe informacje.

Na przykład metryka Użycie bajtów pamięci może mieć klucz wymiaru o nazwie Proces , który przechwytuje, ile bajtów pamięci zużywa każdy proces na maszynie wirtualnej. Za pomocą tego klucza można filtrować metrykę, aby zobaczyć, ile procesów specyficznych dla pamięci używa lub zidentyfikować pięć najważniejszych procesów według użycia pamięci.

Wymiary są opcjonalne, a nie wszystkie metryki mają wymiary. Metryka niestandardowa może mieć maksymalnie 10 wymiarów.

Wartości wymiarów

W przypadku raportowania punktu danych metryk dla każdego klucza wymiaru w zgłoszonej metryce istnieje odpowiednia wartość wymiaru. Możesz na przykład zgłosić pamięć używaną przez aplikację ContosoApp na maszynie wirtualnej:

  • Nazwa metryki to Memory Bytes in Use (Użycie bajtów pamięci).
  • Kluczem wymiaru będzie Proces.
  • Wartość wymiaru będzie ContosoApp.exe.

Podczas publikowania wartości metryki można określić tylko jedną wartość wymiaru na klucz wymiaru. Jeśli zbierzesz to samo wykorzystanie pamięci dla wielu procesów na maszynie wirtualnej, możesz zgłosić wiele wartości metryk dla tego znacznika czasu. Każda wartość metryki określa inną wartość wymiaru dla klucza wymiaru procesu .

Mimo że wymiary są opcjonalne, jeśli wpis metryki definiuje klucze wymiarów, odpowiednie wartości wymiarów są obowiązkowe.

Wartości metryk

Usługa Azure Monitor przechowuje wszystkie metryki w 1-minutowych interwałach szczegółowości. W ciągu danej minuty metryka może być kilka razy próbkowana. Na przykład na podstawie użycia procesora CPU. Może też być konieczne zmierzenie metryki dla wielu odrębnych zdarzeń, takich jak opóźnienia transakcji logowania.

Aby ograniczyć liczbę nieprzetworzonych wartości, które należy emitować i płacić za usługę Azure Monitor, lokalnie wstępnie zagregowane i emitować zagregowane wartości:

  • Min: minimalna obserwowana wartość ze wszystkich próbek i pomiarów w ciągu minuty.
  • Maksymalna: maksymalna obserwowana wartość ze wszystkich próbek i pomiarów w ciągu minuty.
  • Suma: Suma wszystkich obserwowanych wartości ze wszystkich próbek i pomiarów w ciągu minuty.
  • Liczba: liczba próbek i pomiarów wykonanych w ciągu minuty.

Uwaga

Usługa Azure Monitor nie obsługuje definiowania jednostek dla metryki niestandardowej.

Jeśli na przykład w aplikacji w ciągu minuty istniały cztery transakcje logowania, wynikowe zmierzone opóźnienia dla każdej z nich mogą być następujące:

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

Następnie wynikowa publikacja metryk w usłudze Azure Monitor będzie:

  • Min: 4
  • Maksymalna: 16
  • Suma: 40
  • Liczba: 4

Jeśli aplikacja nie może wstępnie zreagować lokalnie i musi emitować każdy dyskretny przykład lub zdarzenie natychmiast po kolekcji, możesz emitować nieprzetworzone wartości miary. Na przykład za każdym razem, gdy transakcja logowania odbywa się w aplikacji, publikujesz metrykę w usłudze Azure Monitor z tylko jedną miarą. Dlatego w przypadku transakcji logowania, która miała 12 milisekund, publikacja metryki będzie:

  • Min: 12
  • Maksymalna: 12
  • Suma: 12
  • Liczba: 1

Dzięki temu procesowi można emitować wiele wartości dla tej samej kombinacji metryki/wymiaru w danej minucie. Usługa Azure Monitor pobiera następnie wszystkie nieprzetworzone wartości emitowane przez daną minutę i agreguje je.

Przykładowa niestandardowa publikacja metryk

W poniższym przykładzie utwórz niestandardową metrykę o nazwie Bajty pamięci w obszarze Użyj w obszarze profilu pamięci przestrzeni nazw metryki dla maszyny wirtualnej. Metryka ma jeden wymiar o nazwie Proces. Dla znacznika czasu wartości metryk są emitowane dla dwóch procesów.

Zapisz następujący kod JSON w pliku o nazwie custommetric.json na komputerze lokalnym. Zaktualizuj parametr time, aby był w ciągu ostatnich 20 minut. Nie można umieścić metryki w magazynie, który ma więcej niż 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
          }
        ]
      }
    }
  }

Prześlij następujące żądanie HTTP POST przy użyciu następujących zmiennych:

  • location: Region wdrażania zasobu, dla którego emitujesz metryki.

  • resourceId: identyfikator zasobu platformy Azure, względem którego śledzisz metryki.

  • accessToken: token autoryzacji uzyskany w kroku Uzyskiwanie tokenu autoryzacji.

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

Wyświetlanie metryk

  1. Zaloguj się w witrynie Azure Portal.

  2. W menu po lewej stronie wybierz pozycję Monitor.

  3. Na stronie Monitorowanie wybierz pozycję Metryki.

    Zrzut ekranu przedstawiający sposób wybierania metryk w witrynie Azure Portal.

  4. Zmień okres agregacji na Last hour.

  5. Z listy rozwijanej Zakres wybierz zasób, dla którego zostanie wysłana metryka.

  6. Z listy rozwijanej Przestrzeń nazw metryk wybierz pozycję Profil pamięci.

  7. Z listy rozwijanej Metryka wybierz pozycję Bajty pamięci w obszarze Użyj.

Rozwiązywanie problemów

Jeśli zostanie wyświetlony komunikat o błędzie z częścią procesu, rozważ następujące informacje dotyczące rozwiązywania problemów:

  • Jeśli nie możesz wydać metryk dla subskrypcji lub grupy zasobów lub zasobu, sprawdź, czy aplikacja lub jednostka usługi ma przypisaną rolę Wydawca metryk monitorowania przypisanych do kontroli dostępu (IAM).
  • Sprawdź, czy liczba nazw wymiarów jest zgodna z liczbą wartości.
  • Sprawdź, czy emitujesz metryki do poprawnego regionalnego punktu końcowego usługi Azure Monitor. Jeśli na przykład zasób jest wdrożony w regionie Zachodnie stany USA, musisz emitować metryki do regionalnego punktu końcowego Zachodnie stany USA.
  • Sprawdź, czy znacznik czasu mieści się w ciągu ostatnich 20 minut.
  • Sprawdź, czy znacznik czasu jest w formacie ISO 8601.
  • Sprawdź, czy nazwa metryki jest prawidłowa. Na przykład nie może zawierać spacji.

Następne kroki

Dowiedz się więcej o metrykach niestandardowych.