Udostępnij za pośrednictwem

Wykonywanie zapytań względem metryk rozwiązania Prometheus przy użyciu interfejsu API i biblioteki PromQL

  • Artykuł

Usługa zarządzana usługi Azure Monitor dla rozwiązania Prometheus zbiera metryki z klastrów usługi Azure Kubernetes i przechowuje je w obszarze roboczym usługi Azure Monitor. PromQL (język zapytań Prometheus) to funkcjonalny język zapytań, który umożliwia wykonywanie zapytań i agregowanie danych szeregów czasowych. Użyj biblioteki PromQL, aby wykonywać zapytania i agregować metryki przechowywane w obszarze roboczym usługi Azure Monitor.

W tym artykule opisano sposób wykonywania zapytań dotyczących obszaru roboczego usługi Azure Monitor przy użyciu protokołu PromQL za pośrednictwem interfejsu API REST. Aby uzyskać więcej informacji na temat rozwiązania PromQL, zobacz Artykuł Tworzenie zapytań prometheus.

Wymagania wstępne

Aby wykonać zapytanie dotyczące obszaru roboczego usługi Azure Monitor przy użyciu rozwiązania PromQL, potrzebne są następujące wymagania wstępne:

  • Klaster usługi Azure Kubernetes lub zdalny klaster Kubernetes.
  • Zarządzana usługa Azure Monitor dla metryk złomowania rozwiązania Prometheus z klastra Kubernetes.
  • Obszar roboczy usługi Azure Monitor, w którym są przechowywane metryki rozwiązania Prometheus.

Uwierzytelnianie

Aby wysłać zapytanie do obszaru roboczego usługi Azure Monitor, uwierzytelnij się przy użyciu identyfikatora Entra firmy Microsoft. Interfejs API obsługuje uwierzytelnianie firmy Microsoft Entra przy użyciu poświadczeń klienta. Zarejestruj aplikację kliencką przy użyciu identyfikatora Entra firmy Microsoft i zażądaj tokenu.

Aby skonfigurować uwierzytelnianie firmy Microsoft Entra, wykonaj poniższe kroki:

  1. Zarejestruj aplikację przy użyciu identyfikatora Entra firmy Microsoft.
  2. Udziel dostępu aplikacji do obszaru roboczego usługi Azure Monitor.
  3. Zażądaj tokenu.

Rejestrowanie aplikacji przy użyciu identyfikatora Entra firmy Microsoft

  1. Aby zarejestrować aplikację, wykonaj kroki opisane w temacie Rejestrowanie aplikacji w celu żądania tokenów autoryzacji i pracy z interfejsami API

Zezwalanie aplikacji na dostęp do obszaru roboczego

Przypisz rolę Czytelnik danych monitorowania aplikację, aby mogła wysyłać zapytania o dane z obszaru roboczego usługi Azure Monitor.

  1. Otwórz obszar roboczy usługi Azure Monitor w witrynie Azure Portal.

  2. Na stronie Przegląd zanotuj punkt końcowy zapytania do użycia w żądaniu REST.

  3. Wybierz pozycję Kontrola dostępu (IAM).

  4. Wybierz pozycję Dodaj, a następnie dodaj przypisanie roli na stronie Kontrola dostępu (Zarządzanie dostępem i tożsamościami).

    Zrzut ekranu przedstawiający stronę przeglądu obszaru roboczego usługi Azure Monitor.

  5. Na stronie Dodawanie przypisania roli wyszukaj pozycję Monitorowanie.

  6. Wybierz pozycję Czytelnik danych monitorowania, a następnie wybierz kartę Członkowie.

    Zrzut ekranu przedstawiający stronę Dodawanie przypisania roli.

  7. Wybierz pozycję Wybierz członków.

  8. Wyszukaj zarejestrowaną aplikację i wybierz ją.

  9. Naciśnij przycisk Wybierz.

  10. Wybierz Przejrzyj + przypisz.

    Zrzut ekranu przedstawiający stronę Dodawanie przypisania roli i wybieranie członków.

Utworzono rejestrację aplikacji i przypisano jej dostęp do zapytań dotyczących danych z obszaru roboczego usługi Azure Monitor. Teraz możesz wygenerować token i użyć go w zapytaniu.

Żądanie tokenu

Wyślij następujące żądanie w wierszu polecenia lub przy użyciu klienta, takiego jak Bezsenność lub Wywołanie RestMethod programu PowerShell

curl -X POST 'https://login.microsoftonline.com/<tenant 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://prometheus.monitor.azure.com'

