Udostępnij za pośrednictwem

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

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 / Notatka

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, podmiot przesyłający metrykę wymaga prawidłowego tokenu Microsoft Entra w nagłówku Bearer żą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.

  • Główny element usługi Microsoft Entra. W tym scenariuszu aplikacja lub usługa Microsoft Entra może mieć przypisane 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 Monitoring Metrics Publisher ma już to uprawnienie. Jest ona dostępna w witrynie Azure Portal.

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

Wskazówka

Gdy zażądasz tokenu Microsoft Entra w celu emitowania metryk niestandardowych, upewnij się, że odbiorca 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.

Uzyskaj token uwierzytelniający, korzystając z jednej z następujących metod:

  • Interfejs Linii Komend (CLI)
  • Interfejs programistyczny REST
  • Zestaw do tworzenia oprogramowania

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

Zasoby obejmują:

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

Uzyskaj token za pomocą żądania REST

Użyj poniższego wywołania REST API, aby uzyskać token. To żądanie używa identyfikatora klienta i tajnego hasła klienta do uwierzytelnienia żądania. Identyfikator klienta i tajny kod klienta są uzyskiwane podczas rejestracji aplikacji w Microsoft Entra ID. Aby uzyskać więcej informacji, zobacz Rejestracja aplikacji w celu żądania tokenów autoryzacyjnych 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 pojawia się 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ść odpowiedzialna za przechwytywanie identyfikatora zasobu platformy Azure, dla której zgłaszana jest 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 / Notatka

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

Rejon

Właściwość region przechwytuje region Azure, w którym wdrożono zasób, dla którego emitowane są 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 Zachodnich USA muszą być wysyłane do punktu końcowego Azure Monitor w 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 przeszłości i do 5 minut w przyszłości. Znacznik czasu musi mieć format ISO 8601.

Namespace

Przestrzenie nazw są sposobem na kategoryzowanie lub grupowanie podobnych metryk razem. 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.

Nazwa

Nazwa właściwości to nazwa metryki, która jest zgłaszana. 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 zbieranej metryki. 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 określa, ile bajtów pamięci zużywa każdy proces na maszynie wirtualnej (VM). 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).
  • Klucz wymiaru to 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ść dla klucza wymiaru Procese.

Mimo że wymiary są opcjonalne, jeśli we wpisie metryki zdefiniowane są klucze wymiarów, wtedy odpowiednie wartości wymiarów stają się 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. Przykładem jest użycie procesora. 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 musisz emitować i za które płacisz w usłudze Azure Monitor, lokalnie wstępnie agreguj i emituj wartości zagregowane.

  • 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 / Notatka

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 agregować lokalnie i musi emitować każdą dyskretną próbkę lub zdarzenie natychmiast po zebraniu, możesz wypuszczać 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 publikacja niestandardowych metryk

W poniższym przykładzie utwórz niestandardową metrykę o nazwie Bajty pamięci w użyciu w przestrzeni nazw metryki Profil pamięci 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 czasu, aby był w ciągu ostatnich 20 minut. Nie można dodać metryki do magazynu, jeśli ma ona 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ę do witryny 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 Bajty pamięci w użyciu.

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 Zachodnim USA, musisz wysyłać metryki do regionalnego punktu końcowego Zachodniego 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.

Dalsze kroki

Dowiedz się więcej o metrykach niestandardowych.