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

Zarządzana usługa Azure Monitor dla Prometheus zbiera metryki z klastrów Azure Kubernetes i przechowuje je w obszarze roboczym 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 swojej aplikacji rolę Czytelnik danych monitorowania, aby mogła przeszukiwać dane z obszaru roboczego 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).

   

5. Na stronie „Dodawanie przypisania roli” wyszukaj „Monitorowanie”.

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

   

7. Wybierz Wybierz członków.

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

9. Wybierz Wybierz.

10. Wybierz Przejrzyj i 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 Insomnia lub PowerShell Invoke-RestMethod.

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.

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

Ścieżka: /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 Wartości etykiet.

Ścieżka: /api/v1/label/__name__/values.

Uwaga / Notatka

__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 Prometheus oprogramowania open source, zobacz Prometheus HTTP API.

Ograniczenia interfejsu API

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

• Zapytanie musi być ograniczone do danej 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 podane, endTime = time.now(). Jeśli zakres czasu jest większy niż 12 godzin, startTime jest ustawiony na endTime – 12h.

• Ignorowany zakres czasu

  Podany czas rozpoczęcia i zakończenia określony za pomocą elementów /labels i /label/__name__/values jest pomijany, a wszystkie dane znajdujące się 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 Azure Monitor dla Prometheus jest systemem niewrażliwym na wielkość 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 / Notatka

To zachowanie różni się od natywnego rozwiązania Prometheus typu open source, czyli systemu z uwzględnieniem wielkości liter. Instancje Prometheus zarządzane samodzielnie działające na maszynach wirtualnych platformy Azure, zestawach skalowalnych maszyn wirtualnych lub klastrach usługi Azure Kubernetes Service są systemami rozróżniają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 wprowadzone do nich są przechowywane tak, jakby zostały zeskrobane lub wprowadzone jako część pojedynczego szeregu czasowego.
• Jeśli powyższe przykłady są przetwarzane przy użyciu tego samego znacznika czasu, jeden z nich jest losowo odrzucony.
• Formatowanie, które jest przechowywane w bazie danych szeregów czasowych i zwracane przez zapytania, jest nieprzewidywalne. Ten sam szereg czasowy może zwracać różne formatowanie wielkości liter w różnym czasie.
• Każda nazwa metryki lub dopasowanie nazwy etykiety/wartości występujące w zapytaniu jest pobierana z bazy danych szeregów czasowych poprzez porównanie niebiorące pod uwagę wielkości liter. Jeśli w zapytaniu znajduje się dopasowanie uwzględniające wielkość liter, jest ono automatycznie traktowane jako dopasowanie bez uwzględniania wielkości liter w porównaniach ciągów.

Najlepiej jest użyć jednego spójnego przypadku do produkcji lub pozyskiwania szeregów czasowych.

Rozwiązanie Prometheus typu open source traktuje powyższe przykłady jako dwa różne szeregi czasowe. Wszystkie próbki zebrane lub pobrane względem nich są przechowywane oddzielnie.

Najczęściej zadawane pytania

Ta sekcja zawiera odpowiedzi na typowe pytania.

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

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

Dlaczego nie widzę metryk, które mają dwie etykiety o tej samej nazwie, ale różnej pisowni?

Rozwiązanie Prometheus zarządzane przez platformę Azure jest systemem nie uwzględniającym 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ę od innych szeregów czasowych jedynie wielkością liter 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 być widoczna luka w danych metryk od 1 do 2 minut, zebranych przez nasze kolektory 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 na poziomie klastra, takie jak kube-state-metrics i określone niestandardowe cele aplikacji. 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, na którym jest uruchomione. To zachowanie nie ma wpływu na żadne z naszych zalecanych reguł alertów.

Dalsze kroki

Omówienie obszaru roboczego usługi Azure MonitorZarządzanie obszarem roboczym usługi Azure MonitorOmówienie usługi zarządzanej Azure Monitor dla PrometheusZapytania dotyczące metryk Prometheus przy użyciu skoroszytów platformy Azure