Un criterio di avviso è rappresentato nell'API Cloud Monitoring
da un oggetto AlertPolicy
,
che descrive un insieme di condizioni che indicano uno stato potenzialmente
non corretto nel sistema.
In questo documento vengono descritte le seguenti informazioni:
- In che modo l'API Monitoring rappresenta i criteri di avviso.
- I tipi di condizioni forniti dall'API Monitoring per i criteri di avviso.
- Come creare un criterio di avviso utilizzando Google Cloud CLI o le librerie client.
Struttura di un criterio di avviso
La struttura AlertPolicy
definisce i componenti di un
criterio di avviso. Quando crei un criterio, specifichi i valori per i seguenti campi AlertPolicy
:
displayName
: un'etichetta descrittiva della norma.documentation
: ti consigliamo di utilizzare questo campo fornire informazioni che aiutino chi risponde agli eventi. Per saperne di più, consulta la sezione Annotare le notifiche con la documentazione definita dall'utente.userLabels
: eventuali etichette definite dall'utente associate al criterio. Per informazioni sull'utilizzo delle etichette con gli avvisi, consulta Annotare gli incidenti con le etichette.conditions[]
: un array di struttureCondition
.combiner
: un operatore logico che determina come gestire più le condizioni di traffico.notificationChannels[]
: un array di nomi di risorse, ognuno che identifica unNotificationChannel
.alertStrategy
: specifica quanto segue:- La velocità con cui il monitoraggio chiude gli incidenti quando i dati non arrivano più.
- Per i criteri di avviso basati su metriche, se Monitoraggio deve inviare una notifica quando un incidente è chiuso.
- Per i criteri di avviso basati su metriche, se le notifiche ripetute sono attivate e l'intervallo tra queste notifiche. Per ulteriori informazioni, consulta Configurare notifiche ripetute per i criteri di avviso basati su metriche.
Puoi anche specificare il campo severity
quando utilizzi l'API Cloud Monitoring
e la console Google Cloud. Questo campo consente di definire il livello di gravità
e i relativi incidenti. Se non specifichi una gravità, Cloud Monitoring imposta la gravità del criterio di avviso su No Severity
.
Esistono altri campi che puoi utilizzare, a seconda delle condizioni che crei.
Quando un criterio di avviso contiene una condizione, viene inviata una notifica se la condizione è soddisfatta. Per informazioni sulle notifiche quando i criteri di avviso contengono più condizioni, consulta Criteri con più condizioni e Numero di notifiche per criterio.
Quando crei o modifichi il criterio di avviso, Monitoring imposta
anche altri campi, tra cui il campo name
. Il valore dell'attributo name
è il nome della risorsa per il criterio di avviso, che identifica
. Il nome della risorsa ha il seguente formato:
projects/PROJECT_ID/alertPolicies/POLICY_ID
Tipi di condizioni nell'API
L'API Cloud Monitoring supporta diversi tipi di condizioni nella struttura Condition
. Esistono più tipi di condizioni per i criteri di avviso basati su metriche e uno per i criteri di avviso basati su log. Le sezioni seguenti descrivono i tipi di condizioni disponibili.
Condizioni per i criteri di avviso basati su metriche
Creare un criterio di avviso che monitori i dati delle metriche, inclusi quelli basati su log puoi utilizzare i seguenti tipi di condizioni:
Condizioni metriche basate su filtri
Le condizioni MetricAbsence
e MetricThreshold
utilizzano
Filtri di Monitoring per selezionare i dati delle serie temporali
da monitorare. Gli altri campi nella struttura delle condizioni specificano come filtrare,
raggruppare e aggregare i dati. Per ulteriori informazioni su questi concetti, consulta
Filtri e aggregazione: manipolazione delle serie temporali.
Se utilizzi il tipo di condizione MetricAbsence
, puoi creare una condizione
che viene soddisfatta solo quando tutte le serie temporali sono assenti. Questa condizione utilizza
Il parametro aggregations
per aggregare più serie temporali in un'unica
serie temporali. Per ulteriori informazioni, vedi
come riferimento a MetricAbsence
nella documentazione dell'API.
Un criterio di avviso per l'assenza di metriche richiede che alcuni dati siano stati scritti precedentemente. Per saperne di più, consulta Creare criteri di avviso per l'assenza di metriche.
Se vuoi ricevere notifiche in base a un valore previsto, configura
il criterio di avviso per utilizzare
tipo di condizione MetricThreshold
e per impostare forecastOptions
. Se questo campo non è impostato, i dati misurati vengono confrontati con una soglia.
Tuttavia, quando questo campo è impostato, i dati previsti vengono confrontati con un
soglia. Per ulteriori informazioni, vedi
Crea criteri di avviso relativi al valore della metrica previsti.
Condizioni delle metriche basate su MQL
La condizione MonitoringQueryLanguageCondition
utilizza Monitoring Query Language (MQL) per selezionare e manipolare i dati delle serie temporali da monitorare. Puoi creare avvisi
Criteri che confrontano i valori con una soglia o verificano l'assenza
di valori con questo tipo di condizione.
Se utilizzi una condizione MonitoringQueryLanguageCondition
, deve essere l'unica
condizione nel criterio di avviso. Per ulteriori informazioni, consulta Criteri di avviso con MQL.
Condizioni delle metriche basate su PromQL
La condizione PrometheusQueryLanguageCondition
utilizza query Prometheus Query Language (PromQL) per selezionare e manipolare i dati delle serie temporali da monitorare.
La condizione può calcolare un rapporto di metriche,
valutare confronti di metriche e altro ancora.
Se utilizzi una condizione PrometheusQueryLanguageCondition
, deve essere l'unica
nel criterio di avviso. Per ulteriori informazioni, vedi
Criteri di avviso con PromQL.
Condizioni per gli avvisi sui rapporti
Puoi creare criteri di avviso basati su soglie di metriche per monitorare il
rapporto tra due metriche. Puoi creare questi criteri utilizzando
il tipo di condizione MetricThreshold
o MonitoringQueryLanguageCondition
.
Puoi anche utilizzare MQL direttamente nella console Google Cloud. Non puoi creare
o gestire condizioni basate su rapporti utilizzando l'interfaccia grafica per la creazione
condizioni di soglia.
Ti consigliamo di utilizzare MQL per creare criteri di avviso basati su un rapporto.
MQL consente di creare query più potenti e flessibili di quanto tu possa
utilizzando il tipo di condizione MetricTheshold
Filtri di monitoraggio.
Ad esempio, con una condizione MonitoringQueryLanguageCondition
, puoi calcolare il rapporto tra una metrica del misuratore e una metrica delta. Per esempi, consulta
Esempi di criteri di avviso MQL.
Se utilizzi la condizione MetricThreshold
, il numeratore e il denominatore
del rapporto devono avere lo stesso MetricKind
.
Per un elenco delle metriche e delle relative proprietà, consulta Elenchi di metriche.
In generale, è preferibile calcolare i rapporti in base alle serie temporali raccolte per un singolo tipo di metrica utilizzando i valori delle etichette. Un rapporto calcolato su due diversi tipi di metriche è soggetto ad anomalie a causa di periodi di campionatura diversi e finestre di allineamento.
Ad esempio, supponiamo che tu abbia due tipi di metriche diversi, un conteggio totale delle RPC e un conteggio degli errori RPC, e che tu voglia calcolare il rapporto tra le RPC con conteggio degli errori e le RPC totali. Le chiamate RPC non riuscite vengono conteggiate nelle serie temporali di entrambi i tipi di metriche. Pertanto, esiste la possibilità che, quando allinei i tempi una RPC non riuscita non viene visualizzata nello stesso intervallo di allineamento entrambe le serie temporali. Questa differenza può verificarsi per diversi motivi, tra cui:
- Poiché esistono due diverse serie temporali che registrano lo stesso evento, sono due controvalori sottostanti che implementano la raccolta e che non vengono aggiornati a livello atomico.
- Le frequenze di campionamento potrebbero essere diverse. Quando le serie temporali sono allineate a un periodo comune, i conteggi di un singolo evento potrebbero apparire in intervalli di allineamento adiacenti nelle serie temporali per le diverse metriche.
La differenza nel numero di valori negli intervalli di allineamento corrispondenti può
Portano a valori di rapporto di error/total
privi di senso, come 1/0 o 2/1.
I rapporti di numeri maggiori hanno meno probabilità di generare valori senza senso. Puoi ottenere numeri più grandi tramite l'aggregazione, utilizzando una finestra di allineamento più lunga del periodo di campionamento o raggruppando i dati per determinate etichette. Queste tecniche riducono al minimo l'effetto di piccole differenze nel numero di punti in un intervallo dato. In altre parole, una disparità di due punti è maggiore significativa quando il numero previsto di punti in un intervallo è 3 rispetto a quando il numero previsto è 300.
Se utilizzi i tipi di metriche integrati, potresti non avere altra scelta i rapporti tra i vari tipi di metriche per ottenere il valore di cui hai bisogno.
Se stai progettando metriche personalizzate che potrebbero conteggiare la stessa cosa, ad esempio RPC che restituiscono lo stato di errore, in due metriche diverse, valuta la possibilità di utilizzare una singola metrica che includa ogni conteggio una sola volta. Ad esempio, supponiamo che che stai conteggiando le RPC e di voler monitorare il rapporto da RPC a tutte le RPC. Per risolvere il problema, crea un singolo tipo di metrica per conteggiare le RPC e utilizza un'etichetta per registrare lo stato dell'invocazione, incluso lo stato "OK". Ogni valore di stato, errore o "OK", viene registrato aggiornando un singolo contatore per la richiesta.
Condizione per i criteri di avviso basati su log
Per creare un criterio di avviso basato su log che ti invii una notifica quando un messaggio corrispondente al tuo filtro viene visualizzato nelle voci di log, utilizza il tipo di condizione LogMatch
. Se utilizzi una condizione LogMatch
, deve essere l'unica condizione nel criterio di avviso.
Non provare a utilizzare il tipo di condizione LogMatch
in combinazione con le
metriche basate su log. I criteri di avviso che monitorano le metriche basate su log sono basati su metriche
criteri. Per ulteriori informazioni sulla scelta tra criteri di avviso che monitorano le metriche o le voci di log basate su log, consulta Monitorare i log.
I criteri di avviso utilizzati negli esempi del documento Gestire i criteri di avviso per API sono criteri di avviso basati su metriche, anche se i principi sono gli stessi per i criteri di avviso basati su log. Per informazioni specifiche sui criteri di avviso basati su log, consulta Crea un criterio di avviso basato su log utilizzando l'API Monitoring nella documentazione di Cloud Logging.
Prima di iniziare
Prima di scrivere codice per l'API, devi:
- Acquisisci familiarità con i concetti generali e la terminologia utilizzati con i criteri di avviso. Per ulteriori informazioni, consulta la Panoramica degli avvisi.
- Assicurati che l'API Cloud Monitoring sia abilitata per l'uso. vedi Per ulteriori informazioni, abilita l'API.
- Se prevedi di utilizzare le librerie client, installa le librerie per le lingue che vuoi usare; vedi Librerie client per i dettagli. Al momento, il supporto dell'API per gli avvisi è disponibile solo per C#, Go, Java, Node.js e Python.
Se prevedi di utilizzare Google Cloud CLI, installalo. Tuttavia, se utilizzi Cloud Shell, Google Cloud CLI sarà è già installata.
Qui sono riportati anche esempi che utilizzano l'interfaccia
gcloud
. Tieni presente che tutti gli esempigcloud
presuppongono che il progetto attuale abbia già impostato come target (gcloud config set project [PROJECT_ID]
) quindi le chiamate omettono il flag--project
esplicito. L'ID del progetto corrente negli esempi èa-gcp-project
.
-
Per ottenere le autorizzazioni necessarie per creare e modificare i criteri di avviso utilizzando l'API Cloud Monitoring, chiedi all'amministratore di concederti Ruolo IAM Monitoring AlertPolicy Editor (
roles/monitoring.alertPolicyEditor
) per il tuo progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Per informazioni dettagliate sui ruoli IAM per il monitoraggio, consulta Controllare l'accesso con Identity and Access Management.
Progetta l'applicazione per le chiamate API Cloud Monitoring a thread singolo che modificano lo stato di un criterio di avviso in un progetto Google Cloud. Ad esempio, chiamate API a thread singolo che creano, aggiornano o eliminare un criterio di avviso.
Crea un criterio di avviso
Per creare un criterio di avviso in un progetto, utilizza
alertPolicies.create
. Per informazioni su come richiamare questo metodo, sui relativi parametri e sui dati di risposta, consulta la pagina di riferimento alertPolicies.create
.
Puoi creare criteri da file JSON o YAML.
Google Cloud CLI accetta questi file come argomenti
puoi leggere i file JSON in modo programmatico, convertirli in AlertPolicy
oggetti e creare criteri a partire da questi
utilizzando il metodo alertPolicies.create
. Se hai un file di configurazione JSON o YAML di Prometheus con una regola di avviso, l'interfaccia a riga di comando gcloud può eseguirne la migrazione a un criterio di avviso di Cloud Monitoring con una condizione PromQL. Per ulteriori informazioni, consulta la pagina Eseguire la migrazione di regole e ricevitori di avviso da Prometheus.
Ogni criterio di avviso appartiene a un progetto di definizione dell'ambito relativo a un ambito delle metriche. Ogni progetto può contenere fino a 500 criteri.
Per le chiamate API, devi fornire un "ID progetto". utilizza la
ID del progetto di definizione dell'ambito di un ambito delle metriche come valore. In questi esempi,
l'ID del progetto di definizione dell'ambito di un ambito delle metriche è a-gcp-project
.
Gli esempi riportati di seguito illustrano la creazione di criteri di avviso, ma come creare un file JSON o YAML che descriva un criterio di avviso. Gli esempi presuppongono invece che esista un file in formato JSON e illustrano come eseguire la chiamata API. Per esempi di file JSON, consulta Criteri di esempio. Per informazioni generali sul monitoraggio dei rapporti delle metriche, consulta Rapporti delle metriche.
gcloud
Per creare un criterio di avviso in un progetto, utilizza il comando gcloud alpha monitoring
policies create
. L'esempio seguente crea un criterio di avviso in
a-gcp-project
dal file rising-cpu-usage.json
:
gcloud alpha monitoring policies create --policy-from-file="rising-cpu-usage.json"
Se l'esito è positivo, questo comando restituisce il nome del nuovo criterio, ad esempio:
Created alert policy [projects/a-gcp-project/alertPolicies/12669073143329903307].
Il file rising-cpu-usage.json
contiene il codice JSON di un criterio con
il nome visualizzato "High CPU rate of change". Per maggiori dettagli su queste norme, consulta
Criterio di tasso di modifica.
Consulta le
gcloud alpha monitoring policies create
di riferimento per ulteriori informazioni.
C#
Per autenticarti a Monitoraggio, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Go
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per autenticarti in Monitoraggio, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per autenticarti a Monitoraggio, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
PHP
Per autenticarti a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per autenticarti a Monitoraggio, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale.
L'oggetto AlertPolicy
creato avrà campi aggiuntivi.
Il criterio stesso avrà i campi name
, creationRecord
e mutationRecord
. Inoltre, a ogni condizione del criterio viene assegnato anche un name
.
Questi campi non possono essere modificati esternamente, quindi non è necessario impostarli
quando crei un criterio. Nessuno degli esempi JSON utilizzati per creare
i criteri che li includono, ma se i criteri creati da questi vengono recuperati dopo
verranno visualizzati i campi.
Configurare notifiche ripetute per i criteri di avviso basati su metriche
Per impostazione predefinita, un criterio di avviso basato su metriche invia una notifica a ogni canale di notifica quando viene aperto un incidente. Tuttavia, puoi modificare il comportamento predefinito e configurare un criterio di avviso per inviare nuovamente le notifiche a tutti o ad alcuni dei canali di notifica per il criterio di avviso. Queste notifiche ripetute vengono inviate per gli incidenti con lo stato Aperto o Confermato. L'intervallo tra queste notifiche deve essere di almeno 30 minuti e non più di 24 ore, espresse in secondi.
Per configurare le notifiche ripetute, aggiungi alla configurazione del criterio di avviso un oggetto AlertStrategy
contenente almeno un oggetto NotificationChannelStrategy
.
Un oggetto NotificationChannelStrategy
ha due campi:
renotifyInterval
: l'intervallo, in secondi, tra notifiche.Se modifichi il valore del campo
renotifyInterval
quando viene aperto un incidente per il criterio di avviso, si verifica quanto segue:- Il criterio di avviso invia un'altra notifica per l'incidente.
- Il criterio di avviso riavvia il periodo dell'intervallo.
notificationChannelNames
: un array di nomi delle risorse del canale di notifica, ovvero stringhe nel formatoprojects/PROJECT_ID/notificationChannels/CHANNEL_ID
, dove CHANNEL_ID è un valore numerico. Per informazioni su come recuperare l'ID canale, consulta Elenco dei canali di notifica in un progetto.
Ad esempio, il seguente esempio JSON mostra una strategia di avviso configurata per inviare notifiche ripetute ogni 1800 secondi (30 minuti) a un canale di notifica:
"alertStrategy": { "notificationChannelStrategy": [ { "notificationChannelNames": [ "projects/PROJECT_ID/notificationChannels/CHANNEL_ID" ], "renotifyInterval": "1800s" } ] }
Per interrompere temporaneamente le notifiche ripetute, crea una posticipazione. A
impedire notifiche ripetute, modificare il criterio di avviso utilizzando l'API e
rimuovi l'oggetto NotificationChannelStrategy
.