Query MQL di esempio

Questo documento introduce il Monitoring Query Language (MQL) attraverso esempi. Tuttavia, non cerca di coprire tutti gli aspetti della lingua. MQL è documentato in modo esaustivo nel riferimento sul monitoraggio del linguaggio di query.

Per informazioni sui criteri di avviso basati su MQL, consulta Criteri di avviso con MQL.

Puoi scrivere una determinata query in molti modi; il linguaggio è flessibile e puoi utilizzare molte scorciatoie se hai acquisito familiarità con la sintassi. Per maggiori informazioni, consulta la sezione Query in formato rigido.

Prima di iniziare

Per accedere all'editor di codice quando utilizzi Metrics Explorer, segui questi passaggi:

1. Nella console Google Cloud, vai alla pagina  Esplora metriche:

   Vai a Esplora metriche

   Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

2. Nella barra degli strumenti del riquadro di creazione di query, seleziona il pulsante con il nome  MQL o  PromQL.
3. Verifica che sia selezionato MQL nell'opzione di attivazione/disattivazione Lingua. L'opzione di attivazione/disattivazione della lingua si trova nella stessa barra degli strumenti che ti consente di formattare la query.

Per eseguire una query, incollala nell'editor e fai clic su Esegui query. Per un'introduzione a questo editor, consulta Utilizzare l'editor di codice per MQL.

È utile avere familiarità con i concetti di Cloud Monitoring, compresi i tipi di metriche, i tipi di risorse monitorate e le serie temporali. Per un'introduzione a questi concetti, consulta Metriche, serie temporali e risorse.

Modello dati

Le query MQL recuperano e manipolano i dati nel database delle serie temporali di Cloud Monitoring. Questa sezione introduce alcuni concetti e terminologia correlati a quel database. Per informazioni dettagliate, consulta l'argomento di riferimento Modello dei dati.

Ogni serie temporale ha origine da un unico tipo di risorsa monitorata e ogni serie temporale raccoglie dati di un solo tipo di metrica. Un descrittore di risorse monitorate definisce un tipo di risorsa monitorata. Analogamente, un descrittore della metrica definisce un tipo di metrica. Ad esempio, il tipo di risorsa potrebbe essere gce_instance, una macchina virtuale (VM) Compute Engine e il tipo di metrica potrebbe essere compute.googleapis.com/instance/cpu/utilization, l'utilizzo della CPU della VM di Compute Engine.

Questi descrittori specificano anche un insieme di etichette utilizzate per raccogliere informazioni su altri attributi della metrica o del tipo di risorsa. Ad esempio, le risorse in genere hanno un'etichetta zone, utilizzata per registrare la posizione geografica della risorsa.

Viene creata una serie temporale per ogni combinazione di valori delle etichette dalla coppia di un descrittore della metrica e di un descrittore di risorse monitorate.

Puoi trovare le etichette disponibili per i tipi di risorse nell'elenco delle risorse monitorate, ad esempio gce_instance. Per trovare le etichette per i tipi di metriche, consulta Elenco delle metriche; ad esempio, consulta Metriche di Compute Engine.

Il database Cloud Monitoring archivia le serie temporali di una metrica e un tipo di risorsa specifici in una tabella. La metrica e il tipo di risorsa fungono da identificatore della tabella. Questa query MQL recupera la tabella delle serie temporali che registrano l'utilizzo della CPU per le istanze di Compute Engine:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization

Nella tabella è presente una serie temporale per ogni combinazione unica di valori di metriche ed etichette delle risorse.

Le query MQL recuperano i dati delle serie temporali da queste tabelle e li trasformano in tabelle di output. Queste tabelle di output possono essere passate ad altre operazioni. Ad esempio, puoi isolare le serie temporali scritte dalle risorse in una determinata zona o in un determinato insieme di zone passando la tabella recuperata come input a un'operazione filter:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| filter zone =~ 'us-central.*'

La query precedente genera una tabella che contiene solo le serie temporali delle risorse di una zona che inizia con us-central.

Le query MQL sono strutturate in modo da passare l'output di un'operazione come input all'operazione successiva. Questo approccio basato su tabelle consente di collegare le operazioni per manipolare questi dati mediante filtri, selezione e altre operazioni di database familiari, come inner e outer join. Puoi anche eseguire varie funzioni sui dati nelle serie temporali man mano che i dati vengono passati da un'operazione all'altra.

Le operazioni e le funzioni disponibili in MQL sono completamente documentate nella documentazione di riferimento su Monitoring Query Language.

Struttura delle query

Una query è composta da una o più operations. Le operazioni sono collegate tra loro, o pipelate, in modo che l'output di un'operazione sia l'input dell'altra. Pertanto, il risultato di una query dipende dall'ordine delle operazioni. Ecco alcune delle cose che puoi fare:

• Avvia una query con un'operazione di selezione fetch o un'altra.
• Crea una query con più operazioni condotte insieme.
• Seleziona un sottoinsieme di informazioni con operazioni filter.
• Aggrega le informazioni correlate con le operazioni di group_by.
• Osserva i valori anomali con le operazioni top e bottom.
• Combina più query con operazioni { ; } e join.
• Utilizza l'operazione e le funzioni value per calcolare i rapporti e altri valori.

