Criteri di esempio in JSON

Questo documento fornisce esempi di criteri di avviso. Gli esempi sono scritti in JSON e utilizzano i filtri di Monitoring. Puoi creare i criteri in formato JSON o YAML, a prescindere dal fatto che tu li definisca utilizzando i filtri di Monitoring o Monitoring Query Language (MQL). Google Cloud CLI può leggere e scrivere sia JSON che YAML, mentre l'API REST può leggere JSON.

Per esempi di criteri di avviso che utilizzano MQL, consulta i seguenti documenti:

Per informazioni su come configurare i campi criterio di avviso, consulta quanto segue:

Genera YAML per i criteri esistenti

Per generare rappresentazioni YAML dei criteri di avviso esistenti, utilizza il comando gcloud alpha monitoring policies list per elencare i criteri e il comando gcloud alpha monitoring policies describe per stampare il criterio.

Per generare rappresentazioni YAML dei canali di notifica esistenti, utilizza il comando gcloud alpha monitoring channels list per elencare i tuoi canali e il comando gcloud alpha monitoring channels describe per stampare la configurazione del canale.

Se non includi il flag --format nei comandi Google Cloud CLI, il formato predefinito sarà YAML per entrambi i comandi gcloud ... describe.

Ad esempio, il seguente comando gcloud alpha monitoring policies describe recupera un singolo criterio denominato projects/a-gcp-project/alertPolicies/12669073143329903307 e il reindirizzamento (>) copia l'output nel file test-policy.yaml:

gcloud alpha monitoring policies describe projects/a-gcp-project/alertPolicies/12669073143329903307 > test-policy.yaml

Genera JSON per i criteri esistenti

Per generare rappresentazioni JSON dei criteri di avviso e dei canali di notifica esistenti, procedi in uno dei seguenti modi:

Esempi di criteri

Come mostrato nell'esempio di backup/ripristino, puoi utilizzare le norme salvate per creare nuove copie di queste norme.

Puoi utilizzare un criterio salvato in un progetto per creare un criterio nuovo o simile in un altro progetto. Tuttavia, devi prima apportare le seguenti modifiche in una copia della norma salvata:

  • Rimuovi i seguenti campi da tutti i canali di notifica:
    • name
    • verificationStatus
  • Crea canali di notifica prima di fare riferimento ai canali nelle norme di avviso (sono necessari i nuovi identificatori dei canali).
  • Rimuovi i seguenti campi da tutti i criteri di avviso che stai ricreando:
    • name
    • condition.name
    • creationRecord
    • mutationRecord

I criteri in questo documento sono organizzati utilizzando la stessa terminologia utilizzata da Monitoring nella console Google Cloud, ad esempio "criterio del tasso di modifica", e esistono due tipi di condizioni:

  • Una condizione di soglia; quasi tutti i tipi di criteri menzionati nell'interfaccia utente sono varianti di una condizione di soglia.
  • Una condizione di assenza

Nei campioni che seguono, queste condizioni corrispondono a conditionThreshold e conditionAbsent. Per maggiori informazioni, consulta la pagina di riferimento per Condition.

Puoi creare molti di questi criteri manualmente utilizzando la console Google Cloud, ma alcuni possono essere creati solo utilizzando l'API Monitoring. Per saperne di più, consulta Creare un criterio di avviso (UI) o Creare criteri di avviso utilizzando l'API.

Criterio di soglia di metriche

Un criterio di soglia di metriche rileva quando un valore supera un limite prestabilito. I criteri di soglia ti informano che si sta avvicinando un punto importante, quindi puoi intervenire. Ad esempio, la condizione per un criterio di soglia di soglia delle metriche viene soddisfatta quando lo spazio su disco disponibile diventa inferiore al 10% dello spazio su disco totale.

Il seguente criterio di avviso utilizza l'utilizzo medio della CPU come indicatore dell'integrità di un gruppo di VM. La condizione del criterio si verifica quando l'utilizzo medio della CPU delle VM in un progetto, misurato a intervalli di 60 secondi, supera la soglia del 90% di utilizzo per 15 minuti (900 secondi):

