Query uitvoeren op metrische gegevens van Prometheus met behulp van de API en PromQL

Artikel
10/15/2024

Beheerde Azure Monitor-service voor Prometheus verzamelt metrische gegevens van Azure Kubernetes-clusters en slaat deze op in een Azure Monitor-werkruimte. PromQL (Prometheus-querytaal) is een functionele querytaal waarmee u tijdreeksgegevens kunt opvragen en aggregeren. Gebruik PromQL om metrische gegevens op te vragen en samen te voegen die zijn opgeslagen in een Azure Monitor-werkruimte.

In dit artikel wordt beschreven hoe u een query uitvoert op een Azure Monitor-werkruimte met behulp van PromQL via de REST API. Zie Query's uitvoeren op prometheus voor meer informatie over PromQL.

Vereisten

Als u een query wilt uitvoeren op een Azure Monitor-werkruimte met behulp van PromQL, hebt u de volgende vereisten nodig:

Een Azure Kubernetes-cluster of een extern Kubernetes-cluster.
Beheerde Azure Monitor-service voor Metrische gegevens voor Het scrapen van Prometheus uit een Kubernetes-cluster.
Een Azure Monitor-werkruimte waarin metrische prometheus-gegevens worden opgeslagen.

Verificatie

Als u een query wilt uitvoeren op uw Azure Monitor-werkruimte, moet u zich verifiëren met behulp van Microsoft Entra ID. De API ondersteunt Microsoft Entra-verificatie met behulp van clientreferenties. Registreer een client-app bij Microsoft Entra ID en vraag een token aan.

Volg de onderstaande stappen om Microsoft Entra-verificatie in te stellen:

Registreer een app bij Microsoft Entra ID.
Ververleent toegang tot de app aan uw Azure Monitor-werkruimte.
Een token aanvragen.

Een app registreren bij Microsoft Entra-id

Als u een app wilt registreren, volgt u de stappen in Een app registreren om autorisatietokens aan te vragen en met API's te werken

Uw app toegang geven tot uw werkruimte

Wijs de rol Bewakingsgegevenslezer toe aan uw app, zodat er query's kunnen worden uitgevoerd op gegevens uit uw Azure Monitor-werkruimte.

Open uw Azure Monitor-werkruimte in Azure Portal.
Noteer uw query-eindpunt op de overzichtspagina voor gebruik in uw REST-aanvraag.
Klik op Toegangsbeheer (IAM) .
Selecteer Toevoegen en voeg vervolgens roltoewijzing toe op de pagina Toegangsbeheer (IAM).
Zoek op de pagina Roltoewijzing toevoegen naar Bewaking.
Selecteer Bewakingsgegevenslezer en selecteer vervolgens het tabblad Leden.
Selecteer Leden selecteren.
Zoek de app die u hebt geregistreerd en selecteer deze.
Kies Selecteren.
Selecteer Controleren + toewijzen.

U hebt uw app-registratie gemaakt en deze toegang toegewezen om query's uit te voeren op gegevens uit uw Azure Monitor-werkruimte. U kunt nu een token genereren en gebruiken in een query.

Een token aanvragen

Verzend de volgende aanvraag in de opdrachtprompt of met behulp van een client zoals Slapeloosheid of De Invoke-RestMethod van 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'

Voorbeeldtekst van antwoord:

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

Sla het toegangstoken op uit het antwoord voor gebruik in de volgende HTTP-aanvragen.

Query-eindpunt

Zoek het query-eindpunt van uw Azure Monitor-werkruimte op de overzichtspagina van de Azure Monitor-werkruimte.

Ondersteunde API's

De volgende query's worden ondersteund:

Directe query's

Zie Instant-query's voor meer informatie

Pad: /api/v1/query
Voorbeelden:

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

Bereikquery's

Zie Bereikquery's voor meer informatie
Pad: /api/v1/query_range
Voorbeelden:

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'

Reeks

Zie Reeks voor meer informatie

Pad: /api/v1/series
Voorbeelden:

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

Etiketten

Zie Labelpad voor meer informatie: /api/v1/labels
Voorbeelden:

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'

Labelwaarden

Zie Labelwaarden voor meer informatie
Pad: /api/v1/label/__name__/values.

Notitie

__name__ is de enige ondersteunde versie van deze API en retourneert alle metrische namen. Er worden geen andere /api/v1/label/<label_name>/waarden ondersteund.

Voorbeeld:

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

Zie Prometheus HTTP-API voor de volledige specificatie van OSS-prom-API's.

API-beperkingen

De volgende beperkingen zijn naast de beperkingen die zijn beschreven in de Prometheus-specificatie.