Non tutte le query utilizzano tutte queste opzioni.

Questi esempi introducono solo alcune delle operazioni e delle funzioni disponibili. Per informazioni dettagliate sulla struttura delle query MQL, consulta l'argomento di riferimento Struttura delle query.

Questi esempi non specificano due cose che potresti aspettarti di vedere: intervalli di tempo e allineamento. Le sezioni seguenti spiegano il motivo.

Intervalli di tempo

Quando utilizzi l'editor di codice, le impostazioni del grafico definiscono l'intervallo di tempo per le query. Per impostazione predefinita, l'intervallo di tempo del grafico è impostato su un'ora.

Per modificare l'intervallo di tempo del grafico, utilizza il selettore dell'intervallo di tempo. Ad esempio, se vuoi visualizzare i dati relativi alla settimana precedente, seleziona Ultima settimana dal selettore dell'intervallo di tempo. Puoi anche specificare un'ora di inizio e di fine o indicare un orario in cui visualizzare la cronologia.

Per ulteriori informazioni sugli intervalli di tempo nell'editor di codice, consulta Intervalli di tempo, grafici e l'editor di codice.

Allineamento

Molte delle operazioni utilizzate in questi esempi, ad esempio le operazioni join e group_by, dipendono da tutti i punti delle serie temporali in una tabella che si verificano a intervalli regolari. L'atto di allineare tutti i punti ai normali timestamp si chiama alignment. Di solito, l'allineamento è implicito e nessuno degli esempi qui lo mostra.

MQL allinea automaticamente le tabelle per le operazioni join e group_by quando necessario, ma MQL consente anche di eseguire l'allineamento in modo esplicito.

• Per informazioni generali sul concetto di allineamento, consulta Allineamento: aggregazione all'interno delle serie.

• Per informazioni sull'allineamento in MQL, consulta l'argomento di riferimento Allineamento. L'allineamento può essere controllato esplicitamente utilizzando le operazioni align e every.

Recupera e filtra i dati

Le query MQL iniziano con il recupero, la selezione o il filtro dei dati. Questa sezione illustra alcune operazioni di recupero e filtri di base con MQL.

Recuperare i dati delle serie temporali

Una query inizia sempre con un'operazione fetch, che recupera le serie temporali da Cloud Monitoring.

La query più semplice è composta da una singola operazione fetch e un argomento che identifica le serie temporali da recuperare, come:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization

L'argomento è costituito da un tipo di risorsa monitorata, gce_instance, una coppia di due caratteri, ::, e un tipo di metrica, compute.googleapis.com/instance/cpu/utilization.

Questa query recupera la serie temporale scritta dalle istanze Compute Engine per il tipo di metrica compute.googleapis.com/instance/cpu/utilization, che registra l'utilizzo della CPU da parte di queste istanze.

Se esegui la query dall'editor di codice in Metrics Explorer, ottieni un grafico che mostra ciascuna delle serie temporali richieste:

Ogni serie temporale richiesta viene visualizzata come una linea nel grafico. Ogni serie temporale include un elenco di valori con timestamp della metrica Utilizzo della CPU per un'istanza VM in questo progetto.

Nello spazio di archiviazione backend utilizzato da Cloud Monitoring, le serie temporali vengono archiviate in tabelle. L'operazione fetch organizza le serie temporali per i tipi di risorse e metriche monitorate specificati in una tabella, quindi restituisce la tabella. I dati restituiti vengono visualizzati nel grafico.

L'operazione fetch viene descritta, insieme ai suoi argomenti, nella pagina di riferimento di fetch. Per ulteriori informazioni sui dati generati dalle operazioni, consulta le pagine di riferimento per serie temporali e tabelle.

Filtra operazioni

Le query in genere consistono in una combinazione di più operazioni. La combinazione più semplice prevede l'utilizzo dell'operatore pipe | per indirizzare l'output di un'operazione all'input dell'operazione successiva. L'esempio seguente illustra l'utilizzo di una barra verticale per inserire la tabella in un'operazione di filtro:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| filter instance_name =~ 'gke.*'

Questa query indirizza la tabella, restituita dall'operazione fetch mostrata nell'esempio precedente, a un'operazione filter che prende come espressione che restituisce un valore booleano. In questo esempio, l'espressione significa "instance_name inizia con gke".

L'operazione filter prende la tabella di input, rimuove le serie temporali per le quali il filtro è falso e restituisce la tabella risultante. Il seguente screenshot mostra il grafico risultante:

Se non hai nomi di istanze che iniziano con gke, modifica il filtro prima di provare questa query. Ad esempio, se ci sono istanze VM con apache all'inizio dei nomi, utilizza il seguente filtro:

 | filter instance_name =~ 'apache.*'