{
    "displayName": "Very high CPU usage",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "CPU usage is extremely high",
            "conditionThreshold": {
                "aggregations": [
                    {
                        "alignmentPeriod": "60s",
                        "crossSeriesReducer": "REDUCE_MEAN",
                        "groupByFields": [
                            "project"
                        ],
                        "perSeriesAligner": "ALIGN_MAX"
                    }
                ],
                "comparison": "COMPARISON_GT",
                "duration": "900s",
                "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
                          AND resource.type=\"gce_instance\"",
                "thresholdValue": 0.9,
                "trigger": {
                    "count": 1
                }
            }
        }
    ],
}

Criterio di assenza di metriche

Una condizione di assenza di metriche è soddisfatta quando non vengono scritti dati in una metrica per la durata specificata.

Un modo per dimostrarlo è creare una metrica personalizzata.

Di seguito è riportato un descrittore di esempio per una metrica personalizzata. Puoi creare la metrica utilizzando Explorer API.

{
  "description": "Number of times the pipeline has run",
  "displayName": "Pipeline runs",
  "metricKind": "GAUGE",
  "type": "custom.googleapis.com/pipeline_runs",
  "labels": [
    {
      "description": "The name of the pipeline",
      "key": "pipeline_name",
      "valueType": "STRING"
    },
  ],
  "unit": "1",
  "valueType": "INT64"
}

Per saperne di più, consulta Panoramica delle metriche definite dall'utente.

La condizione nel seguente criterio di avviso viene soddisfatta quando i dati smettono di essere scritti nella metrica per un periodo di circa un'ora: in altre parole, non è stato possibile eseguire la pipeline oraria. Tieni presente che la condizione utilizzata qui è conditionAbsent.

{
    "displayName": "Data ingestion functioning",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "Hourly pipeline is up",
            "conditionAbsent": {
                "duration": "3900s",
                "filter": "resource.type=\"global\"
                          AND metric.type=\"custom.googleapis.com/pipeline_runs\"
                          AND metric.label.pipeline_name=\"hourly\"",
            }
        }
    ],
}

Criterio di previsione

Una condizione di previsione si verifica quando tutte le previsioni effettuate per una serie temporale in una finestra di durata sono le stesse e prevede che le serie temporali violeranno la soglia all'interno dell'orizzonte di previsione.

Una condizione di previsione è una condizione di soglia di metriche configurata per utilizzare la previsione. Come illustrato nell'esempio seguente, queste condizioni includono un campo forecastOptions che consente di effettuare le previsioni e di specificare l'orizzonte di previsione. Nel seguente esempio, l'orizzonte di previsione è impostato su un'ora, ovvero il valore minimo:

{
    "displayName": "NFS free bytes alert",
    "combiner": "OR",
    "conditions": [
      {
        "displayName": "Filestore Instance - Free disk space percent",
        "conditionThreshold": {
          "aggregations": [
            {
              "alignmentPeriod": "300s",
              "perSeriesAligner": "ALIGN_MEAN"
            }
          ],
          "comparison": "COMPARISON_LT",
          "duration": "900s",
          "filter": "resource.type = \"filestore_instance\" AND metric.type = \"file.googleapis.com/nfs/server/free_bytes_percent\"",
          "forecastOptions": {
            "forecastHorizon": "3600s"
          },
          "thresholdValue": 20,
          "trigger": {
            "count": 1
          }
        }
      }
    ],
}

Norme relative al tasso di modifica

Le condizioni di frequenza di modifica vengono soddisfatte quando i valori in una serie temporale aumentano o diminuiscono almeno della percentuale specificata dalla soglia. Quando crei questo tipo di condizione, alla serie temporale viene applicato un calcolo della percentuale di variazione prima del confronto con la soglia.

La condizione calcola la media dei valori della metrica degli ultimi 10 minuti, quindi confronta il risultato con la media di 10 minuti misurata poco prima della finestra di durata. La finestra temporale di 10 minuti utilizzata da una condizione di modifica della frequenza metrica è un valore fisso e non puoi modificarla. Tuttavia, devi specificare la durata quando crei una condizione.

