Utilizzo di MQL dall'API Monitoring

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

In questa pagina viene descritto come fornire query di Monitoring Query Language (MQL) all'API Cloud Monitoring.

Questa pagina non illustra la creazione delle query MQL. Per una serie di query di esempio, consulta la sezione Esempi. Riferimento referente MQL fornisce un riferimento completo per la lingua.

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

Utilizzare MQL dall'API

Puoi fornire query MQL nelle seguenti posizioni nell'API Monitoring:

Recupero dei dati con timeSeries.query in corso...

Per recuperare i dati della serie temporale dall'API con una query MQL, utilizza il metodo timeSeries.query.

Il metodo timeSeries.query adotta una struttura minima simile alla seguente in JSON:

{
  "query": string
}

Per il valore del campo query, specifica una stringa in MQL:

{

  "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count
            | within 5m"
}

Per sperimentare con l'API, puoi utilizzare lo strumento Explorer API nella pagina di riferimento di timeSeries.query. Per un'introduzione allo strumento Explorer API, vedi Explorer API.

Un altro modo per provare l'API è inserire la query in un file di testo ed eseguire la query utilizzando curl. L'esempio seguente trasmette la query nel file query.json al metodo timeSeries.query:

curl -d @query.json -H "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" -X POST \
https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries:query

Per saperne di più sull'uso di curl, consulta Richiamare curl.

In caso di esito positivo, la query restituisce una tabella contenente le serie temporali richieste. La tabella è divisa in due componenti:

  • timeSeriesDescriptor descrive le chiavi delle etichette, i valori delle etichette e i punti dati nella tabella. Non contiene dati, ma semplicemente i dati.

  • timeSeriesData contiene i dati descritti nel descrittore delle serie temporali. Questi dati vengono presentati sotto forma di array di coppie.

    • Il primo elemento della coppia, labelValues, registra un insieme di valori per le etichette elencate nel descrittore della serie temporale.
    • La seconda, pointData, è un array incorporato di coppie valore/timestamp, che rappresentano i dati raccolti con il set di valori etichetta specificato.

La risposta, leggermente riformattata, è simile alla seguente:

