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 integro nel sistema.
Questo documento descrive quanto segue:
- Il modo in cui 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
: qualsiasi informazione fornita per aiutare chi risponde. Questo campo è facoltativo. L'oggettodocumentation
include quanto segue:content
: testo definito dall'utente visualizzato nel corpo della notifica.subject
: l'oggetto della notifica. La lunghezza dell'oggetto non può superare i 255 caratteri.
userLabels
: qualsiasi etichetta definita dall'utente associata al criterio. Per informazioni sull'utilizzo delle etichette con gli avvisi, consulta Annotare gli avvisi con etichette.conditions[]
: un array di struttureCondition
.combiner
: un operatore logico che determina come gestire più condizioni.notificationChannels[]
: un array di nomi di risorse, ognuno dei quali identifica unNotificationChannel
.alertStrategy
: specifica la velocità con cui Monitoring chiude gli incidenti all'arrivo dei dati. Questo oggetto specifica inoltre se le notifiche ripetute sono abilitate per gli avvisi basati su metriche e l'intervallo tra queste notifiche. Per maggiori informazioni, consulta Inviare notifiche ripetute.
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à degli 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 create.
Quando un criterio di avviso contiene una condizione, viene inviata una notifica quando questa 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 del campo name
è il nome della risorsa per il criterio di avviso, che identifica il criterio. 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 seguenti sezioni descrivono i tipi di condizioni disponibili.
Condizioni per i criteri di avviso basati su metriche
Per creare un criterio di avviso che monitori i dati delle metriche, incluse le metriche basate su log, puoi utilizzare i seguenti tipi di condizioni:
Condizioni delle metriche basate su filtro
Le condizioni MetricAbsence
e MetricThreshold
utilizzano i
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
Filtro e aggregazione: manipolazione delle serie temporali.
Se utilizzi il tipo di condizione MetricAbsence
, puoi creare una condizione
soddisfatta solo quando tutte le serie temporali sono assenti. Questa condizione utilizza il parametro aggregations
per aggregare più serie temporali in un'unica serie temporale. Per ulteriori informazioni, consulta il riferimento MetricAbsence
nella documentazione dell'API.
Un criterio di avviso per l'assenza di metriche richiede che alcuni dati siano stati scritti in precedenza. 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 in modo da utilizzare il tipo di condizione MetricThreshold
e impostare il campo forecastOptions
. Se questo campo non è impostato, i dati misurati vengono confrontati con una soglia.
Tuttavia, se questo campo viene impostato, i dati previsti vengono confrontati con una soglia. Per ulteriori informazioni, consulta Creare criteri di avviso per i valori delle metriche previste.
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 criteri di avviso per confrontare i valori con una soglia o verificare l'assenza di valori con questo tipo di condizione.
Se utilizzi una condizione MonitoringQueryLanguageCondition
, deve essere l'unica condizione nel criterio di avviso. Per maggiori informazioni, consulta
Criteri di avviso con MQL.
Condizioni delle metriche basate su PromQL
La condizione PrometheusQueryLanguageCondition
utilizza le query Prometheus Query Language (PromQL) per selezionare e manipolare i dati delle serie temporali da monitorare. Puoi creare
una query semplice o complessa e utilizzare strutture di query come soglie dinamiche, rapporti, confronti di metriche e altro ancora.
Se utilizzi una condizione PrometheusQueryLanguageCondition
, deve essere l'unica condizione nel criterio di avviso. Per maggiori informazioni, consulta
Criteri di avviso con PromQL.
Condizioni per gli avvisi sui rapporti
Puoi creare criteri di avviso per soglia 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 rapporto utilizzando l'interfaccia grafica per la creazione di condizioni di soglia.
Ti consigliamo di utilizzare MQL per creare criteri di avviso basati su rapporto.
MQL ti consente di creare query più efficaci e flessibili di quelle che puoi creare utilizzando il tipo di condizione MetricTheshold
e i filtri di Monitoring.
Ad esempio, con una condizione MonitoringQueryLanguageCondition
, puoi calcolare il rapporto tra una metrica indicatore e una metrica delta. Per alcuni esempi, consulta la pagina relativa agli 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 in base a due diversi tipi di metriche è soggetto ad anomalie dovute a periodi di campionamento e finestre di allineamento differenti.
Ad esempio, supponiamo di avere due diversi tipi di metriche, un conteggio totale RPC e un conteggio degli errori RPC, e di voler calcolare il rapporto tra le RPC per il numero di errori e le RPC totali. Le RPC non riuscite vengono conteggiate nella serie temporale di entrambi i tipi di metriche. Pertanto, è possibile che, quando allinei le serie temporali, una RPC non riuscita non venga visualizzata nello stesso intervallo di allineamento per entrambe le serie temporali. Questa differenza può verificarsi per diversi motivi, tra cui:
- Poiché due serie temporali registrano lo stesso evento, esistono due valori contatore sottostanti che implementano la raccolta e non vengono aggiornati a livello atomico.
- Le frequenze di campionamento potrebbero variare. Quando le serie temporali sono allineate a un periodo comune, i conteggi per un singolo evento potrebbero essere visualizzati negli intervalli di allineamento adiacenti nelle serie temporali per le diverse metriche.
La differenza nel numero di valori negli intervalli di allineamento corrispondenti può
portare a valori del rapporto error/total
insensati, come 1/0 o 2/1.
I rapporti dei numeri maggiori hanno meno probabilità di generare valori incomprensibili. Puoi ottenere numeri più elevati per 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 dato intervallo. In altre parole, una disparità di due punti è più significativa quando il numero previsto di punti in un intervallo è 3 rispetto a quando il numero previsto è 300.
Se usi tipi di metriche integrate, potresti non avere altra scelta che calcolare i rapporti tra i tipi di metriche per ottenere il valore di cui hai bisogno.
Se stai progettando metriche personalizzate che potrebbero conteggiare gli stessi elementi, ad esempio gli RPC che restituiscono lo stato di errore, in due metriche diverse, prendi in considerazione una sola metrica, che include ogni conteggio una sola volta. Ad esempio, supponi di conteggiare le RPC e di voler monitorare il rapporto tra le RPC non riuscite e 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 della chiamata, incluso lo stato "OK". Quindi, ogni valore dello stato, errore o "OK", viene registrato aggiornando un singolo contatore per quel caso.
Condizione per i criteri di avviso basati su log
Per creare un criterio di avviso basato su log, che ti invii una notifica quando nelle voci di log viene visualizzato un messaggio corrispondente al filtro, 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
insieme alle metriche basate su log. I criteri di avviso per il monitoraggio delle metriche basate su log sono quelli basati su metriche. Per ulteriori informazioni sulla scelta tra criteri di avviso che monitorano le metriche o le voci di log basate su log, consulta Monitoraggio dei log.
I criteri di avviso utilizzati negli esempi del documento Gestisci i criteri di avviso per API sono criteri di avviso basati su metriche, sebbene i principi siano gli stessi per i criteri di avviso basati su log. Per informazioni specifiche sui criteri di avviso basati su log, consulta Creare un avviso basato su log utilizzando l'API Monitoring nella documentazione di Cloud Logging.
Prima di iniziare
Prima di scrivere codice nell'API, devi:
- Acquisire familiarità con i concetti generali e la terminologia utilizzati con i criteri di avviso; consulta Panoramica degli avvisi per ulteriori informazioni.
- Assicurati che l'API Cloud Monitoring sia abilitata per l'utilizzo. Per ulteriori informazioni, consulta Abilitazione dell'API.
- Se prevedi di utilizzare librerie client, installa le librerie per le lingue desiderate. Per i dettagli, consulta Librerie client. Attualmente, il supporto API per gli avvisi è disponibile solo per C#, Go, Java, Node.js e Python.
Se prevedi di utilizzare Google Cloud CLI, installala. Tuttavia, se utilizzi Cloud Shell, Google Cloud CLI è già installato.
Qui puoi trovare anche esempi di utilizzo dell'interfaccia
gcloud
. Tieni presente che gli esempigcloud
presuppongono che il progetto corrente sia già stato impostato come destinazione (gcloud config set project [PROJECT_ID]
), pertanto 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 il ruolo IAM Editor AlertPolicy Monitoring (
roles/monitoring.alertPolicyEditor
) per il tuo progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.Potresti anche essere in grado di ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Per informazioni dettagliate sui ruoli IAM per Monitoring, consulta Controllare l'accesso con Identity and Access Management.
Progetta la tua applicazione per 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 eliminano un criterio di avviso.
crea un criterio di avviso
Per creare un criterio di avviso in un progetto, utilizza il metodo alertPolicies.create
. Per informazioni su come richiamare questo metodo, i relativi parametri e i dati della risposta, consulta la pagina di riferimento alertPolicies.create
.
Puoi creare criteri da file JSON o YAML.
Google Cloud CLI accetta questi file come argomenti e
puoi leggere in modo programmatico i file JSON, convertirli in oggetti AlertPolicy
e creare criteri da questi
utilizzando il metodo alertPolicies.create
. Se hai un file di configurazione JSON o YAML Prometheus con una regola di avviso, gcloud CLI può eseguirne la migrazione a un criterio di avviso di Cloud Monitoring con una condizione PromQL. Per maggiori informazioni, consulta
Eseguire la migrazione delle regole di avviso e dei ricevitori da Prometheus.
Ogni criterio di avviso appartiene a un progetto di definizione dell'ambito di un ambito delle metriche. Ogni progetto può contenere fino a 500 criteri.
Per le chiamate API, devi fornire un "ID progetto". Utilizza l'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 non descrivono come creare un file JSON o YAML che descrive un criterio di avviso. Gli esempi presuppongono invece che esista un file in formato JSON e illustrano come emettere la chiamata API. Ad esempio, per i file JSON, vedi Criteri di esempio. Per informazioni generali sul monitoraggio dei rapporti delle metriche, consulta Rapporto 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 per un criterio con il nome visualizzato "Frequenza di modifica elevata della CPU". Per maggiori dettagli su questo criterio, consulta il Criterio della frequenza di modifica.
Per ulteriori informazioni, consulta il riferimento gcloud alpha monitoring policies create
.
C#
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Go
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
PHP
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione a Monitoring, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
L'oggetto AlertPolicy
creato avrà campi aggiuntivi.
Il criterio avrà campi name
, creationRecord
e mutationRecord
. Inoltre, a ogni condizione nel criterio viene assegnato un valore name
.
Questi campi non possono essere modificati esternamente, quindi non è necessario impostarli quando si crea un criterio. Nessuno degli esempi JSON utilizzati per la creazione dei criteri li include, ma i campi saranno presenti se vengono recuperati dopo la creazione.