Questo criterio ti avvisa quando il tasso di utilizzo della CPU aumenta rapidamente:

{
  "displayName": "High CPU rate of change",
  "combiner": "OR",
  "conditions": [
    {
      "displayName": "CPU usage is increasing at a high rate",
      "conditionThreshold": {
         "aggregations": [
           {
             "alignmentPeriod": "900s",
             "perSeriesAligner": "ALIGN_PERCENT_CHANGE",
           }],
        "comparison": "COMPARISON_GT",
        "duration": "180s",
        "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" AND resource.type=\"gce_instance\"",
        "thresholdValue": 0.5,
        "trigger": {
          "count": 1
         }
      }
    }
  ],
}

Norme sui gruppi aggregati

Questo criterio ti avvisa quando l'utilizzo medio della CPU in un cluster Google Kubernetes Engine supera una soglia:

{
    "displayName": "CPU utilization across GKE cluster exceeds 10 percent",
    "combiner": "OR",
    "conditions": [
         {
            "displayName": "Group Aggregate Threshold across All Instances in Group GKE cluster",
            "conditionThreshold": {
                "filter": "group.id=\"3691870619975147604\" AND metric.type=\"compute.googleapis.com/instance/cpu/utilization\" AND resource.type=\"gce_instance\"",
                "comparison": "COMPARISON_GT",
                "thresholdValue": 0.1,
                "duration": "300s",
                "trigger": {
                    "count": 1
                },
                "aggregations": [
                    {
                        "alignmentPeriod": "60s",
                        "perSeriesAligner": "ALIGN_MEAN",
                        "crossSeriesReducer": "REDUCE_MEAN",
                        "groupByFields": [
                              "project"
                        ]
                    },
                    {
                        "alignmentPeriod": "60s",
                        "perSeriesAligner": "ALIGN_SUM",
                        "crossSeriesReducer": "REDUCE_MEAN"
                    }
                ]
            },
        }
    ],
}

Questo criterio presuppone l'esistenza del seguente gruppo:

    {
        "name": "projects/a-gcp-project/groups/3691870619975147604",
        "displayName": "GKE cluster",
        "filter": "resource.metadata.name=starts_with(\"gke-kuber-cluster-default-pool-6fe301a0-\")"
    }

Per identificare i campi equivalenti per i tuoi gruppi, elenca i dettagli del gruppo utilizzando Explorer API nella pagina di riferimento del progetto.groups.list.

Norme per i controlli di uptime

Lo stato dei controlli di uptime viene visualizzato nella pagina Controlli di uptime, ma è possibile configurare un criterio di avviso in modo che Cloud Monitoring invii una notifica se il controllo di uptime ha esito negativo.

Ad esempio, il codice JSON seguente descrive un controllo di uptime HTTPS sul sito Google Cloud. Il criterio di avviso verifica la disponibilità ogni 5 minuti.

Il controllo di uptime è stato creato con la console Google Cloud. La rappresentazione JSON qui è stata creata elencando i controlli di uptime nel progetto utilizzando l'API Monitoring. Vedi uptimeCheckConfigs.list. Puoi anche creare controlli di uptime con l'API Monitoring.

{
    "name": "projects/a-gcp-project/uptimeCheckConfigs/uptime-check-for-google-cloud-site",
    "displayName": "Uptime check for Google Cloud site",
    "monitoredResource": {
        "type": "uptime_url",
        "labels": {
            "host": "cloud.google.com"
      }
    },
    "httpCheck": {
        "path": "/index.html",
        "useSsl": true,
        "port": 443,
        "authInfo": {}
    },
    "period": "300s",
    "timeout": "10s",
    "contentMatchers": [
        {}
    ]
}

Per creare un criterio di avviso per un controllo di uptime, fai riferimento al controllo di uptime in base al relativo UPTIME_CHECK_ID. Questo ID viene impostato al momento della creazione del controllo, appare come ultimo componente del campo name ed è visibile nella UI come Check ID nel riepilogo della configurazione. Se utilizzi l'API Monitoring, il metodo uptimeCheckConfigs.create restituisce l'ID.