Przykładowa treść odpowiedzi:

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https:/prometheus.monitor.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

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

Punkt końcowy zapytania

Znajdź punkt końcowy zapytania obszaru roboczego usługi Azure Monitor na stronie przeglądu obszaru roboczego usługi Azure Monitor.

Zrzut ekranu przedstawiający punkt końcowy zapytania na stronie przeglądu obszaru roboczego usługi Azure Monitor.

Obsługiwane interfejsy API

Obsługiwane są następujące zapytania:

Natychmiastowe zapytania

Aby uzyskać więcej informacji, zobacz Natychmiastowe zapytania

Ścieżka: /api/v1/query
Przykłady:

POST https://k8s-02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query  
--header 'Authorization:  Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=sum( \
    container_memory_working_set_bytes \
    * on(namespace,pod) \
    group_left(workload, workload_type) \
    namespace_workload_pod:kube_pod_owner:relabel{ workload_type="deployment"}) by (pod)'


GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query?query=container_memory_working_set_bytes' 
--header 'Authorization:  Bearer <access token>'

Zapytania zakresu

Aby uzyskać więcej informacji, zobacz Zakres zapytań
Ścieżka: /api/v1/query_range
Przykłady:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range?query=container_memory_working_set_bytes&start=2023-03-01T00:00:00.000Z&end=2023-03-20T00:00:00.000Z&step=6h'
--header 'Authorization: Bearer <access token>

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range' 
--header 'Authorization:  Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=up' 
--data-urlencode 'start=2023-03-01T20:10:30.781Z' 
--data-urlencode 'end=2023-03-20T20:10:30.781Z' 
--data-urlencode 'step=6h'

Seria

Aby uzyskać więcej informacji, zobacz Seria

Ścieżka: /api/v1/series
Przykłady:

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series' 
--header 'Authorization: Bearer <access token>
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'match[]=kube_pod_info{pod="bestapp-123abc456d-4nmfm"}'


GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series?match[]=container_network_receive_bytes_total{namespace="default-1669648428598"}'

Etykiety

Aby uzyskać więcej informacji, zobacz Ścieżka etykiet : /api/v1/labels
Przykłady:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'


POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

Wartości etykiet

Aby uzyskać więcej informacji, zobacz Etykiety wartości
Ścieżka: /api/v1/label/__name__/values.

Uwaga

__name__ jest jedyną obsługiwaną wersją tego interfejsu API i zwraca wszystkie nazwy metryk. Nie są obsługiwane żadne inne /api/v1/label/<label_name>/values.

Przykład:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/label/__name__/values'

Aby uzyskać pełną specyfikację interfejsów API promowych systemu operacyjnego, zobacz Prometheus HTTP API ( Prometheus HTTP API).

Ograniczenia interfejsu API