L'espressione filter viene valutata una volta per ogni serie temporale di input. Se l'espressione restituisce true, la serie temporale viene inclusa nell'output. In questo esempio, l'espressione di filtro corrisponde a un'espressione regolare, =~, sull'etichetta instance_name di ogni serie temporale. Se il valore dell'etichetta corrisponde all'espressione regolare 'gke.*', la serie temporale viene inclusa nell'output. In caso contrario, le serie temporali vengono eliminate dall'output.

Per ulteriori informazioni sui filtri, consulta la pagina di riferimento di filter. Il predicato filter può essere qualsiasi espressione arbitraria che restituisca un valore booleano; per ulteriori informazioni, consulta la sezione Espressioni.

Raggruppa e aggrega

Il raggruppamento ti consente di raggruppare le serie temporali in base a dimensioni specifiche. L'aggregazione combina tutte le serie temporali di un gruppo in un'unica serie temporale di output.

La seguente query filtra l'output dell'operazione fetch iniziale per conservare solo quelle serie temporali dalle risorse in una zona che inizia con us-central. Raggruppa quindi le serie temporali per zona e le combina utilizzando l'aggregazione mean.

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| filter zone =~ 'us-central.*'
| group_by [zone], mean(val())

La tabella risultante dall'operazione group_by ha una serie temporale per zona. Il seguente screenshot mostra il grafico risultante:

L'operazione group_by accetta due argomenti, separati da una virgola, ,. Questi argomenti determinano l'esatto comportamento di raggruppamento. In questo esempio, group_by [zone], mean(val()), gli argomenti agiscono come segue:

• Il primo argomento, [zone], è un'espressione di mappa che determina il raggruppamento delle serie temporali. In questo esempio, specifica le etichette da utilizzare per il raggruppamento. Il passaggio di raggruppamento raccoglie in un unico gruppo tutte le serie temporali di input che hanno gli stessi valori zone di output. In questo esempio, l'espressione raccoglie le serie temporali dalle VM di Compute Engine in una zona.

  La serie temporale di output ha solo un'etichetta zone, con il valore copiato dalla serie temporale di input nel gruppo. Le altre etichette della serie temporale di input vengono eliminate da quelle di output.

  L'espressione mappa può fare molto di più che elencare le etichette; per ulteriori informazioni, consulta la pagina di riferimento map.

• Il secondo argomento, mean(val()), determina il modo in cui le serie temporali di ogni gruppo vengono combinate, o aggregated, in un'unica serie temporale di output. Ogni punto nella serie temporale di output per un gruppo è il risultato dell'aggregazione dei punti con lo stesso timestamp di tutte le serie temporali di input nel gruppo.

  La funzione di aggregazione, mean in questo esempio, determina il valore aggregato. La funzione val() restituisce i punti da aggregare, a questi punti viene applicata la funzione di aggregazione. In questo esempio, puoi ottenere la media dell'utilizzo della CPU delle macchine virtuali nella zona in ogni punto temporale di output.

  L'espressione mean(val()) è un esempio di espressione di aggregazione.

L'operazione group_by combina sempre il raggruppamento e l'aggregazione. Se specifichi un raggruppamento, ma ometti l'argomento di aggregazione, group_by utilizza un'aggregazione predefinita, aggregate(val()), che seleziona una funzione appropriata per il tipo di dati. Consulta aggregate per l'elenco delle funzioni di aggregazione predefinite.

Utilizza group_by con una metrica basata su log

Supponi di aver creato una metrica basata su log di distribuzione per estrarre il numero di punti dati elaborati da un insieme di voci lunghe, incluse stringhe come seguenti:

... entry ID 1 ... Processed data points 1000 ...
... entry ID 2 ... Processed data points 1500 ...
... entry ID 3 ... Processed data points 1000 ...
... entry ID 4 ... Processed data points 500 ...

Per creare una serie temporale che mostri il conteggio di tutti i punti dati elaborati, utilizza un MQL come il seguente:

fetch global
| metric 'logging.googleapis.com/user/METRIC_NAME'
| group_by [], sum(sum_from(value))

Per creare una metrica di distribuzione basata su log, consulta Configurare le metriche di distribuzione.

Escludi le colonne da un gruppo

Puoi utilizzare il modificatore drop in una mappatura per escludere le colonne da un gruppo. Ad esempio, la metrica core_usage_time di Kubernetes ha sei colonne:

fetch k8s_container :: kubernetes.io/container/cpu/core_usage_time
| group_by [project_id, location, cluster_name, namespace_name, container_name]

Se non è necessario raggruppare pod_name, puoi escluderlo con drop:

fetch k8s_container :: kubernetes.io/container/cpu/core_usage_time
| group_by drop [pod_name]

Seleziona serie temporale

Gli esempi in questa sezione illustrano come selezionare determinate serie temporali da una tabella di input.

Seleziona serie temporali superiore o inferiore

Per visualizzare i dati delle serie temporali per le tre istanze di Compute Engine con il massimo utilizzo di CPU all'interno del progetto, inserisci la query seguente:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| top 3

Il seguente screenshot mostra il risultato di un progetto:

Per recuperare la serie temporale con l'utilizzo più basso di CPU, sostituisci top con bottom.