L'ID deriva da displayName, che in questo caso è stato impostato nella UI. Per verificarlo, elenca i controlli di uptime e osserva il valore di name.

L'ID per il controllo di uptime descritto in precedenza è uptime-check-for-google-cloud-site.

La seguente condizione del criterio di avviso è soddisfatta se il controllo di uptime non va a buon fine o se il certificato SSL sul sito Google Cloud scadrà tra meno di 15 giorni. Se una delle condizioni è soddisfatta, Monitoring invia una notifica al canale di notifica specificato:

{
    "displayName": "Google Cloud site uptime failure",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "Failure of uptime check_id uptime-check-for-google-cloud-site",
            "conditionThreshold": {
                "aggregations": [
                    {
                        "alignmentPeriod": "1200s",
                        "perSeriesAligner": "ALIGN_NEXT_OLDER",
                        "crossSeriesReducer": "REDUCE_COUNT_FALSE",
                        "groupByFields": [ "resource.label.*" ]
                    }
                ],
                "comparison": "COMPARISON_GT",
                "duration": "600s",
                "filter": "metric.type=\"monitoring.googleapis.com/uptime_check/check_passed\"
                          AND metric.label.check_id=\"uptime-check-for-google-cloud-site\"
                          AND resource.type=\"uptime_url\"",
                "thresholdValue": 1,
                "trigger": {
                    "count": 1
                }
            }
        },
        {
            "displayName": "SSL Certificate for google-cloud-site expiring soon",
            "conditionThreshold": {
                "aggregations": [
                    {
                        "alignmentPeriod": "1200s",
                        "perSeriesAligner": "ALIGN_NEXT_OLDER",
                        "crossSeriesReducer": "REDUCE_MEAN",
                        "groupByFields": [ "resource.label.*" ]
                    }
                ],
                "comparison": "COMPARISON_LT",
                "duration": "600s",
                "filter": "metric.type=\"monitoring.googleapis.com/uptime_check/time_until_ssl_cert_expires\"
                          AND metric.label.check_id=\"uptime-check-for-google-cloud-site\"
                          AND resource.type=\"uptime_url\"",
                "thresholdValue": 15,
                "trigger": {
                    "count": 1
                }
            }
        }
    ],
}

Il filtro nella condizione specifica la metrica monitorata in base al tipo e all'etichetta. I tipi di metriche sono monitoring.googleapis.com/uptime_check/check_passed e monitoring.googleapis.com/uptime_check/time_until_ssl_cert_expires. L'etichetta della metrica identifica lo specifico controllo di uptime monitorato. In questo esempio, il campo dell'etichetta check_id contiene l'ID del controllo di uptime.

AND metric.label.check_id=\"uptime-check-for-google-cloud-site\"

Per ulteriori informazioni, consulta la sezione Filtri di Monitoring.

Norme di integrità dei processi

Un criterio di integrità dei processi può avvisarti se il numero di processi che corrispondono a un pattern supera una soglia. Può essere utilizzato per indicare, ad esempio, che l'esecuzione di un processo è stata interrotta.

Questo criterio di avviso fa sì che Monitoring invii una notifica al canale di notifica specificato quando nessun processo corrispondente alla stringa nginx, in esecuzione come utente www, è disponibile per più di 5 minuti:

{
    "displayName": "Server health",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "Process 'nginx' is not running",
            "conditionThreshold": {
                "filter": "select_process_count(\"has_substring(\\\"nginx\\\")\", \"www\") AND resource.type=\"gce_instance\"",
                "comparison": "COMPARISON_LT",
                "thresholdValue": 1,
                "duration": "300s"
            }
        }
    ],
}

Per maggiori informazioni, consulta la sezione Stato del processo.

Rapporto metriche

Ti consigliamo di utilizzare Monitoring Query Language (MQL) per creare criteri di avviso basati su rapporto. Sebbene l'API Cloud Monitoring supporti la creazione di alcuni rapporti basati su filtri, MQL offre una soluzione più flessibile e solida:

