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

Artykuł
03/05/2024

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:

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

Rejestrowanie aplikacji przy użyciu identyfikatora Entra firmy Microsoft

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.

Otwórz obszar roboczy usługi Azure Monitor w witrynie Azure Portal.
Na stronie Przegląd zanotuj punkt końcowy zapytania do użycia w żądaniu REST.
Wybierz pozycję Kontrola dostępu (IAM) .
Wybierz pozycję Dodaj, a następnie dodaj przypisanie roli na stronie Kontrola dostępu (Zarządzanie dostępem i tożsamościami).
Na stronie Dodawanie przypisania roli wyszukaj pozycję Monitorowanie.
Wybierz pozycję Czytelnik danych monitorowania, a następnie wybierz kartę Członkowie.
Wybierz pozycję Wybierz członków.
Wyszukaj zarejestrowaną aplikację i wybierz ją.
Naciśnij przycisk Wybierz.
Wybierz Przejrzyj + przypisz.

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 Postman.

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://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.

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

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, co szeregi czasowe, jeśli różnią się one od innej serii czasowej tylko w przypadku ciągu.

Uwaga

To zachowanie różni się od natywnego rozwiązania Prometheus typu open source, czyli systemu z uwzględnieniem wielkości liter.

W zarządzanym rozwiązaniu Prometheus platformy Azure następujące serie 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.

Wszystkie próbki pozyskane względem nich są przechowywane tak, jakby zostały zeskropane/pozyskane względem pojedynczego szeregu czasowego.
Jeśli powyższe przykłady są pozyskiwane z tym samym znacznikiem czasu, jeden z nich jest losowo porzucony.
Wielkość liter przechowywana w bazie danych szeregów czasowych i zwracana przez zapytanie jest nieprzewidywalna. Różne wielkości liter mogą być zwracane w różnych godzinach dla tych samych szeregów czasowych.
Każda nazwa metryki lub dopasowanie etykiety/wartości obecne w zapytaniu jest pobierane z bazy danych szeregów czasowych przez porównanie bez uwzględniania wielkości liter. Jeśli w zapytaniu jest uwzględniana wielkość liter, jest ona automatycznie traktowana jako element matcher bez uwzględniania wielkości liter podczas porównywania ciągów.

Najlepszym rozwiązaniem jest zapewnienie, że szereg czasowy jest generowany lub złomowany przy użyciu pojedynczego spójnego przypadku.

W rozwiązaniu Open Source Prometheus powyższy szereg czasowy jest traktowany jako dwa różne szeregi czasowe. Wszystkie próbki zeskrobane/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?

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 węzła, który jest uruchamiany podczas aktualizowania. 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

Share via