L'API Cloud Monitoring e Google Cloud CLI consentono di creare policy di avviso da file JSON o YAML o utilizzando le librerie client. Ogni oggetto AlertPolicy definisce le condizioni basate su metriche o log che indicano uno stato potenzialmente non integro nel sistema, insieme ai canali di notifica e alle strategie di avviso.
Quando utilizzi l'API Monitoring, devi eseguire l'autenticazione con una credenziale dell'utente finale anziché con una chiave API. Ad esempio, puoi fornire un token OAuth 2.0 per un utente o un account di servizio. Per saperne di più, consulta Utilizzo di OAuth 2.0 per accedere alle API di Google e Autenticazione per API e servizi Google Cloud .
Questa funzionalità è supportata solo per i progetti Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.
Struttura di una criterio di avviso
La struttura AlertPolicy definisce i componenti di una criterio di avviso. Quando crei una policy, specifichi i valori per i seguenti campi AlertPolicy:
displayName: un'etichetta descrittiva per la policy.documentation: ti consigliamo di utilizzare questo campo per fornire informazioni che aiutino i soccorritori. Per saperne di più, consulta Annota le notifiche con la documentazione definita dall'utente.userLabels: eventuali etichette definite dall'utente associate alla policy. Queste etichette vengono visualizzate nelle policy di avviso, negli avvisi e nelle notifiche. Per informazioni sull'utilizzo delle etichette con gli avvisi, consulta Annota gli avvisi con le 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 quanto segue:- La rapidità con cui Monitoring chiude gli avvisi quando i dati smettono di arrivare.
- Per le policy di avviso basate su metriche, se Monitoring invia una notifica quando un avviso viene chiuso.
- Per le policy di avviso basate su metriche, se le notifiche ripetute sono attivate e l'intervallo tra queste notifiche. Per saperne di più, consulta Configura le notifiche ripetute per le policy di avviso basate 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à degli avvisi. Se non specifichi una gravità, Cloud Monitoring imposta la gravità criterio di avviso su No Severity.
Esistono altri campi che potresti utilizzare, a seconda delle condizioni che crei.
Quando una criterio di avviso contiene una condizione, viene inviata una notifica quando questa condizione viene soddisfatta. Per informazioni sulle notifiche quando le policy di avviso contengono più condizioni, consulta Policy con più condizioni e Quando Monitoring invia notifiche e crea avvisi.
Quando crei o modifichi la criterio di avviso, Monitoring imposta anche altri campi, incluso il campo name. Il valore del campo name è il nome della risorsa per la criterio di avviso, che identifica la policy. Il nome della risorsa ha il seguente formato:
projects/PROJECT_ID/alertPolicies/POLICY_ID
Nell'espressione precedente:
- PROJECT_ID: l'identificatore del progetto. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.
- POLICY_ID: l'ID della criterio di avviso
Tipi di condizioni nell'API
L'API Cloud Monitoring supporta vari tipi di condizioni nella struttura Condition. Esistono diversi tipi di condizioni per le policy di avviso basate su metriche e un tipo per le policy di avviso basate su log. Le sezioni seguenti descrivono i tipi di condizioni disponibili.
Condizioni per le policy di avviso basate su metriche
Per creare una 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 filtri
Le condizioni MetricAbsence e MetricThreshold utilizzano i filtri di Monitoring per selezionare i dati delle serie temporali da monitorare. Altri campi nella struttura della condizione specificano come filtrare, raggruppare e aggregare i dati. Per saperne di più su questi concetti, consulta Filtro 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 temporale. Per saperne di più, consulta il riferimento MetricAbsence nella documentazione dell'API.
Una criterio di avviso per assenza di metriche richiede che alcuni dati siano stati scritti in precedenza. Per saperne di più, consulta Crea policy di avviso per assenza di metriche.
Se vuoi ricevere notifiche in base a un valore previsto, configura la criterio di avviso in modo che utilizzi il tipo di condizione MetricThreshold e imposta il campo 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 una soglia. Per saperne di più, consulta Crea policy di avviso basate su valori delle metriche previsti.
Condizioni delle metriche basate su PromQL
La condizione PrometheusQueryLanguageCondition utilizza query PromQL (Prometheus Query Language) per selezionare e manipolare i dati delle serie temporali da monitorare.
La condizione può calcolare un rapporto tra metriche, valutare i confronti tra metriche e altro ancora.
Se utilizzi una condizione PrometheusQueryLanguageCondition, deve essere l'unica condizione nella criterio di avviso. Per saperne di più, consulta Policy di avviso con PromQL.
Condizioni per gli avvisi sui rapporti
Puoi creare policy di avviso basate su soglie metriche per monitorare il rapporto tra due metriche. Puoi creare queste policy utilizzando il tipo di condizione MetricThreshold o PrometheusQueryLanguageCondition.
Puoi anche utilizzare PromQL direttamente nella console Google Cloud . Non puoi creare o gestire condizioni basate su un rapporto utilizzando l'interfaccia grafica per la creazione di condizioni di soglia.
Ti consigliamo di utilizzare PromQL per creare policy di avviso basate su rapporti.
PromQL ti consente di creare query più potenti e flessibili di quelle che puoi creare utilizzando il tipo di condizione MetricTheshold e i filtri di Monitoring.
Ad esempio, con una condizione PrometheusQueryLanguageCondition, puoi calcolare il rapporto tra una metrica di tipo GAUGE e una metrica di tipo DELTA.
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, è meglio 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 tipi di metriche diversi è soggetto ad anomalie dovute a periodi di campionamento e finestre di allineamento diversi.
Ad esempio, supponiamo di avere due tipi di metriche diversi, un conteggio totale delle RPC e un conteggio degli errori RPC, e di voler calcolare il rapporto tra le RPC con errori e le RPC totali. Le RPC non riuscite vengono conteggiate nelle serie temporali 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é esistono due serie temporali diverse che registrano lo stesso evento, esistono due valori di contatore sottostanti che implementano la raccolta e non vengono aggiornati in modo atomico.
- Le frequenze di campionamento potrebbero essere diverse. Quando le serie temporali sono allineate a un periodo comune, i conteggi per 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ò
portare a valori di rapporto error/total privi di senso, come 1/0 o 2/1.
I rapporti di numeri più grandi hanno meno probabilità di generare valori privi di 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 determinato 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 utilizzi 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 la stessa cosa, ad esempio le 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 tu stia contando le RPC e voglia monitorare il rapporto tra le RPC non riuscite e tutte le RPC. Per risolvere questo problema, crea un unico tipo di metrica per conteggiare le RPC e utilizza un'etichetta per registrare lo stato della chiamata, incluso lo stato "OK". Poi, ogni valore di stato, errore o "OK", viene registrato aggiornando un singolo contatore per quel caso.
Condizione per le policy di avviso basate su log
Per creare una criterio di avviso basata su log, che ti avvisa 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 nella criterio di avviso.
Non provare a utilizzare il tipo di condizione LogMatch insieme alle metriche basate su log. Le policy di avviso che monitorano le metriche basate su log sono policy basate su metriche. Per saperne di più sulla scelta tra policy di avviso che monitorano le metriche basate su log o le voci di log, consulta Monitoraggio dei log.
Le policy di avviso utilizzate negli esempi del documento Gestisci le policy di avviso tramite API sono policy di avviso basate su metriche, anche se i principi sono gli stessi per le policy di avviso basate su log. Per informazioni specifiche sulle policy di avviso basate su log, consulta Crea una criterio di avviso basata su log utilizzando l'API Monitoring nella documentazione di Cloud Logging.
Come associare una criterio di avviso a un'applicazione App Hub
Google Cloud genera dashboard che ti aiutano a monitorare le tue applicazioni App Hub. Queste dashboard mostrano informazioni come i dati di log e metriche per le tue applicazioni, nonché i servizi e i workload che fanno parte dell'applicazione. In queste dashboard vengono visualizzate anche le policy di avviso e i relativi avvisi, se queste policy sono associate al servizio o al workload di un'applicazione. Per saperne di più sul monitoraggio delle applicazioni, consulta Visualizza la telemetria delle applicazioni.
Per associare una criterio di avviso a un'applicazione App Hub, collega alla policy le etichette con le seguenti chiavi:
apphub_application_locationapphub_application_idapphub_service_idoapphub_workload_id
userLabels della rappresentazione JSON di una criterio di avviso potrebbe essere simile alla seguente:
"userLabels": {
"apphub_service_id": "my-service-id",
"apphub_application_location": "my-app-location",
"apphub_application_id": "my-app"
},
Prima di iniziare
Prima di scrivere il codice per l'API, devi:
- Avere familiarità con i concetti generali e la terminologia utilizzata con le policy di avviso; per ulteriori informazioni, consulta la Panoramica degli avvisi.
- Assicurati che l'API Cloud Monitoring sia abilitata per l'utilizzo. Per saperne di più, consulta Abilitazione dell'API.
- Se prevedi di utilizzare le librerie client, installa le librerie per i linguaggi che vuoi utilizzare. Per maggiori dettagli, consulta Librerie client. Il supporto delle 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 sono riportati anche esempi di utilizzo dell'interfaccia
gcloud. Tieni presente che tutti gli esempi digcloudpresuppongono che il progetto corrente sia già stato impostato come destinazione (gcloud config set project [PROJECT_ID]), pertanto le chiamate omettono il flag esplicito--project. L'ID del progetto corrente negli esempi èa-gcp-project. Per le configurazioni di App Hub, seleziona il progetto host o il progetto di gestione di App Hub.
-
Per ottenere le autorizzazioni necessarie per creare e modificare le policy di avviso utilizzando l'API Cloud Monitoring, chiedi all'amministratore di concederti il ruolo IAM Monitoring AlertPolicy Editor (
roles/monitoring.alertPolicyEditor) sul progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci 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 Monitoring, consulta Controlla l'accesso con Identity and Access Management.
Progetta la tua applicazione in modo da eseguire in un singolo thread le chiamate API Cloud Monitoring che modificano lo stato di una criterio di avviso in un progettoGoogle Cloud . Ad esempio, chiamate API single-thread che creano, aggiornano o eliminano una criterio di avviso.
crea una policy di avviso
Per creare una criterio di avviso in un progetto, utilizza il metodo 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 policy da file JSON o YAML.
Google Cloud CLI accetta questi file come argomenti e puoi leggere i file JSON in modo programmatico, convertirli in oggetti AlertPolicy e creare policy da questi oggetti utilizzando il metodo alertPolicies.create. Se hai un file di configurazione JSON o YAML di Prometheus con una regola di avviso, gcloud CLI può eseguirne la migrazione a una policy di avviso di Cloud Monitoring con una condizione PromQL. Per saperne di più, consulta Esegui la migrazione di regole di avviso e 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 2000 policy.
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.
I seguenti esempi illustrano la creazione di policy di avviso, ma non descrivono come creare un file JSON o YAML che descriva una 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 Esempi di policy. Per informazioni generali sul monitoraggio dei rapporti delle metriche, consulta Rapporti delle metriche.
gcloud
Per creare una criterio di avviso in un progetto, utilizza il comando gcloud monitoring
policies create. L'esempio seguente crea una policy di avviso in a-gcp-project dal file rising-cpu-usage.json:
gcloud monitoring policies create --policy-from-file="rising-cpu-usage.json"
In caso di esito positivo, questo comando restituisce il nome della nuova policy, ad esempio:
Created alert policy [projects/a-gcp-project/alertPolicies/12669073143329903307].
Il file rising-cpu-usage.json contiene il codice JSON per una policy con il nome visualizzato "Tasso di variazione della CPU elevato". Per i dettagli su questa policy, consulta Policy sul tasso di variazione.
Per saperne di più, consulta il riferimento gcloud monitoring policies create.
C#
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Go
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Java
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
PHP
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione in Monitoring, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
L'oggetto AlertPolicy creato avrà campi aggiuntivi.
La policy stessa avrà i campi name, creationRecord e mutationRecord. Inoltre, a ogni condizione della policy viene assegnato un name.
Questi campi non possono essere modificati esternamente, quindi non è necessario impostarli durante la creazione di una policy. Nessuno degli esempi JSON utilizzati per la creazione delle policy li include, ma se le policy create da questi esempi vengono recuperate dopo la creazione, i campi saranno presenti.
Configura le notifiche ripetute per le policy di avviso basate su metriche
Per impostazione predefinita, una criterio di avviso basata su metriche invia una notifica a ogni canale di notifica quando viene aperto un avviso. Tuttavia, puoi modificare il comportamento predefinito e configurare una criterio di avviso per inviare nuovamente le notifiche a tutti o ad alcuni dei canali di notifica della criterio di avviso. Queste notifiche ripetute vengono inviate per gli avvisi con stato Aperto o Confermato. L'intervallo tra queste notifiche deve essere di almeno 30 minuti e non più di 24 ore, espresso in secondi.
Per configurare le notifiche ripetute, aggiungi alla configurazione della criterio di avviso un oggetto AlertStrategy che contiene almeno un oggetto NotificationChannelStrategy.
Un oggetto NotificationChannelStrategy ha due campi:
renotifyInterval: l'intervallo, in secondi, tra le notifiche ripetute.Se modifichi il valore del campo
renotifyIntervalquando viene aperto un avviso per la criterio di avviso, si verifica quanto segue:- La criterio di avviso invia un'altra notifica per l'avviso.
- La criterio di avviso riavvia il periodo dell'intervallo.
notificationChannelNames: un array di nomi delle risorse dei canali di notifica, che sono stringhe nel formatoprojects/PROJECT_ID/notificationChannels/CHANNEL_ID, dove CHANNEL_ID è un valore numerico. Per informazioni su come recuperare l'ID canale, consulta Elenca i canali di notifica in un progetto.
Ad esempio, l'esempio JSON seguente 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. Per evitare notifiche ripetute, modifica la criterio di avviso utilizzando l'API e rimuovi l'oggetto NotificationChannelStrategy.