Questa sezione descrive il rapporto basato su filtri. Con l'API puoi creare e visualizzare un criterio che calcola il rapporto di due metriche correlate e si attiva quando il rapporto supera una soglia. Le metriche correlate devono avere lo stesso valore MetricKind. Ad esempio, puoi creare un criterio di avviso basato su rapporto se entrambe le metriche sono metriche di misurazione. Per determinare il MetricKind di un tipo di metrica, consulta l'elenco delle metriche.

Una condizione di rapporto è una variante di una condizione di soglia semplice, in cui la condizione in un criterio di rapporto utilizza due filtri: il consueto filter, che funge da numeratore del rapporto, e denominatorFilter, che funge da denominatore del rapporto.

Le serie temporali di entrambi i filtri devono essere aggregate nello stesso modo, in modo che il calcolo del rapporto dei valori sia significativo. La condizione del criterio di avviso è soddisfatta quando il rapporto dei due filtri viola un valore di soglia per la durata specificata.

La sezione successiva descrive come configurare un criterio di avviso che monitori il rapporto tra le risposte di errore HTTP e tutte le risposte HTTP.

Rapporto errori HTTP

Il seguente criterio di avviso ha una condizione di soglia basata sul rapporto tra il numero di risposte di errore HTTP e il numero di tutte le risposte HTTP.

{
    "displayName": "HTTP error count exceeds 50 percent for App Engine apps",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "Ratio: HTTP 500s error-response counts / All HTTP response counts",
            "conditionThreshold": {
                 "filter": "metric.label.response_code>=\"500\" AND
                            metric.label.response_code<\"600\" AND
                            metric.type=\"appengine.googleapis.com/http/server/response_count\" AND
                            project=\"a-gcp-project\" AND
                            resource.type=\"gae_app\"",
                 "aggregations": [
                    {
                        "alignmentPeriod": "300s",
                        "crossSeriesReducer": "REDUCE_SUM",
                        "groupByFields": [
                          "project",
                          "resource.label.module_id",
                          "resource.label.version_id"
                        ],
                        "perSeriesAligner": "ALIGN_DELTA"
                    }
                ],
                "denominatorFilter": "metric.type=\"appengine.googleapis.com/http/server/response_count\" AND
                                      project=\"a-gcp-project\" AND
                                      resource.type=\"gae_app\"",
                "denominatorAggregations": [
                   {
                      "alignmentPeriod": "300s",
                      "crossSeriesReducer": "REDUCE_SUM",
                      "groupByFields": [
                        "project",
                        "resource.label.module_id",
                        "resource.label.version_id"
                       ],
                      "perSeriesAligner": "ALIGN_DELTA",
                    }
                ],
                "comparison": "COMPARISON_GT",
                "thresholdValue": 0.5,
                "duration": "0s",
                "trigger": {
                    "count": 1
                }
            }
        }
    ]
}

La metrica e i tipi di risorse

Il tipo di metrica per questo criterio è appengine.googleapis.com/http/server/response_count, che ha due etichette:

  • response_code, un numero intero a 64 bit che rappresenta il codice di stato HTTP della richiesta. Questo criterio filtra i dati delle serie temporali in questa etichetta, in modo da poter determinare quanto segue:
    • Il numero di risposte ricevute.
    • Il numero di risposte di errore ricevute.
    • Il rapporto tra le risposte di errore rispetto a tutte le risposte.
  • loading, un valore booleano che indica se la richiesta era in fase di caricamento. L'etichetta loading non è pertinente in questo criterio di avviso.

Il criterio di avviso valuta i dati di risposta delle app App Engine, ovvero i dati provenienti dal tipo di risorsa monitorata gae_app. Questa risorsa monitorata ha tre etichette:

  • project_id, l'ID del progetto Google Cloud.
  • module_id, il nome del servizio o del modulo nell'app.
  • version_id, la versione dell'app.

Per informazioni di riferimento su queste metriche e sui tipi di risorse monitorate, consulta le metriche di App Engine nell'elenco delle metriche e la voce gae_app nell'elenco delle risorse monitorate.

Cosa fanno queste norme

