Dotazování metrik Prometheus pomocí rozhraní API a PromQL

Článek
12/24/2024

Spravovaná služba Azure Monitor pro Prometheus shromažďuje metriky z clusterů Azure Kubernetes a ukládá je do pracovního prostoru služby Azure Monitor. PromQL (dotazovací jazyk Prometheus) je funkční dotazovací jazyk, který umožňuje dotazovat a agregovat data časových řad. Pomocí nástroje PromQL můžete dotazovat a agregovat metriky uložené v pracovním prostoru služby Azure Monitor.

Tento článek popisuje, jak dotazovat pracovní prostor služby Azure Monitor pomocí jazyka PromQL prostřednictvím rozhraní REST API. Další informace o nástroji PromQL najdete v tématu Dotazování na prometheus.

Požadavky

Pokud chcete dotazovat pracovní prostor Služby Azure Monitor pomocí nástroje PromQL, potřebujete následující požadavky:

Cluster Azure Kubernetes nebo vzdálený cluster Kubernetes
Spravovaná služba Azure Monitoru pro prometheus seskupuje metriky z clusteru Kubernetes.
Pracovní prostor služby Azure Monitor, ve kterém se ukládají metriky Prometheus.

Ověřování

Pokud chcete dotazovat pracovní prostor služby Azure Monitor, ověřte se pomocí ID Microsoft Entra. Rozhraní API podporuje ověřování Microsoft Entra pomocí přihlašovacích údajů klienta. Zaregistrujte klientskou aplikaci s ID Microsoft Entra a požádejte o token.

Pokud chcete nastavit ověřování Microsoft Entra, postupujte následovně:

Zaregistrujte aplikaci pomocí Microsoft Entra ID.
Udělte aplikaci přístup k pracovnímu prostoru služby Azure Monitor.
Požádejte o token.

Registrace aplikace pomocí Microsoft Entra ID

Pokud chcete zaregistrovat aplikaci, postupujte podle kroků v části Registrace aplikace a požádejte o autorizační tokeny a pracujte s rozhraními API.

Povolit aplikaci přístup k vašemu pracovnímu prostoru

Přiřaďte aplikaci roli Čtenář dat monitorování, aby se mohl dotazovat na data z pracovního prostoru služby Azure Monitor.

Otevřete pracovní prostor Azure Monitoru na webu Azure Portal.
Na stránce Přehled si poznamenejte koncový bod dotazu pro použití v požadavku REST.
Vyberte Řízení přístupu (IAM) .
Na stránce Řízení přístupu (IAM) vyberte Přidat a pak přidejte přiřazení role.
Na stránce Přidat přiřazení role vyhledejte monitorování.
Vyberte Čtenář dat monitorování a pak vyberte kartu Členové.
Zvolte Zvolit členy.
Vyhledejte aplikaci, kterou jste zaregistrovali, a vyberte ji.
Zvolte Vybrat.
Vyberte Zkontrolovat + přiřadit.

Vytvořili jste registraci aplikace a přiřadili jste jí přístup k dotazování dat z pracovního prostoru služby Azure Monitor. Teď můžete vygenerovat token a použít ho v dotazu.

Vyžádání tokenu

Odešlete následující požadavek na příkazovém řádku nebo pomocí klienta, jako je režim spánku nebo Invoke-RestMethod PowerShellu.

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'

Text ukázkové odpovědi:

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

Uložte přístupový token z odpovědi pro použití v následujících požadavcích HTTP.

Koncový bod dotazu

Na stránce přehledu pracovního prostoru služby Azure Monitor vyhledejte koncový bod dotazu pracovního prostoru služby Azure Monitor.

Podporovaná rozhraní API

Podporují se následující dotazy:

Okamžité dotazy

Další informace najdete v tématu Okamžité dotazy.

Cesta: /api/v1/query
Příklady:

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>'

Dotazy rozsahu

Další informace naleznete v tématu Dotazy rozsahu
Cesta: /api/v1/query_range
Příklady:

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'

Řada

Další informace najdete v tématu Řada.

Cesta: /api/v1/series
Příklady:

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

Popisky

Další informace najdete v tématu Popisky cesty: /api/v1/labels
Příklady:

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'

Hodnoty popisků

Další informace najdete v tématu Hodnoty popisku.
Cesta: /api/v1/label/__name__/values.

Poznámka:

__name__ je jediná podporovaná verze tohoto rozhraní API a vrací všechny názvy metrik. Nejsou podporovány žádné jiné hodnoty /api/v1/label/<label_name>/values.

Příklad:

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

Úplnou specifikaci rozhraní API prom operačního systému najdete v tématu Prometheus HTTP API.

Omezení rozhraní API

Následující omezení jsou kromě těch, která jsou podrobně popsána ve specifikaci Prometheus.