L'operazione top genera una tabella con un numero specificato di serie temporali selezionate dalla relativa tabella di input. Le serie temporali incluse nell'output hanno il valore più grande per alcuni aspetti delle serie temporali.

Poiché questa query non specifica un modo per ordinare le serie temporali, restituisce quelle con il valore più grande per il punto più recente. Per specificare come determinare quali serie temporali hanno il valore più grande, puoi fornire un argomento all'operazione top. Ad esempio, la query precedente equivale alla seguente query:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| top 3, val()

L'espressione val() seleziona il valore del punto più recente in ogni serie temporale a cui viene applicata. La query restituisce quindi le serie temporali con il valore più alto per il punto più recente.

Puoi fornire un'espressione che esegue l'aggregazione su alcuni o tutti i punti di una serie temporale per fornire il valore di ordinamento. Di seguito viene calcolata la media di tutti i punti negli ultimi 10 minuti:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| top 3, mean(val()).within(10m)

Se non viene utilizzata la funzione within, la funzione mean viene applicata ai valori di tutti i punti visualizzati nella serie temporale.

L'operazione bottom funziona in modo simile. La seguente query trova il valore del punto più grande in ogni serie temporale con max(val()), quindi seleziona le tre serie temporali per le quali il valore è più piccolo:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| bottom 3, max(val())

Il seguente screenshot mostra un grafico che mostra gli stream con i picchi più piccoli:

Escludi i risultati in alto o in basso n nelle serie temporali

Considera uno scenario in cui hai molte istanze VM di Compute Engine. Alcune di queste istanze consumano molta più memoria della maggior parte delle istanze e questi outlier rendono più difficile vedere i pattern di utilizzo nel gruppo più grande. I grafici sull'utilizzo della CPU hanno il seguente aspetto:

Vuoi escludere i tre outlier dal grafico in modo da poter vedere più chiaramente i pattern nel gruppo più grande.

Per escludere le prime tre serie temporali in una query che recupera le serie temporali per l'utilizzo della CPU di Compute Engine, utilizza l'operazione di tabella top per identificare le serie temporali e l'operazione della tabella outer_join per escludere la serie temporale identificata dai risultati. Puoi utilizzare la seguente query:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| {
    top 3 | value [is_default_value: false()]
  ;
    ident
  }
| outer_join true(), _
| filter is_default_value
| value drop [is_default_value]

L'operazione fetch restituisce una tabella di serie temporali per l'utilizzo della CPU da tutte le istanze. Questa tabella viene quindi elaborata in due tabelle risultanti:

• L'operazione di tabella top n restituisce una tabella che contiene la serie temporale n con i valori più elevati. In questo caso, n = 3. La tabella risultante contiene le tre serie temporali da escludere.

  La tabella contenente le prime tre serie temporali viene quindi trasmessa a un'operazione di tabella value. Questa operazione aggiunge un'altra colonna a ciascuna delle serie temporali nella tabella delle prime tre. A questa colonna, is_default_value, viene assegnato il valore booleano false per tutte le serie temporali nella tabella delle prime tre.

• L'operazione ident restituisce la stessa tabella che è stata restituita: la tabella originale delle serie temporali di utilizzo della CPU. Nessuna delle serie temporali in questa tabella ha la colonna is_default_value.

Le prime tre tabelle e la tabella originale vengono quindi inserite nell'operazione della tabella outer_join. Le prime tre tabelle sono la tabella a sinistra nel join, la tabella recuperata è la tabella a destra nel join. Il join esterno è configurato per fornire il valore true come valore per qualsiasi campo che non esiste in una riga di cui viene unita. Il risultato dell'outer join è una tabella unita in cui le righe delle prime tre tabelle mantengono la colonna is_default_value con il valore false e tutte le righe della tabella originale che non erano presenti anche nelle prime tre tabelle ricevono la colonna is_default_value con il valore true.

La tabella risultante dal join viene quindi passata all'operazione della tabella filter, che filtra le righe che hanno il valore false nella colonna is_default_value. La tabella risultante contiene le righe della tabella recuperata originariamente senza le righe delle prime tre tabelle. Questa tabella contiene l'insieme previsto di serie temporali, con l'aggiunta del valore is_default_column.

Il passaggio finale consiste nel rilasciare la colonna is_default_column aggiunta dal join, in modo che la tabella di output abbia le stesse colonne della tabella recuperata originariamente.

Il seguente screenshot mostra il grafico della query precedente:

Puoi creare una query per escludere le serie temporali con l'utilizzo minimo di CPU sostituendo top n con bottom n.

La possibilità di escludere gli outlier può essere utile nei casi in cui vuoi impostare un avviso ma non vuoi che i valori anomali attivino costantemente l'avviso. La seguente query di avviso utilizza la stessa logica di esclusione della query precedente per monitorare l'utilizzo del limite di CPU da parte di un insieme di pod Kubernetes, dopo aver escluso i primi due pod:

