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.

Puoi utilizzare le etichette dei metadati in PromQL come qualsiasi altra etichetta, ma come i nomi delle metriche, anche le etichette dei metadati devono essere rese compatibili con PromQL. La sintassi per fare riferimento a un'etichetta di sistema dei metadati version è metadata_system_version, mentre la sintassi per l'etichetta utente dei metadati version è metadata_user_version. Le query PromQL ben formate che utilizzano le etichette dei metadati potrebbero avere il seguente aspetto:

  • {"compute.googleapis.com/instance/cpu/utilization", monitored_resource="gce_instance",metadata_user_env="prod"}
  • sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_system_region)
  • sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_user_env)
  • {"compute.googleapis.com/instance/uptime_total", "metadata_user_i-love.special/chars"="yes"}
  • sum("compute.googleapis.com/instance/uptime_total") by ("metadata_user_i-love.special/chars")

Se la chiave dell'etichetta dei metadati contiene caratteri speciali diversi dal carattere _, devi racchiudere la chiave dell'etichetta tra virgolette doppie (") in base alla specifica UTF-8 di PromQL. Devi comunque aggiungere il prefisso metadata_user_ all'etichetta dei metadati.

I grafici e i 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.

Accedere a PromQL in Cloud Monitoring

Puoi utilizzare PromQL dalla scheda Codice nelle seguenti pagine della console Google Cloud :

  • Esplora metriche
  • Aggiungi grafico durante la creazione di dashboard personalizzate

Per informazioni sull'accesso e sull'utilizzo dell'editor, consulta Utilizzo dell'editor PromQL.

Regole e avvisi PromQL

Puoi utilizzare PromQL per creare criteri di avviso per qualsiasi metrica in Cloud Monitoring. Per ulteriori informazioni, consulta Criteri di avviso basati su PromQL.

Puoi anche utilizzare PromQL per creare regole di registrazione e avviso su qualsiasi metrica in Cloud Monitoring utilizzando gli avvisi in-cluster in stile Prometheus in Cloud Monitoring. Per ulteriori informazioni, vedi Valutazione e avvisi delle regole gestite o Valutazione e avvisi delle regole autogestite.

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 da 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 e molte di quelle generate dalle metriche basate sui log, vengono mappate a più di un tipo di risorsa. Se utilizzi una di queste metriche, in particolare le metriche basate sui log, devi specificare esplicitamente il tipo di risorsa.

Per vedere a quale metrica sono mappati i tipi di risorsa monitorata, esegui una delle seguenti operazioni:

  • Per le metriche curate da Google, puoi consultare gli elenchi di metriche disponibili, tra cui le Google Cloud metriche e le metriche Kubernetes. 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.

  • In Esplora metriche, puoi:

    1. Inserisci il nome della metrica nel campo Seleziona una metrica e poi naviga nei menu per selezionarla. Il menu delle risorse elenca i tipi di risorse validi per quella metrica, ad esempio "Istanza VM".

    2. Nella barra degli strumenti del riquadro del generatore di query, seleziona il pulsante il cui nome è < > PromQL.

      La query PromQL visualizzata mostra il tipo di risorsa come valore del campo monitored_resource. In particolare, questo metodo è utile per le metriche che possono essere associate a molti tiprisorsa monitoratate, ad esempio metriche basate su log, metriche personalizzate o qualsiasi metrica definita dall'utente.

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"}
  • custom_googleapis_com:opencensus_opencensus_io_http_server_request_count_by_method{monitored_resource="global"}
  • loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

Il valore di "" per l'etichetta monitored_resource è speciale e si riferisce al tipo di risorsa prometheus_target predefinito utilizzato per le metriche di Cloud Monitoring.

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 metrica ha lo stesso nome chiave di un'etichetta risorsa, puoi fare riferimento all'etichetta 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
kubernetes.io/container/cpu/limit_cores kubernetes_io:container_cpu_limit_cores
compute.googleapis.com/instance/cpu/utilization compute_googleapis_com:instance_cpu_utilization
logging.googleapis.com/log_entry_count logging_googleapis_com:log_entry_count
custom.googleapis.com/opencensus/opencensus.io/
http/server/request_count_by_method		 custom_googleapis_com:opencensus_opencensus_io_
http_server_request_count_by_method
agent.googleapis.com/disk/io_time agent_googleapis_com:disk_io_time

È 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 sono presenti 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.

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 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 si evita 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 invece 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

L'obsolescenza non è supportata nel backend di Monarch.

Calcolo di irate

Quando l'intervallo di ricerca della funzione irate è inferiore alla dimensione del passo, aumentiamo l'intervallo fino alla dimensione del passo. 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 l'intervallo di ricerca della funzione rate è inferiore alla dimensione del passo, aumentiamo l'intervallo fino alla dimensione del passo. 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ò comporta risultati più precisi, soprattutto quando si eseguono query 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 nel 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.