Eseguire query sulle metriche di Prometheus usando l'API e PromQL

Articolo
12/24/2024

Il servizio gestito per Prometheus di Monitoraggio di Azure raccoglie le metriche dai cluster Azure Kubernetes e le archivia in un'area di lavoro di Monitoraggio di Azure. PromQL (linguaggio di query Prometheus) è un linguaggio di query funzionale che consente di eseguire query e aggregare i dati delle serie temporali. Usare PromQL per eseguire query e aggregare le metriche archiviate in un'area di lavoro di Monitoraggio di Azure.

Questo articolo descrive come eseguire query su un'area di lavoro di Monitoraggio di Azure usando PromQL tramite l'API REST. Per altre informazioni su PromQL, vedere Esecuzione di query su Prometheus.

Prerequisiti

Per eseguire query su un'area di lavoro di Monitoraggio di Azure usando PromQL, sono necessari i prerequisiti seguenti:

Un cluster Kubernetes di Azure o un cluster Kubernetes remoto.
Servizio gestito per Prometheus di Monitoraggio di Azure che incorpora metriche da un cluster Kubernetes.
Un'area di lavoro di Monitoraggio di Azure in cui vengono archiviate le metriche di Prometheus.

Autenticazione

Per eseguire query sull'area di lavoro di Monitoraggio di Azure, eseguire l'autenticazione con Microsoft Entra ID. L'API supporta l'autenticazione di Microsoft Entra usando le credenziali client. Registrare un'app client con Microsoft Entra ID e richiedere un token.

Per configurare l'autenticazione di Microsoft Entra, seguire questa procedura:

Registrare un'app con Microsoft Entra ID.
Concedere l'accesso dell'app all'area di lavoro di Monitoraggio di Azure.
Richiedere un token.

Registrare un'app con Microsoft Entra ID

Per registrare un'app, seguire la procedura descritta in Registrare un'app per richiedere token di autorizzazione e usare le API

Consentire all'app di accedere all'area di lavoro

Assegnare il ruolo Lettore dati di monitoraggio all'app in modo che possa eseguire query sui dati dall'area di lavoro di Monitoraggio di Azure.

Aprire l'area di lavoro di Monitoraggio di Azure nel portale di Azure.
Nella pagina Panoramica prendere nota dell'endpoint di query da usare nella richiesta REST.
Seleziona Controllo di accesso (IAM).
Selezionare Aggiungi, quindi Aggiungi assegnazione di ruolo nella pagina Controllo di accesso (IAM).
Nella pagina Aggiungi assegnazione di ruolo cercare Monitoraggio.
Selezionare Lettore dati di monitoraggio, quindi selezionare la scheda Membri.
Selezionare Selezionare i membri.
Cercare l'app registrata e selezionarla.
Scegli Seleziona.
Seleziona Rivedi + assegna.

È stata creata la registrazione dell'app a cui è stato assegnato l'accesso ai dati delle query dall'area di lavoro di Monitoraggio di Azure. È ora possibile generare un token e usarlo in una query.

Richiedere un token

Inviare la richiesta seguente al prompt dei comandi o tramite un client come Insomnia o Invoke-RestMethod di 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'

Corpo della risposta di esempio:

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

Salvare il token di accesso dalla risposta da usare nelle richieste HTTP seguenti.

Endpoint di query

Trovare l'endpoint di query dell'area di lavoro di Monitoraggio di Azure nella pagina di panoramica dell'area di lavoro di Monitoraggio di Azure.

API supportate

Sono supportate le query seguenti:

Query istantanee

Per altre informazioni, vedere Query istantanee

Percorso: /api/v1/query
Esempi:

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

Query su intervallo

Per altre informazioni, vedere Query di intervallo
Percorso: /api/v1/query_range
Esempi:

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'

di cassa

Per ulteriori informazioni, vedere Serie

Percorso: /api/v1/series
Esempi:

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

Etichette

Per ulteriori informazioni, vedere Etichette Percorso: /api/v1/labels
Esempi:

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'

Valori etichetta

Per altre informazioni, vedere Valori delle etichette
Percorso: /api/v1/label/__name__/values.

Nota

__name__ è l'unica versione supportata di questa API e restituisce tutti i nomi delle metriche. Non sono supportati altri valori /api/v1/label/<label_name>/values.

Esempio:

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

Per la specifica completa delle API di software open source prom, vedere API HTTP Prometheus.

Limitazioni dell'API

Le limitazioni seguenti si aggiungono a quelle descritte in dettaglio nella specifica Prometheus.