fetch k8s_container
| metric 'kubernetes.io/container/cpu/limit_utilization'
| filter (resource.cluster_name == 'CLUSTER_NAME' &&
          resource.namespace_name == 'NAMESPACE_NAME' &&
          resource.pod_name =~ 'POD_NAME')
| group_by 1m, [value_limit_utilization_max: max(value.limit_utilization)]
| {
    top 2 | value [is_default_value: false()]
  ;
    ident
  }
| outer_join true(), _
| filter is_default_value
| value drop [is_default_value]
| every 1m
| condition val(0) > 0.73 '1'

Seleziona in alto o in basso dai gruppi

Le operazioni della tabella top e bottom selezionano le serie temporali dall'intera tabella di input. Le operazioni top_by e bottom_by raggruppano le serie temporali in una tabella, quindi selezionano un certo numero di serie temporali da ciascun gruppo.

La seguente query seleziona le serie temporali in ciascuna zona con il valore di picco maggiore:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| top_by [zone], 1, max(val())

L'espressione [zone] indica che un gruppo è costituito da serie temporali con lo stesso valore della colonna zone. Il valore 1 nel valore top_by indica il numero di serie temporali da selezionare per il gruppo di ogni zona. L'espressione max(val()) cerca il valore più grande nell'intervallo di tempo del grafico in ogni serie temporale.

Puoi utilizzare qualsiasi funzione di aggregazione al posto di max. Ad esempio, di seguito viene utilizzato l'aggregatore mean e within per specificare l'intervallo di ordinamento di 20 minuti. Seleziona le prime 2 serie temporali in ogni zona:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| top_by [zone], 2, mean(val()).within(20m)

Nell'esempio precedente, esiste una sola istanza nella zona us-central-c, quindi viene restituita solo una serie temporale; non è presente alcuna "primi 2" nel gruppo.

Combina le selezioni con union

Puoi combinare operazioni di selezione come top e bottom per creare grafici che mostrano entrambi. Ad esempio, la seguente query restituisce la singola serie temporale con il valore massimo e la singola serie temporale con il valore minimo:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| {
    top 1, max(val())
  ;
    bottom 1, min(val())
  }
| union

Nota: il rientro e l'allineamento dei componenti della query servono a garantire la leggibilità. MQL non è una lingua dipendente dallo spazio.

Il grafico risultante mostra due righe, una contenente il valore più alto e l'altra con il valore più basso:

Puoi utilizzare le parentesi graffe, { }, per specificare sequenze di operazioni, ciascuna delle quali genera una tabella di serie temporali come output. Le singole operazioni sono separate da un punto e virgola, ;.

In questo esempio, l'operazione fetch restituisce una singola tabella, che viene inviata a ciascuna delle due operazioni nella sequenza, un'operazione top e un'operazione bottom. Ognuna di queste operazioni genera una tabella di output basata sulla stessa tabella di input. L'operazione union combina quindi le due tabelle in una sola, che viene visualizzata nel grafico.

Per scoprire di più sulle operazioni di sequenza utilizzando { }, consulta l'argomento di riferimento Struttura delle query.

Combinare serie temporali con valori diversi per un'unica etichetta

Supponi di avere più serie temporali per lo stesso tipo di metrica e di volerne combinarne alcune. Se vuoi selezionarli in base ai valori di una singola etichetta, non puoi creare la query utilizzando l'interfaccia di Query Builder in Metrics Explorer. Devi applicare un filtro in base a due o più valori diversi della stessa etichetta, ma l'interfaccia dello strumento di creazione delle query richiede che una serie temporale corrisponda a tutti i filtri da selezionare: la corrispondenza delle etichette è un test AND. Nessuna serie temporale può avere due valori diversi per la stessa etichetta, ma non puoi creare un test OR per i filtri in Query Builder.

La seguente query recupera le serie temporali per la metrica instance/disk/max_read_ops_count di Compute Engine per due istanze specifiche di Compute Engine e allinea l'output a intervalli di 1 minuto:

fetch gce_instance
| metric 'compute.googleapis.com/instance/disk/max_read_ops_count'
| filter (resource.instance_id == '1854776029354445619' ||
          resource.instance_id == '3124475757702255230')
| every 1m

Il grafico seguente mostra un risultato di questa query:

Per trovare la somma dei valori massimi di max_read_ops_count per queste due VM e sommarli, puoi procedere come segue:

• Trova il valore massimo per ogni serie temporale utilizzando l'operatore di tabella group_by, specificando lo stesso periodo di allineamento di 1 minuto e aggregando il periodo nel periodo con l'aggregatore max per creare una colonna denominata max_val_of_read_ops_count_max nella tabella di output.
• Trova la somma delle serie temporali utilizzando l'operatore di tabella group_by e l'aggregatore sum nella colonna max_val_of_read_ops_count_max.

Di seguito è riportata la query:

fetch gce_instance
| metric 'compute.googleapis.com/instance/disk/max_read_ops_count'
| filter (resource.instance_id == '1854776029354445619' ||
          resource.instance_id == '3124475757702255230')
| group_by 1m, [max_val_of_read_ops_count_max: max(value.max_read_ops_count)]
| every 1m
| group_by [], [summed_value: sum(max_val_of_read_ops_count_max)]