Poniższe ograniczenia są dodatkiem do tych opisanych w specyfikacji Prometheus.

  • Zapytanie musi być ograniczone do metryki
    Każde zapytanie pobierania szeregów czasowych (/seria lub /query lub /query_range) musi zawierać dopasowanie etykiet __name__. Oznacza to, że każde zapytanie musi być ograniczone do metryki. W zapytaniu może istnieć tylko jeden __name__ matcher etykiet.
  • Kwerenda /series nie obsługuje filtru wyrażeń regularnych
  • Obsługiwany zakres czasu
    • Interfejs API /query_range obsługuje zakres czasu 32 dni. Jest to maksymalny dozwolony zakres czasu, w tym selektory zakresu określone w samym zapytaniu. Na przykład zapytanie rate(http_requests_total[1h] z ostatnich 24 godzin oznaczałoby, że dane są odpytywane przez 25 godzin. Jest to zakres 24-godzinny oraz 1 godzina określona w zapytaniu.
    • /series API pobiera dane dla maksymalnie 12-godzinnego zakresu czasu. Jeśli endTime nie zostanie podana, endTime = time.now(). Jeśli wściekłość czasu jest większa niż 12 godzin, startTime ustawiono wartość endTime – 12h
  • Ignorowany zakres czasu
    Czas rozpoczęcia i godzina zakończenia dostarczana z elementem /labels i /label/__name__/values są ignorowane, a wszystkie przechowywane dane w obszarze roboczym usługi Azure Monitor są odpytywane.
  • Funkcje eksperymentalne
    Funkcje eksperymentalne, takie jak przykładowe, nie są obsługiwane.

Aby uzyskać więcej informacji na temat limitów metryk rozwiązania Prometheus, zobacz Metryki rozwiązania Prometheus

Uwzględnij wielkość liter

Usługa zarządzana usługi Azure Monitor dla rozwiązania Prometheus jest systemem bez uwzględniania wielkości liter. Traktuje ciągi (takie jak nazwy metryk, nazwy etykiet lub wartości etykiet) jako szeregi czasowe, jeśli różnią się one od innej serii czasowej tylko przez przypadek ciągu.

Uwaga

To zachowanie różni się od natywnego rozwiązania Prometheus typu open source, czyli systemu z uwzględnieniem wielkości liter. Wystąpienia rozwiązania Prometheus zarządzane samodzielnie działające na maszynach wirtualnych platformy Azure, zestawach skalowania maszyn wirtualnych lub klastrach usługi Azure Kubernetes Service są systemami uwzględniającymi wielkość liter.

W usłudze zarządzanej dla rozwiązania Prometheus następujące szeregi czasowe są traktowane tak samo:

diskSize(cluster="eastus", node="node1", filesystem="usr_mnt")
diskSize(cluster="eastus", node="node1", filesystem="usr_MNT")

Powyższe przykłady to pojedynczy szereg czasowy w bazie danych szeregów czasowych. Obowiązują następujące zastrzeżenia:

  • Wszystkie próbki pozyskane względem nich są przechowywane tak, jakby zostały zeskropane lub pozyskane względem pojedynczego szeregu czasowego.
  • Jeśli powyższe przykłady są pozyskiwane przy użyciu tej samej sygnatury czasowej, jeden z nich jest losowo porzucony.
  • Wielkość liter przechowywana w bazie danych szeregów czasowych i zwracana przez zapytanie jest nieprzewidywalna. Ten sam szereg czasowy może zwracać różne wielkości liter w różnych godzinach.
  • Każda nazwa metryki lub element matcher etykiety/wartości znajdujący się w zapytaniu jest pobierany z bazy danych szeregów czasowych za pomocą porównania bez uwzględniania wielkości liter. Jeśli w zapytaniu jest rozróżniana wielkość liter, jest ona automatycznie traktowana jako element matcher bez uwzględniania wielkości liter w porównaniach ciągów.

Najlepszym rozwiązaniem jest użycie pojedynczego spójnego przypadku do produkcji lub złomowania szeregów czasowych.

Rozwiązanie Prometheus typu open source traktuje powyższe przykłady jako dwa różne szeregi czasowe. Wszystkie próbki zeskrobowane lub pozyskane na nie są przechowywane oddzielnie.

Często zadawane pytania

Ta sekcja zawiera odpowiedzi na typowe pytania.

Brakuje wszystkich lub niektórych moich metryk. Jak mogę rozwiązać problemy?

Przewodnik rozwiązywania problemów umożliwia pozyskiwanie metryk rozwiązania Prometheus z zarządzanego agenta tutaj.

Dlaczego brakuje metryk, które mają dwie etykiety o tej samej nazwie, ale innej wielkości liter?

Rozwiązanie Prometheus zarządzane przez platformę Azure jest systemem bez uwzględniania wielkości liter. Traktuje ciągi, takie jak nazwy metryk, nazwy etykiet lub wartości etykiet, jako identyczne szeregi czasowe, jeśli różnią się one od innych szeregów czasowych tylko wielkością lister w ciągu. Aby uzyskać więcej informacji, zobacz Omówienie metryk rozwiązania Prometheus.

Widzę pewne luki w danych metryk, dlaczego tak się dzieje?

Podczas aktualizacji węzła może zostać wyświetlona 1-minutowa luka w danych metryk zebranych z naszych modułów zbierających na poziomie klastra. Ta luka występuje, ponieważ węzeł, w ramach którego są uruchamiane dane, jest aktualizowany w ramach normalnego procesu aktualizacji. Ten proces aktualizacji ma wpływ na cele w całym klastrze, takie jak kube-state-metrics i niestandardowe obiekty docelowe aplikacji, które zostały określone. Dzieje się tak, gdy klaster jest aktualizowany ręcznie lub za pośrednictwem autoaktualizacji. To zachowanie jest oczekiwane i występuje z powodu aktualizacji węzła, w którym pojawia się ta luka. To zachowanie nie ma wpływu na żadne z naszych zalecanych reguł alertów.

Następne kroki

Omówienie obszaru roboczego usługi Azure Monitor
Zarządzanie obszarem roboczym usługi Azure Monitor
Omówienie usługi zarządzanej usługi Azure Monitor dla rozwiązania Prometheus
Wykonywanie zapytań o metryki prometheus przy użyciu skoroszytów platformy Azure