La query deve avere come ambito una metrica
Qualsiasi query di recupero delle serie temporali (/series o /query o /query_range) deve contenere un matcher di etichette __name__. In altre parole ogni query deve avere come ambito una metrica. In una query può essere presente un solo matcher di etichette __name__.
La query /series non supporta il filtro delle espressioni regolari
Intervallo di tempo supportato
- L'API /query_range supporta un intervallo di tempo di 32 giorni. Questo è l'intervallo di tempo massimo consentito, inclusi i selettori di intervallo specificati nella query stessa. Ad esempio, la query rate(http_requests_total[1h] per le ultime 24 ore significa effettivamente che i dati vengono sottoposti a query per 25 ore. Questo deriva dall'intervallo di 24 ore più l'ora specificata nella query stessa.
- L'API /series recupera i dati per un intervallo di tempo massimo di 12 ore. Se endTime non viene specificato, endTime = time.now(). Se l'intervallo di tempo è maggiore di 12 ore, l'oggetto startTime viene impostato su endTime – 12h
Intervallo di tempo ignorato
L'orario di inizio e l'orario di fine forniti con /labels e /label/__name__/values vengono ignorati e tutti i dati conservati nell'area di lavoro di Monitoraggio di Azure vengono sottoposti a query.
Funzionalità sperimentali
Le funzionalità sperimentali, ad esempio gli esemplari, non sono supportate.

Per altre informazioni sui limiti delle metriche di Prometheus, vedere Metriche di Prometheus

Distinzione tra maiuscole e minuscole

Il servizio gestito di Monitoraggio di Azure per Prometheus è un sistema senza distinzione tra maiuscole e minuscole. Considera stringhe (ad esempio nomi di metriche, nomi di etichetta o valori di etichetta) come la stessa serie temporale se differiscono da un'altra serie temporale solo in base alla distinzione tra maiuscole e minuscole della stringa.

Nota

Questo comportamento è diverso da Prometheus open source nativo, ovvero un sistema con distinzione tra maiuscole e minuscole. Le istanze di Prometheus autogestito in esecuzione in macchine virtuali di Azure, set di scalabilità di macchine virtuali o servizio Azure Kubernetes cluster fanno distinzione tra maiuscole e minuscole.

Nel servizio gestito per Prometheus, la serie temporale seguente viene considerata la stessa:

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

Gli esempi precedenti sono una singola serie temporale in un database time series. Si applicano le considerazioni seguenti:

Tutti i campioni inseriti su di essi vengono archiviati come se fossero raschiati o inseriti in base a una singola serie temporale.
Se gli esempi precedenti vengono inseriti con lo stesso timestamp, uno di essi viene eliminato in modo casuale.
La combinazione di maiuscole e minuscole archiviata nel database di serie temporali e restituita da una query è imprevedibile. La stessa serie temporale può restituire maiuscole e minuscole diverse in momenti diversi.
Qualsiasi nome di metrica o matcher nome/valore dell'etichetta presente nella query viene recuperato dal database time series tramite un confronto senza distinzione tra maiuscole e minuscole. Se in una query è presente un matcher con distinzione tra maiuscole e minuscole, viene considerato automaticamente come matcher senza distinzione tra maiuscole e minuscole nei confronti di stringhe.

È consigliabile usare un singolo case coerente per produrre o raschiare una serie temporale.

Prometheus open source considera gli esempi precedenti come due serie temporali diverse. Tutti i campioni raschiati o inseriti su di essi vengono archiviati separatamente.

Domande frequenti

Questa sezione fornisce le risposte alle domande comuni.

Mancano tutte le metriche o alcune delle mie metriche. Come è possibile risolvere i problemi?

È possibile usare la guida alla risoluzione dei problemi per l'inserimento di metriche Prometheus dall'agente gestito qui.

Perché mancano metriche con due etichette con lo stesso nome ma che presentano maiuscole/minuscole diverse?

Prometheus gestito da Azure è un sistema senza distinzione tra maiuscole e minuscole. Tratta le stringhe, come nomi di metriche, nomi di etichette o valori di etichette, come la stessa serie temporale se differiscono da un'altra serie temporale solo in base alla distinzione tra maiuscole e minuscole della stringa. Per altre informazioni, vedere Panoramica delle metriche in Prometheus.

Vengono visualizzati alcuni gap nei dati delle metriche, perché si verifica questo problema?

Durante gli aggiornamenti dei nodi, è possibile che si verifichi un gap di 1-2 minuti nei dati delle metriche raccolti dagli agenti di raccolta a livello di cluster. Questo gap si verifica perché il nodo in cui vengono eseguiti i dati viene aggiornato come parte di un normale processo di aggiornamento. Questo processo di aggiornamento influisce sulle destinazioni al livello di cluster, ad esempio su kube-state-metrics e su destinazioni di applicazione personalizzate specificate. Ciò si verifica quando il cluster viene aggiornato manualmente o tramite l'aggiornamento automatico. Questo comportamento è previsto e si verifica a causa del nodo in cui viene eseguito l'aggiornamento. Questo comportamento non influisce sulle regole di avviso consigliate.

Passaggi successivi

Panoramica dell'area di lavoro di Monitoraggio di Azure
Gestire un'area di lavoro di Monitoraggio di Azure
Panoramica del servizio gestito per Prometheus di Monitoraggio di Azure
Eseguire query sulle metriche di Prometheus usando le cartelle di lavoro di Azure

Condividi tramite