Il grafico seguente mostra un risultato di questa query:

Statistiche sul percentile di calcolo nel tempo e tra flussi

Per calcolare separatamente un valore di flusso percentile su una finestra scorrevole per ogni flusso, utilizza un'operazione group_by temporale. Ad esempio, la seguente query calcola il 99° percentile di un flusso su una finestra temporale di 1 ora:

fetch gce_instance :: compute.googleapis.com/instance/cpu/utilization
| group_by 1h, percentile(val(), 99)
| every 1m

Per calcolare la stessa statistica percentile in un momento specifico tra i vari stream, anziché nel tempo all'interno di un flusso, utilizza un'operazione group_by spaziale:

fetch gce_instance :: compute.googleapis.com/instance/cpu/utilization
| group_by [], percentile(val(), 99)

Rapporti di calcolo

Supponi di aver creato un servizio web distribuito in esecuzione su istanze VM di Compute Engine e che utilizza Cloud Load Balancing.

Vuoi visualizzare un grafico che mostra il rapporto tra le richieste che restituiscono risposte HTTP 500 (errori interni) e il numero totale di richieste, ovvero il rapporto tra richieste di errore. Questa sezione illustra diversi modi per calcolare il rapporto tra richieste di errore.

Cloud Load Balancing utilizza il tipo di risorsa monitorata http_lb_rule. Il tipo di risorsa monitorata http_lb_rule ha un'etichetta matched_url_path_rule che registra il prefisso degli URL definiti per la regola. Il valore predefinito è UNMATCHED.

Il tipo di metrica loadbalancing.googleapis.com/https/request_count ha un'etichetta response_code_class. Questa etichetta acquisisce la classe dei codici di risposta.

Utilizza outer_join e div

La seguente query determina le risposte 500 per ogni valore dell'etichetta matched_url_path_rule in ogni http_lb_rule risorsa monitorata nel progetto. Poi unisce questa tabella del numero di errori con la tabella originale, che contiene tutti i conteggi delle risposte e divide i valori per mostrare il rapporto tra le risposte di errore e le risposte totali:

fetch https_lb_rule::loadbalancing.googleapis.com/https/request_count
| {
    filter response_code_class = 500
  ;
    ident
  }
| group_by [matched_url_path_rule]
| outer_join 0
| div

Il grafico seguente mostra il risultato di un progetto:

Le aree ombreggiate intorno alle linee del grafico sono bande min/max; per ulteriori informazioni, consulta Bande min/max.

L'operazione fetch genera una tabella di serie temporali contenente i conteggi delle richieste per tutte le query con bilanciamento del carico. Questa tabella viene elaborata in due modi dalle due sequenze di operazioni nelle parentesi graffe:

• filter response_code_class = 500 restituisce solo le serie temporali che hanno l'etichetta response_code_class con il valore 500. La serie temporale risultante conteggia le richieste con codici di risposta HTTP 5xx (errore).

  Questa tabella è il numeratore del rapporto.

• L'operazione ident, o identity, restituisce il proprio input, quindi questa operazione restituisce la tabella recuperata originariamente. Questa è la tabella che contiene serie temporali con i conteggi per ogni codice di risposta.

  Questa tabella è il denominatore del rapporto.

Le tabelle numeratore e denominatore, prodotte rispettivamente dalle operazioni filter e ident, vengono elaborate separatamente dall'operazione group_by. L'operazione group_by raggruppa le serie temporali in ogni tabella in base al valore dell'etichetta matched_url_path_rule e somma i conteggi di ogni valore dell'etichetta. Questa operazione group_by non indica esplicitamente la funzione aggregatore, pertanto viene utilizzato un valore predefinito, sum.

• Per la tabella filtrata, il risultato di group_by è il numero di richieste che restituiscono una risposta 500 per ogni valore matched_url_path_rule.

• Per la tabella delle identità, il risultato di group_by è il numero totale di richieste per ogni valore matched_url_path_rule.

Queste tabelle vengono indirizzate all'operazione outer_join, che abbina le serie temporali a valori delle etichette corrispondenti, uno da ciascuna delle due tabelle di input. Le serie temporali accoppiate vengono compresse abbinando il timestamp di ogni punto in una serie temporale al timestamp di un punto nell'altra serie temporale. Per ogni coppia di punti corrispondente, outer_join produce un singolo punto di output con due valori, uno da ciascuna delle tabelle di input. La serie temporale compressa viene generata dal join con le stesse etichette delle due serie temporali di input.

Con un outer join, se un punto della seconda tabella non ha un punto di corrispondenza nella prima, è necessario fornire un valore sostitutivo. In questo esempio, viene utilizzato un punto con valore 0—l'argomento dell'operazione outer_join.

Nota: perché utilizzare 0 come valore? Se una risorsa monitorata non ha mai risposto con una risposta 500, non è presente alcun valore di conteggio per le risposte 500. Il valore sostitutivo fornisce un valore pari a 0 per il conteggio.