[{
  "timeSeriesTable": {
    "timeSeriesDescriptor": {
      "labelDescriptors": [
        { "key": "resource.project_id" },
        { "key": "resource.zone" },
        { "key": "resource.instance_id" },
        { "key": "metric.instance_name" }
      ],
      "valueDescriptors": [
        {
          "key": "value.utilization",
          "valueType": "DOUBLE",
          "metricKind": "GAUGE"
        }
      ],
      "pointDescriptors": [
        {
          "key": "value.utilization",
          "valueType": "DOUBLE",
          "metricKind": "GAUGE"
        }
      ]
    },
    "timeSeriesData": [
      {
        "labelValues": [
          { "stringValue": "632526624816" },
          { "stringValue": "us-central1-a" },
          { "stringValue": "5106847938297466291" },
          { "stringValue": "gke-kuber-cluster-default-pool-6fe301a0-n8r9" }
        ],
        "pointData": [
          {
            "values": [
              {
                "doubleValue": 0.063896992710942874
              }
            ],
            "timeInterval": {
              "startTime": "1969-12-31T23:59:59.999999Z",
              "endTime": "2020-03-02T20:17:00Z"
            }
          },
          { ... additional value/timestamp pairs ...}
        ]
      },
      { ... additional labelValue/pointData pairs ...},
    ]
  }

Grafici degli edifici

Puoi utilizzare il metodo dashboards.create per creare in modo programmatico dashboard e i grafici che contengono.

L'unica differenza tra la creazione di grafici basati su MQL e altri grafici è il tipo di query TimeSeriesQuery che utilizzi per completare il set di dati del grafico.

Creazione di un grafico basato su MQL

Per le query MQL, utilizza la query come valore del campo stringa timeSeriesQueryLanguage nell'array DataSet del grafico.

Di seguito è riportata una semplice definizione di dashboard che include MQL:

{
  "displayName": "Dashboard for MQL chart (API)",
  "gridLayout": {
    "widgets": [
      {
        "title": "Min/Max Compute Engine CPU utilization",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | within(1h) | { top 1, max(val()) ; bottom 1, min(val()) } | union"
              },
              "plotType": "LINE",
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

In questo modo viene creata una dashboard denominata "Quartiere per grafico MQL (API)" nel tuo progetto. La dashboard contiene un grafico denominato "Utilizzo CPU/Min/Max" di Compute Engine, che mostra due righe, una per i valori più alti e una per la più bassa.

Il grafico mostra le serie temporali con i valori più alti e più bassi.

Per ulteriori informazioni su questa query di esempio, consulta Combinazione delle selezioni con union.

Creare un grafico

Puoi inserire il file JSON della dashboard in un file, quindi passarlo a gcloud beta monitoring dashboards create o utilizzare curl per pubblicarlo su https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards. Per ulteriori esempi, vedi Creare una dashboard. Per saperne di più sull'uso di curl, consulta Richiamare curl.

Per informazioni generali sulla creazione di grafici e dashboard, vedi Gestire le dashboard per API. Per il materiale di riferimento, consulta Dashboards.

Creazione di condizioni per i criteri di avviso

Puoi utilizzare il metodo alertPolicies.create per creare in modo programmatico i criteri di avviso.

L'unica differenza tra la creazione di criteri di avviso basati su MQL e altri criteri di avviso è il tipo di Condition che utilizzi. Altrimenti, potrai creare questi criteri come qualsiasi altro criterio di avviso.

Di seguito è riportata una semplice query MQL per una condizione dei criteri di avviso che verifica se l'utilizzo di CPU di Compute Engine supera il 15%:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by sliding(5m), mean(val())
| condition val() > 0.15 '10^2.%'

Per ulteriori informazioni sull'operazione di avviso MQL condition, consulta Criteri di avviso con MQL.

Creazione del criterio di avviso

Per creare un criterio di avviso basato su una query MQL, utilizza il tipo di condizione AlertPolicy MonitoringQueryLanguageCondition. MonitoringQueryLanguageCondition ha la seguente struttura:

{
  "query":    string,
  "duration": string,
  "trigger":  {
    object (Trigger)
  }
}

Il valore del campo query è una stringa di query di avviso MQL in forma concisa o rigorosa. Gli esempi in questo documento sono in forma concisa. Per ulteriori informazioni, consulta le query di tipo Strict.

Il campo duration specifica il periodo di tempo durante il quale ogni valutazione della query deve generare un valore true prima che venga attivato il criterio di avviso. Per ulteriori informazioni, consulta la pagina Comportamento dei criteri di avviso basati su metriche. Il valore deve essere un numero di minuti, espresso in secondi, ad esempio 600s per una durata di 10 minuti.

Il campo trigger specifica quante serie temporali devono soddisfare la condizione durante il periodo duration, espressa come conteggio o percentuale. Il valore predefinito è un conteggio di 1. Per ulteriori informazioni, consulta Trigger.

Per la query di avviso di esempio, con una durata di 10 minuti e un numero di trigger di 1, la struttura ha il seguente aspetto:

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'",
  "duration": "600s",
  "trigger" : {
     "count": 1
  }
}

Utilizza questa struttura come valore di un campo conditionMonitoringQueryLanguage in una condizione, che a sua volta è incorporata in una struttura di criteri di avviso. Per scoprire di più su queste strutture, vedi AlertPolicy.

Di seguito è riportato un criterio minimo completo con una condizione MonitoringQueryLanguageCondition in JSON:

{
  "displayName":"Alert if CPU utilization exceeds 15% for 10 mins (MQL, API)",
  "combiner":"OR",
  "conditions":[
    {
      "displayName":"MQL-based utilization condition, API",

      "conditionMonitoringQueryLanguage":
      {
        "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'",
        "duration": "600s",
        "trigger" : {
           "count": 1
        },
     },
   }
  ],
}

Creazione di un criterio di avviso

Per creare il criterio, puoi inserire il file JSON del criterio di avviso in un file, quindi passare il file a gcloud alpha monitoring policies create o utilizzare curl per pubblicarlo su https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/alertPolicies.

Per ulteriori informazioni sull'API Monitoring per i criteri di avviso, consulta Gestire i criteri di avviso in base all'API.

Per saperne di più sull'uso di curl, consulta Richiamare curl.

Richiamare curl

Ogni chiamata curl include un insieme di argomenti, seguito dall'URL di una risorsa API. Gli argomenti comuni includono un ID progetto Google Cloud e un token di autenticazione. Questi valori sono rappresentati qui dalle variabili di ambiente PROJECT_ID e TOKEN.

Potrebbe essere necessario specificare anche altri argomenti, ad esempio il tipo di richiesta HTTP (ad esempio -X DELETE). La richiesta predefinita è GET, quindi non viene specificata negli esempi.

Ogni chiamata curl ha questa struttura generale:

curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

Per utilizzare curl, devi specificare l'ID progetto e un token di accesso. Per ridurre la digitazione e gli errori, puoi inserirli in variabili di ambiente, in modo che vengano trasmesse a curl in questo modo.

Per impostare queste variabili:

  1. Crea una variabile di ambiente per contenere l'ID del tuo progetto di definizione dell'ambito per un ambito delle metriche. Questi passaggi chiamano la variabile PROJECT_ID:

    PROJECT_ID=a-sample-project
    
  2. Esegui l'autenticazione con Google Cloud CLI:

    gcloud auth login
    
  3. Facoltativi. Per evitare di dover specificare l'ID progetto con ogni comando gcloud, imposta l'ID progetto come predefinito utilizzando l'interfaccia a riga di comando gcloud:

    gcloud config set project ${PROJECT_ID}
    
  4. Crea un token di autorizzazione e acquisiscilo in una variabile di ambiente. Questi passaggi chiamano la variabile TOKEN:

    TOKEN=`gcloud auth print-access-token`
    

    Il token di accesso deve essere aggiornato periodicamente. Se i comandi che hanno funzionato improvvisamente segnalano che non hai eseguito l'autenticazione, riesegui il comando.

  5. Per verificare di avere un token di accesso, fai eco alla variabile TOKEN:

    echo ${TOKEN}
    ya29.GluiBj8o....