Query moet zijn afgestemd op een metrische waarde
Elke tijdreeks die query's ophaalt (/series of /query of /query_range) moet een __name__ labelmatcher bevatten. Dat wil gezegd, elke query moet worden afgestemd op een metrische waarde. Er kan slechts één __name__ labelmatcher in een query zijn.
Query/reeks biedt geen ondersteuning voor het reguliere expressiefilter
Ondersteund tijdsbereik
- /query_range-API ondersteunt een tijdsbereik van 32 dagen. Dit is het toegestane maximale tijdsbereik, inclusief bereikkiezers die zijn opgegeven in de query zelf. De query rate(http_requests_total[1h] voor de afgelopen 24 uur betekent bijvoorbeeld dat gegevens gedurende 25 uur worden opgevraagd. Dit komt uit het bereik van 24 uur plus het 1 uur dat is opgegeven in de query zelf.
- /series-API haalt gegevens op voor een maximaal tijdsbereik van 12 uur. Als endTime dit niet is opgegeven, endTime = time.now(). Als de tijdsrage groter is dan 12 uur, wordt de waarde startTime ingesteld op endTime – 12h
Genegeerd tijdsbereik
De begin- en eindtijd worden genegeerd /labels /label/__name__/values en alle bewaarde gegevens in de Azure Monitor-werkruimte worden opgevraagd.
Experimentele functies
Experimentele functies, zoals exemplaren, worden niet ondersteund.

Zie Metrische prometheus-limieten voor meer informatie over metrische prometheus-limieten

Hoofdlettergevoelig

De beheerde Azure Monitor-service voor Prometheus is een niet hoofdlettergevoelig systeem. Hiermee worden tekenreeksen (zoals metrische namen, labelnamen of labelwaarden) behandeld als dezelfde tijdreeks als ze alleen verschillen van een andere tijdreeks in het geval van de tekenreeks.

Notitie

Dit gedrag verschilt van systeemeigen opensource Prometheus, een hoofdlettergevoelig systeem. Zelfbeheerde Prometheus-exemplaren die worden uitgevoerd in virtuele Azure-machines, virtuele-machineschaalsets of Azure Kubernetes Service-clusters zijn hoofdlettergevoelige systemen.

In de beheerde service voor Prometheus worden de volgende tijdreeksen als hetzelfde beschouwd:

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

De voorgaande voorbeelden zijn één tijdreeks in een tijdreeksdatabase. De volgende overwegingen zijn van toepassing:

Alle monsters die worden opgenomen, worden opgeslagen alsof ze worden geschraapt of opgenomen voor één tijdreeks.
Als de voorgaande voorbeelden worden opgenomen met hetzelfde tijdstempel, wordt een van deze voorbeelden willekeurig verwijderd.
De behuizing die is opgeslagen in de tijdreeksdatabase en die door een query wordt geretourneerd, is onvoorspelbaar. Dezelfde tijdreeks kan verschillende behuizingen op verschillende tijdstippen retourneren.
Elke metrische naam of labelnaam/waardematcher die aanwezig is in de query, wordt opgehaald uit de tijdreeksdatabase via een niet-hoofdlettergevoelige vergelijking. Als er een hoofdlettergevoelige matcher in een query is, wordt deze automatisch behandeld als een hoofdlettergevoelige matcher in tekenreeksvergelijkingen.

Het is een best practice om één consistent geval te gebruiken om een tijdreeks te produceren of te scrapen.

Opensource Prometheus behandelt de voorgaande voorbeelden als twee verschillende tijdreeksen. Alle monsters die op deze monsters worden gesroot of opgenomen, worden afzonderlijk opgeslagen.

Veelgestelde vragen

In deze sectie vindt u antwoorden op veelgestelde vragen.

Ik mis alle of sommige van mijn metrische gegevens. Hoe kan ik problemen oplossen?

U kunt de gids voor probleemoplossing gebruiken voor het opnemen van metrische prometheus-gegevens van de beheerde agent hier.

Waarom mis ik metrische gegevens met twee labels met dezelfde naam, maar met een andere behuizing?

Azure managed Prometheus is een niet hoofdlettergevoelig systeem. Hiermee worden tekenreeksen, zoals metrische namen, labelnamen of labelwaarden, behandeld als dezelfde tijdreeks als ze alleen verschillen van een andere tijdreeks in het geval van de tekenreeks. Zie het overzicht van metrische gegevens van Prometheus voor meer informatie.

Ik zie enkele hiaten in metrische gegevens. Waarom gebeurt dit?

Tijdens knooppuntupdates ziet u mogelijk een tussenruimte van 1 minuut tot 2 minuten in metrische gegevens voor metrische gegevens die zijn verzameld van onze verzamelaars op clusterniveau. Deze kloof treedt op omdat het knooppunt waarop de gegevens worden uitgevoerd, wordt bijgewerkt als onderdeel van een normaal updateproces. Dit updateproces is van invloed op clusterbrede doelen, zoals metrische gegevens van kube-state en aangepaste toepassingsdoelen die zijn opgegeven. Dit gebeurt wanneer uw cluster handmatig of via autoupdate wordt bijgewerkt. Dit gedrag wordt verwacht en treedt op omdat de node wordt uitgevoerd wanneer deze wordt bijgewerkt. Dit gedrag heeft geen invloed op een van onze aanbevolen waarschuwingsregels.

Volgende stappen

Overzicht van Azure Monitor-werkruimte
Een Azure Monitor-werkruimte beheren
Overzicht van Azure Monitor Managed Service voor Prometheus
Metrische gegevens van Prometheus opvragen met behulp van Azure-werkmappen

Delen via