Infine, l'operazione div prende ogni punto con due valori e divide i valori per produrre un singolo punto di output, ovvero il rapporto di 500 risposte a tutte le risposte per ogni mappa URL.

La stringa div qui è in realtà il nome della funzione div, che divide due valori numerici. Tuttavia, in questo caso viene utilizzata come operazione. Se utilizzate come operazioni, funzioni come div si aspettano due valori in ogni punto di input (cosa garantisce join) e producono un singolo valore per il punto di output corrispondente.

La parte | div della query è una scorciatoia per | value val(0) / val(1). L'operazione value consente a espressioni arbitrarie nelle colonne dei valori di una tabella di input di produrre le colonne dei valori della tabella di output. Per maggiori informazioni, consulta le pagine di riferimento per l'operazione value e per le espressioni.

Utilizza ratio

La funzione div può essere sostituita con qualsiasi funzione su due valori, ma poiché i rapporti vengono utilizzati così spesso, MQL fornisce un'operazione di tabella ratio che calcola direttamente i rapporti.

La seguente query è equivalente alla versione precedente, utilizzando outer_join e div:

fetch https_lb_rule::loadbalancing.googleapis.com/https/request_count
| {
    filter response_code_class = 500
  ;
    ident
  }
| group_by [matched_url_path_rule]
| ratio

In questa versione, l'operazione ratio sostituisce le operazioni outer_join 0 | div della versione precedente e produce lo stesso risultato.

Tieni presente che ratio utilizza outer_join per fornire un 0 per il numeratore solo se gli input del numeratore e del denominatore hanno le stesse etichette che identificano ogni serie temporale, richiesta da MQL outer_join. Se l'input del numeratore ha ulteriori etichette, non ci sarà alcun output per alcun punto mancante nel denominatore.

Utilizza group_by e /

Esiste un altro modo per calcolare il rapporto tra le risposte di errore e tutte le risposte. In questo caso, poiché il numeratore e il denominatore del rapporto derivano dalla stessa serie temporale, puoi anche calcolare il rapporto raggruppando i dati. La seguente query mostra questo approccio:

fetch https_lb_rule::loadbalancing.googleapis.com/https/request_count
| group_by [matched_url_path_rule],
    sum(if(response_code_class = 500, val(), 0)) / sum(val())

Questa query utilizza un'espressione di aggregazione basata sul rapporto di due somme:

• Il primo sum utilizza la funzione if per contare 500 etichette con valori e 0 per le altre. La funzione sum calcola il conteggio delle richieste che hanno restituito 500.

• Il secondo sum somma il conteggio di tutte le richieste: val().

Le due somme vengono quindi divise, ottenendo il rapporto di 500 risposte per tutte le risposte. Questa query produce lo stesso risultato delle query in Con outer_join e div e Con ratio.

Utilizza filter_ratio_by

Poiché i rapporti vengono spesso calcolati dividendo due somme derivate dalla stessa tabella, MQL fornisce l'operazione filter_ratio_by a questo scopo. La seguente query funziona come la versione precedente, che divide in modo esplicito le somme:

fetch https_lb_rule::loadbalancing.googleapis.com/https/request_count
| filter_ratio_by [matched_url_path_rule], response_code_class = 500

Il primo operando dell'operazione filter_ratio_by, qui [matched_url_path_rule], indica come raggruppare le risposte. La seconda operazione, qui response_code_class = 500, funge da espressione di filtro per il numeratore.

• La tabella denominatore è il risultato del raggruppamento della tabella recuperata per matched_url_path_rule e aggregata per sum.
• La tabella del numeratore è la tabella recuperata, filtrata in base alle serie temporali con un codice di risposta HTTP 5xx, quindi raggruppata per matched_url_path_rule e aggregata tramite sum.

Rapporti e metriche di quota

Per configurare query e avvisi sulle metriche delle quote di serviceruntime e sulle metriche delle quote specifiche delle risorse per monitorare il consumo delle quote, puoi utilizzare MQL. Per ulteriori informazioni, inclusi esempi, consulta Utilizzare le metriche di quota.

Calcolo aritmetico

A volte potresti voler eseguire un'operazione aritmetica sui dati prima di creare un grafico. Ad esempio, puoi scalare le serie temporali, convertire i dati in scala logaritmica o tracciare la somma di due serie temporali. Per un elenco delle funzioni aritmetiche disponibili in MQL, consulta Aritmetica.

Per scalare una serie temporale, utilizza la funzione mul. Ad esempio, la seguente query recupera la serie temporale e moltiplica ogni valore per 10:

  fetch gce_instance
  | metric 'compute.googleapis.com/instance/disk/read_bytes_count'
  | mul(10)

Per sommare due serie temporali, configura la query per recuperare due tabelle di serie temporali, unisci i risultati e quindi chiama la funzione add. L'esempio seguente illustra una query che calcola la somma del numero di byte letti e scritti nelle istanze di Compute Engine:

  fetch gce_instance
  | { metric 'compute.googleapis.com/instance/disk/read_bytes_count'
    ; metric 'compute.googleapis.com/instance/disk/write_bytes_count' }
  | outer_join 0
  | add