Questa condizione calcola il rapporto tra le risposte di errore e le risposte totali. La condizione è soddisfatta se il rapporto è superiore al 50% (ossia, il rapporto è maggiore di 0,5) nel periodo di allineamento di 5 minuti.

Questo criterio acquisisce il modulo e la versione dell'app che viola la condizione raggruppando le serie temporali in ogni filtro in base ai valori di queste etichette.

  • Il filtro nella condizione esamina le risposte HTTP di un'app App Engine e seleziona le risposte nell'intervallo di errori 5xx. Questo è il numeratore nel rapporto.
  • Il filtro denominatore nella condizione esamina tutte le risposte HTTP da un'app App Engine.

La condizione è soddisfatta e Monitoring invia immediatamente una notifica per il nuovo incidente. La durata consentita per la condizione è pari a zero secondi. Questa condizione utilizza il conteggio trigger pari a 1, ovvero il numero di serie temporali che devono violare la condizione per causare l'incidente. Per un'app App Engine con un singolo servizio, il conteggio trigger di uno è consentito. Se hai un'app con 20 servizi e vuoi causare un incidente se tre o più servizi violano la condizione, utilizza un conteggio trigger pari a 3.

Impostazione di un rapporto

I filtri per numeratore e denominatore sono esattamente gli stessi, ad eccezione del fatto che il filtro di condizione nel numeratore corrisponde ai codici di risposta compresi nell'intervallo di errori e il filtro di condizione al denominatore corrisponde a tutti i codici di risposta. Le seguenti clausole appaiono solo nella condizione del numeratore:

      metric.label.response_code>=\"500\" AND
      metric.label.response_code<\"600\"

In caso contrario, i filtri per numeratore e denominatore sono gli stessi.

Le serie temporali selezionate da ciascun filtro devono essere aggregate nello stesso modo per rendere valido il calcolo del rapporto. Poiché esistono diverse serie temporali per ogni combinazione di valori delle etichette, ogni filtro potrebbe raccogliere più serie temporali. Questo criterio raggruppa l'insieme di serie temporali in base a specifiche etichette delle risorse, che partizionano l'insieme di serie temporali in un insieme di gruppi. Alcune delle serie temporali in ogni gruppo corrispondono al filtro del numeratore, le altre corrispondono al filtro del denominatore.

Per calcolare un rapporto, l'insieme di serie temporali che corrisponde a ciascun filtro deve essere aggregato in una singola serie temporale ciascuna. In questo modo ogni gruppo ha due serie temporali, una per il numeratore e una per il denominatore. Successivamente, puoi calcolare il rapporto dei punti nelle serie temporali del numeratore e del denominatore in ogni gruppo.

In questo criterio, le serie temporali di entrambi i filtri vengono aggregate come segue:

  • Ogni filtro crea un numero di serie temporali allineate a intervalli di 5 minuti, con i valori rappresentati che calcolano ALIGN_DELTA sui valori in quell'intervallo di allineamento di 5 minuti. Questo allineatore restituisce il numero di risposte corrispondenti in quell'intervallo sotto forma di numero intero a 64 bit.

  • Le serie temporali all'interno di ciascun filtro vengono anche raggruppate in base ai valori delle etichette delle risorse per modulo e versione, pertanto ogni gruppo contiene due insiemi di serie temporali allineate: quelle corrispondenti al filtro numeratore e quelle corrispondenti al filtro denominatore.

  • Le serie temporali all'interno di ogni gruppo che corrispondono al filtro del numeratore o del denominatore vengono aggregate per una sola volta sommando i valori delle singole serie temporali utilizzando il riduttore di serie incrociate REDUCER_SUM. Ne risultano una serie temporale per il numeratore e una per il denominatore, ciascuna che riporta il numero di risposte in tutte le serie temporali corrispondenti nell'intervallo di allineamento.

Il criterio calcola quindi, per le serie temporali del numeratore e del denominatore che rappresenta ogni gruppo, il rapporto dei valori. Una volta disponibile il rapporto, questo criterio è un semplice criterio relativo alla soglia di metrica.