PromQL per Cloud Monitoring

Questo documento descrive l'utilizzo di Prometheus Query Language (PromQL) in Cloud Monitoring. PromQL offre un'alternativa all'interfaccia basata su menu di Metrics Explorer per la creazione di grafici e dashboard.

Puoi utilizzare PromQL per eseguire query e creare grafici dei dati di Cloud Monitoring dalle seguenti origini:

Puoi anche utilizzare strumenti come Grafana per rappresentare graficamente i dati delle metriche inseriti in Cloud Monitoring. Le metriche disponibili includono le metriche di Managed Service per Prometheus e Cloud Monitoring documentate negli elenchi di metriche. Per informazioni sulla configurazione di Grafana e di altri strumenti basati sull'API Prometheus, consulta la documentazione di Managed Service per Prometheus su Grafana.

Puoi anche importare le dashboard Grafana in Cloud Monitoring.

Eseguire query sulle metriche di Cloud Monitoring utilizzando PromQL

È possibile eseguire query sulle metriche di Cloud Monitoring utilizzando la specifica UTF-8 per PromQL. I nomi delle metriche UTF-8 devono essere racchiusi tra virgolette e spostati all'interno delle parentesi graffe. I nomi delle etichette devono essere racchiusi tra virgolette anche se contengono caratteri incompatibili con le versioni precedenti. Per la metrica di Cloud Monitoring kubernetes.io/container/cpu/limit_utilization, le seguenti query sono equivalenti:

  • {"kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}
  • {__name__="kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}.
  • {"__name__"="kubernetes.io/container/cpu/limit_utilization", "pod_name"="foo"}.

È possibile eseguire query sulle metriche con valori di distribuzione di Cloud Monitoring come sugli istogrammi Prometheus, con il suffisso _count, _sum o _bucket aggiunto al nome della metrica.

I grafici e le dashboard creati prima della query di compatibilità UTF-8 Cloud Monitoring le metriche convertendo i relativi nomi in equivalenti legacy compatibili con PromQL. Per ulteriori informazioni sulle regole di conversione di PromQL legacy, consulta Mapping delle metriche di Cloud Monitoring a PromQL legacy.

Imparare PromQL

Per imparare le nozioni di base sull'utilizzo di PromQL, ti consigliamo di consultare la documentazione open source. Le seguenti risorse possono aiutarti a iniziare:

Specificare un tipo di risorsa monitorata

Quando una metrica Cloud Monitoring è associata a un solo tipo di risorsa monitorata Cloud Monitoring, l'esecuzione di query PromQL funzionerà senza specificare manualmente un tipo di risorsa. Tuttavia, alcune metriche in Cloud Monitoring, incluse alcune metriche di sistema, vengono mappate a più di un tipo di risorsa.

Puoi vedere a quali tipi di risorsa monitorata viene mappata una metrica consultando l'elenco delle metricheGoogle Cloud . Ogni voce della documentazione elenca i tipi di risorsa monitorata associati nella prima colonna di ogni voce sotto il tipo. Se non sono elencati tipi di risorsa monitorata, la metrica può essere associata a qualsiasi tipo.

Se una metrica è associata a più di un tipo di risorsa, devi specificare il tipo di risorsa nella query PromQL. Esiste un'etichetta speciale, monitored_resource, che puoi utilizzare per selezionare il tipo di risorsa.

I tipi di risorse monitorate sono nella maggior parte dei casi una stringa breve, come gce_instance, ma a volte vengono visualizzati come URI completi, ad esempio monitoring.googleapis.com/MetricIngestionAttribution. Le query PromQL ben formate potrebbero avere il seguente aspetto:

  • logging_googleapis_com:byte_count{monitored_resource="k8s_container"}
  • loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

Se non utilizzi l'etichetta monitored_resource quando è necessaria, ricevi il seguente errore:

metric is configured to be used with more than one monitored resource type; series selector must specify a label matcher on monitored resource name

Risoluzione dei conflitti di etichette

In Cloud Monitoring, le etichette possono appartenere alla metrica o alla risorsa. Se un'etichetta della metrica ha lo stesso nome chiave di un'etichetta della risorsa, puoi fare riferimento all'etichetta della metrica in modo specifico aggiungendo il prefisso metric_ al nome della chiave dell'etichetta nella query.

Ad esempio, supponiamo di avere un'etichetta risorsa e un'etichetta metrica entrambe denominate pod_name nella metrica example.googleapis.com/user/widget_count.

  • Per filtrare in base al valore dell'etichetta della risorsa, utilizza
    example_googleapis_com:user_widget_count{pod_name="RESOURCE_LABEL_VALUE"}

  • Per filtrare in base al valore dell'etichetta della metrica, utilizza
    example_googleapis_com:user_widget_count{metric_pod_name="METRIC_LABEL_VALUE"}

Mappatura dei nomi delle metriche di Cloud Monitoring a PromQL legacy

I nomi delle metriche di Cloud Monitoring includono due componenti: un dominio (ad esempio compute.googleapis.com/) e un percorso (ad esempio instance/disk/max_read_ops_count). Poiché PromQL legacy supporta solo i caratteri speciali : e _, devi applicare le seguenti regole per rendere i nomi delle metriche di Monitoring compatibili con PromQL legacy:

  • Sostituisci il primo / con :.
  • Sostituisci tutti gli altri caratteri speciali (inclusi . e altri caratteri / ) con _.

La tabella seguente elenca alcuni nomi di metriche e i relativi equivalenti PromQL legacy:

Nome della metrica di Cloud Monitoring Nome della metrica PromQL precedente
compute.googleapis.com/instance/cpu/utilization compute_googleapis_com:instance_cpu_utilization
logging.googleapis.com/log_entry_count logging_googleapis_com:log_entry_count

È possibile eseguire query sulle metriche con valori di distribuzione di Cloud Monitoring come sugli istogrammi Prometheus, con il suffisso _count, _sum o _bucket aggiunto al nome della metrica:

Nome della metrica di Cloud Monitoring Nomi delle metriche PromQL precedenti
networking.googleapis.com/vm_flow/rtt networking_googleapis_com:vm_flow_rtt_sum
networking_googleapis_com:vm_flow_rtt_count
networking_googleapis_com:vm_flow_rtt_bucket

Compatibilità con PromQL

PromQL per Cloud Monitoring potrebbe funzionare in modo leggermente diverso rispetto a PromQL upstream.

Le query PromQL in Cloud Monitoring vengono valutate parzialmente nel backend Monarch utilizzando un linguaggio di query interno e ci sono alcune differenze note nei risultati delle query. A parte le differenze elencate in questa sezione, PromQL in Cloud Monitoring è alla pari con PromQL disponibile in Prometheus versione 2.44.

Le funzioni PromQL aggiunte dopo la versione 2.44 di Prometheus potrebbero non essere supportate.

Supporto di UTF-8

PromQL per Cloud Monitoring supporta le query UTF-8.

Se il nome della metrica Prometheus è composto solo da caratteri alfanumerici più i caratteri _ o : e se le chiavi delle etichette sono composte solo da caratteri alfanumerici più il carattere _, puoi eseguire query utilizzando la sintassi PromQL tradizionale. Ad esempio, una query valida potrebbe avere il seguente aspetto: job:my_metric:sum{label_key="label_value"}.

Tuttavia, se il nome della metrica Prometheus utilizza caratteri speciali ad eccezione dei caratteri _ o : oppure se le chiavi delle etichette utilizzano caratteri speciali ad eccezione del carattere _, devi creare la query in base alla specifica UTF-8 per PromQL.

I nomi delle metriche UTF-8 devono essere racchiusi tra virgolette e spostati tra le parentesi graffe. I nomi delle etichette devono essere racchiusi tra virgolette anche se contengono caratteri incompatibili con le versioni precedenti. Le seguenti query valide di esempio sono tutte equivalenti:

  • {"my.domain.com/metric/name_bucket", "label.key"="label.value"}
  • {__name__="my.domain.com/metric/name_bucket", "label.key"="label.value"}
  • {"__name__"="my.domain.com/metric/name_bucket", "label.key"="label.value"}

Corrispondenza in base ai nomi delle metriche

È supportata solo la corrispondenza esatta dei nomi delle metriche. Devi includere una corrispondenza esatta del nome della metrica nella query.

Ti consigliamo le seguenti soluzioni alternative per gli scenari comuni che utilizzano un matcher di espressioni regolari sull'etichetta __name__:

  • Le configurazioni dell'adattatore Prometheus spesso utilizzano l'operatore =~ per trovare la corrispondenza con più nomi di metriche. Per correggere questo utilizzo, espandi la configurazione in modo da utilizzare una norma separata per ogni metrica e assegna un nome esplicito a ciascuna metrica. In questo modo eviti anche di scalare automaticamente in base a metriche impreviste.
  • Le espressioni regolari vengono spesso utilizzate per rappresentare graficamente più metriche non dimensionali nello stesso grafico. Ad esempio, se hai una metrica come cpu_servicename_usage, puoi utilizzare un carattere jolly per rappresentare graficamente tutti i tuoi servizi insieme. L'utilizzo di metriche non dimensionali come questa è una pratica esplicitamente sconsigliata in Cloud Monitoring e porta a prestazioni delle query estremamente scarse. Per correggere questo utilizzo, sposta tutta la dimensionalità nelle etichette delle metriche anziché incorporare le dimensioni nel nome della metrica.
  • L'esecuzione di query su più metriche viene spesso utilizzata per vedere quali metriche sono disponibili per le query. Ti consigliamo di utilizzare la chiamata /labels/__name__/values per scoprire le metriche. Puoi anche scoprire le metriche utilizzando la UI di Cloud Monitoring.
  • La corrispondenza di più metriche è utile per vedere quanti campioni sono stati sottoposti a scraping, importati e addebitati in base a ciascuna metrica. Cloud Monitoring fornisce queste informazioni nella pagina Gestione metriche. Puoi accedere a queste informazioni anche come dati delle metriche utilizzando la metrica Campioni importati o la metrica Campioni scritti dall'ID attribuzione.

Mancato aggiornamento

Staleness non è supportato nel backend di Monarch.

Calcolo di irate

Quando la finestra temporale per la funzione irate è inferiore alla dimensione del passaggio, aumentiamo la finestra temporale fino alla dimensione del passaggio. Monarch richiede questa modifica per garantire che nessuno dei dati di input venga completamente ignorato nell'output. Questa differenza si applica anche ai calcoli di rate.

Calcolo di rate e increase

Quando la finestra temporale per la funzione rate è inferiore alla dimensione del passaggio, aumentiamo la finestra temporale fino alla dimensione del passaggio. Monarch richiede questa modifica per garantire che nessuno dei dati di input venga completamente ignorato nell'output. Questa differenza si applica anche ai calcoli di irate.

Esistono differenze nei calcoli di interpolazione ed estrapolazione. Monarch utilizza un algoritmo di interpolazione diverso da Prometheus e questa differenza può portare a risultati leggermente diversi. Ad esempio, i campioni del contatore Monarch vengono archiviati con un intervallo di tempo anziché con il singolo timestamp utilizzato da Prometheus. Pertanto, i campioni del contatore in Monarch possono essere inclusi nel calcolo della velocità anche se il timestamp di Prometheus li escluderebbe. In genere, ciò si traduce in risultati più precisi, soprattutto quando la query viene eseguita all'inizio o alla fine della serie temporale sottostante.

Calcolo di histogram_quantile

Un calcolo histogram_quantile PromQL su un istogramma senza campioni produce un valore NaN. Il calcolo del linguaggio di query interno non produce alcun valore; il punto al timestamp viene eliminato.

Le differenze di calcolo della tariffa possono influire anche sull'input delle query histogram_quantile.

Funzioni specifiche per tipo su metriche con tipi diversi

Sebbene Prometheus upstream sia a tipizzazione debole, Monarch è a tipizzazione forte. Ciò significa che l'esecuzione di funzioni specifiche per un singolo tipo su una metrica di tipo diverso (ad esempio, l'esecuzione di rate() su una metrica GAUGE o di histogram_quantile() su una metrica COUNTER o senza tipo) non funziona in Cloud Monitoring, anche se queste funzioni funzionano in Prometheus upstream.