Per sottrarre il conteggio dei byte scritti dal conteggio dei byte letti, sostituisci add con sub nell'espressione precedente.

MQL utilizza le etichette nei set di tabelle restituite dal primo e dal secondo recupero per determinare come unire le tabelle:

• Se la prima tabella contiene un'etichetta non trovata nella seconda tabella, MQL non può eseguire un'operazione outer_join sulle tabelle e, di conseguenza, viene segnalato un errore. Ad esempio, la seguente query causa un errore perché l'etichetta metric.instance_name è presente nella prima tabella, ma non nella seconda:

   fetch gce_instance
    | { metric 'compute.googleapis.com/instance/disk/write_bytes_count'
      ; metric 'compute.googleapis.com/instance/disk/max_write_bytes_count' }
    | outer_join 0
    | add
  

  Un modo per risolvere questo tipo di errore è applicare clausole di raggruppamento per garantire che le due tabelle abbiano le stesse etichette. Ad esempio, puoi raggruppare le etichette di tutte le serie temporali:

   fetch gce_instance
    | { metric 'compute.googleapis.com/instance/disk/write_bytes_count'
        | group_by []
      ; metric 'compute.googleapis.com/instance/disk/max_write_bytes_count'
        | group_by [] }
    | outer_join 0
    | add
  

• Se le etichette delle due tabelle corrispondono o se la seconda tabella contiene un'etichetta non trovata nella prima tabella, il join esterno è consentito. Ad esempio, la seguente query non causa un errore anche se l'etichetta metric.instance_name è presente nella seconda tabella, ma non nella prima:

   fetch gce_instance
    | { metric 'compute.googleapis.com/instance/disk/max_write_bytes_count'
      ; metric 'compute.googleapis.com/instance/disk/write_bytes_count' }
    | outer_join 0
    | sub
  

  Una serie temporale trovata nella prima tabella potrebbe avere valori delle etichette corrispondenti a più serie temporali nella seconda tabella, pertanto MQL esegue l'operazione di sottrazione per ogni accoppiamento.

Time shifting

A volte potresti voler confrontare ciò che sta succedendo ora con quello che è successo in passato. Per consentirti di confrontare i dati passati con quelli attuali, MQL fornisce l'operazione tabella time_shift per spostare i dati dal passato al periodo di tempo attuale.

Rapporti nel tempo

La seguente query utilizza time_shift, join e div per calcolare il rapporto dell'utilizzo medio in ciascuna zona tra oggi e una settimana prima.

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by [zone], mean(val())
| {
    ident
  ;
    time_shift 1w
  }
| join | div

Il seguente grafico mostra un possibile risultato di questa query:

Le prime due operazioni recuperano le serie temporali e le raggruppano per zona, calcolando i valori medi di ciascuna. La tabella risultante viene quindi passata a due operazioni. La prima operazione, ident, passa la tabella senza modifiche.

La seconda operazione, time_shift, aggiunge il periodo (1 settimana) ai timestamp per i valori nella tabella, in modo da spostare i dati da una settimana prima in poi. In questo modo, i timestamp per i dati meno recenti nella seconda tabella sono allineati con i timestamp dei dati attuali nella prima tabella.

La tabella invariata e quella spostata in base al tempo vengono quindi combinate utilizzando un elemento join interno. join produce una tabella di serie temporali in cui ogni punto ha due valori: l'utilizzo attuale e l'utilizzo una settimana prima. La query utilizza quindi l'operazione div per calcolare il rapporto tra il valore attuale e quello della settimana.

Dati passati e presenti

Combinando time_shift e union, puoi creare un grafico che mostra i dati passati e quelli attuali contemporaneamente. Ad esempio, la seguente query restituisce l'utilizzo medio complessivo ora e di una settimana prima. Utilizzando union, puoi visualizzare questi due risultati sullo stesso grafico.

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by []
| {
     add [when: "now"]
  ;
     add [when: "then"] | time_shift 1w
  }
| union

Il seguente grafico mostra un possibile risultato di questa query:

Questa query recupera le serie temporali, quindi utilizza group_by [] per combinarle in un'unica serie temporale senza etichette, lasciando i punti dati di utilizzo della CPU. Questo risultato viene passato a due operazioni. La prima aggiunge una colonna per una nuova etichetta chiamata when con il valore now. Il secondo aggiunge un'etichetta chiamata when con il valore then e passa il risultato all'operazione time_shift per spostare i valori di una settimana. Questa query utilizza il modificatore di mappa add; consulta Maps per ulteriori informazioni.

Le due tabelle, ciascuna contenente dati per una singola serie temporale, vengono passate a union, che produce una tabella contenente le serie temporali da entrambe le tabelle di input.

Passaggi successivi

Per una panoramica delle strutture linguistiche MQL, consulta Informazioni sul linguaggio MQL.

Per una descrizione completa di MQL, consulta la pagina di riferimento su Monitoring Query Language.

Per informazioni sull'interazione con i grafici, vedi Utilizzo dei grafici.