Dotaz musí být vymezený na metriku.
Všechny dotazy řady time series fetch (/series nebo /query nebo /query_range) musí obsahovat __name__ shodovač popisků. To znamená, že každý dotaz musí být vymezen na metriku. V dotazu může být pouze jeden __name__ shodný popisek.
Dotaz /series nepodporuje filtr regulárních výrazů.
Podporovaný časový rozsah
- /query_range API podporuje časový rozsah 32 dnů. Toto je maximální povolený časový rozsah, včetně selektorů rozsahů zadaných v samotném dotazu. Dotaz za posledních 24 hodin by například rate(http_requests_total[1h] znamenal dotazování dat po dobu 25 hodin. Pochází z 24hodinového rozsahu a 1 hodiny zadané v samotném dotazu.
- Rozhraní API /series načítá data pro maximální 12hodinový časový rozsah. Pokud endTime není zadaný, endTime = time.now(). Pokud je doba rage větší než 12 hodin, je nastavena startTime na endTime – 12h
Ignorovaný časový rozsah
Počáteční a koncový čas poskytované /labels a /label/__name__/values jsou ignorovány a všechna zachovaná data v pracovním prostoru služby Azure Monitor se dotazují.
Experimentální funkce
Experimentální funkce, jako jsou příklady, se nepodporují.

Další informace o limitech metrik Prometheus najdete v tématu Metriky Prometheus.

Rozlišování malých a velkých písmen

Spravovaná služba Azure Monitoru pro Prometheus je systém nerozlišující velká a malá písmena. Zpracovává řetězce (například názvy metrik, názvy popisků nebo hodnoty popisků) jako stejné časové řady, pokud se liší od jiné časové řady pouze v případě řetězce.

Poznámka:

Toto chování se liší od nativního open source systému Prometheus, což je systém rozlišující malá a velká písmena. Instance Prometheus, které běží na virtuálních počítačích Azure, škálovacích sadách virtuálních počítačů nebo v clusterech Azure Kubernetes Service, se rozlišují malá a velká písmena.

Ve spravované službě pro Prometheus jsou následující časové řady považovány za stejné:

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

Předchozí příklady představují jednu časovou řadu v databázi časových řad. Vezměte na vědomí následující:

Všechny ingestované vzorky se ukládají tak, jako by byly šrotovány nebo ingestovány v rámci jedné časové řady.
Pokud se předchozí příklady ingestují se stejným časovým razítkem, jeden z nich se náhodně vyřadí.
Velikost velikostí uložená v databázi časových řad a vrácená dotazem je nepředvídatelná. Stejná časová řada může v různých časech vracet různá pouzdra.
Z databáze časových řad se prostřednictvím porovnání nerozlišují malá a velká písmena, načte se z databáze časových řad jakýkoli název metriky nebo shoda s názvem nebo hodnotou popisku v dotazu. Pokud je v dotazu rozlišovací na malá a velká písmena, při porovnávání řetězců se automaticky považuje za rozlišovací shodovač nerozlišující malá a velká písmena.

Osvědčeným postupem je použít jeden konzistentní případ k výrobě nebo škrábání časových řad.

Open source Prometheus považuje předchozí příklady za dvě různé časové řady. Všechny vzorky šrotované nebo ingestované proti nim se ukládají samostatně.

Nejčastější dotazy

Tato část obsahuje odpovědi na běžné otázky.

Chybí mi všechny metriky nebo některé metriky. Jak můžu řešit potíže?

Průvodce odstraňováním potíží můžete použít k ingestování metrik Prometheus ze spravovaného agenta.

Proč mi chybí metriky, které mají dva popisky se stejným názvem, ale různá velikost písma?

Azure Managed Prometheus je systém nerozlišující malá a velká písmena. Zpracovává řetězce, jako jsou názvy metrik, názvy popisků nebo hodnoty popisků, jako stejné časové řady, pokud se liší od jiné časové řady pouze velkým nebo malým písmenem řetězce. Další informace najdete v tématu Přehled metrik Prometheus.

V datech metrik se zobrazují určité mezery, proč k tomu dochází?

Během aktualizací uzlů se může zobrazit 1 minuta až 2minutová mezera v datech metrik pro metriky shromážděné z našich kolekcí na úrovni clusteru. K této mezerě dochází, protože uzel, na kterém se data spouští, se aktualizuje jako součást normálního procesu aktualizace. Tento proces aktualizace má vliv na cíle na úrovni clusteru, jako jsou metriky stavu kube a vlastní cíle aplikace, které jsou zadané. K tomu dochází při ruční aktualizaci clusteru nebo prostřednictvím automatického aktualizace. Toto chování je očekávané a dochází k němu kvůli aktualizaci uzlu, na kterém běží. Toto chování nemá vliv na žádná z našich doporučených pravidel upozornění.

Další kroky

Přehled pracovních prostorů služby Azure Monitor
Správa pracovního prostoru služby Azure Monitor
Přehled spravované služby Azure Monitor pro Prometheus
Dotazování metrik Prometheus pomocí sešitů Azure

Sdílet prostřednictvím