Annota le notifiche con la documentazione definita dall'utente

In questa pagina viene descritto come configurare la documentazione sui criterio di avviso per personalizzare il corpo e la riga dell'oggetto delle notifiche. I campi della documentazione supportano testo normale, Markdown, variabili e controlli specifici per canale.

Aggiungi informazioni alla notifica

È possibile fornire agli utenti che rispondono agli incidenti i passaggi di correzione e le informazioni sull'incidente nella notifica, specificando tale contenuto quando si crea il criterio di avviso. Ad esempio, puoi configurare il criterio di avviso in modo da includere i link a un playbook interno in tutte le notifiche.

Per un'implementazione di esempio, consulta la sezione Esempio di questa pagina.

Configura la riga dell'oggetto delle notifiche

Puoi gestire e ordinare le notifiche specificandone l'oggetto. L'oggetto può contenere un massimo di 255 caratteri. Se non definisci un oggetto nella documentazione, Cloud Monitoring determina la riga dell'oggetto.

Puoi configurare la riga dell'oggetto quando utilizzi l'API Cloud Monitoring, Google Cloud CLI o la console Google Cloud.

Per un'implementazione di esempio, consulta la sezione Esempio di questa pagina.

Utilizzo di Markdown

Il campo della documentazione supporta il seguente sottoinsieme di tagging Markdown:

• Intestazioni, indicate da un carattere hash iniziale.
• Elenchi non ordinati, indicati da caratteri iniziali più, meno o asterischi.
• Elenchi ordinati, indicati da un numero iniziale seguito da un punto.
• Testo in corsivo, indicato da singoli trattini bassi o asterischi intorno a una frase.
• Testo in grassetto, indicato da doppi trattini bassi o asterischi intorno a una frase.
• Link, indicati dalla sintassi [link text](url).

Per ulteriori informazioni su questo tagging, consulta qualsiasi riferimento Markdown, ad esempio la Guida al markup.

Utilizzo delle variabili

Per personalizzare il testo nella documentazione, puoi utilizzare variabili nel formato ${varname}. Quando la documentazione viene inviata con una notifica, la stringa ${varname} viene sostituita con un valore estratto dalla risorsa Google Cloud corrispondente, come descritto nella tabella seguente.

Variabile	Valore
condition.name	Il nome della risorsa REST della condizione, ad esempio projects/foo/alertPolicies/1234/conditions/5678.
condition.display_name	Il nome visualizzato di una condizione, ad esempio CPU usage increasing rapidly.
log.extracted_label.KEY	Il valore dell'etichetta KEY, estratta da una voce di log. Solo per i criteri di avviso basati su log; per ulteriori informazioni, consulta Creare un criterio di avviso basato su log utilizzando l'API Monitoring.
metadata.system_label.KEY	Valore dell'etichetta dei metadati della risorsa fornita dal sistema KEY.^1
metadata.user_label.KEY	Il valore dell'etichetta dei metadati della risorsa definita dall'utente KEY.^1,3
metric.type	Il tipo di metrica, ad esempio compute.googleapis.com/instance/cpu/utilization.
metric.display_name	Il nome visualizzato per il tipo di metrica, ad esempio CPU utilization.
metric.label.KEY	Il valore dell'etichetta della metrica KEY.^1 Per trovare le etichette associate al tipo di metrica, consulta Elenco delle metriche. Quando il valore della variabile ${metric.label.KEY} non inizia con un numero, una lettera, una barra (/) o un segno di uguale (=), Monitoring omette l'etichetta dalle notifiche. Quando esegui la migrazione di una regola di avviso Prometheus, i modelli di campi di avviso Prometheus {{$value}} e {{humanize $value}} vengono visualizzati come ${metric.label.VALUE} nella configurazione della documentazione criterio di avviso. In questo caso, VALUE contiene il valore della query PromQL. Puoi utilizzare ${metric.label.VALUE} anche quando crei query PromQL in Google Cloud.
metric_or_resource.labels	Questa variabile mostra tutti i valori delle metriche e delle etichette delle risorse come un elenco ordinato di key-value coppie. Se un'etichetta di metrica e un'etichetta di risorsa hanno lo stesso nome, viene visualizzata solo l'etichetta della metrica. Quando esegui la migrazione di una regola di avviso Prometheus, i modelli di campi di avviso Prometheus {{$labels}} e {{humanize $labels}} vengono visualizzati come ${metric_or_resource.labels} nella configurazione della documentazione criterio di avviso.
metric_or_resource.label.KEY	Se KEY è un'etichetta valida, questa variabile viene visualizzata nella notifica come valore di ${metric.label.KEY}. Se KEY è una risorsa valida, questa variabile viene visualizzata nella notifica come valore di ${resource.label.KEY}. Se KEY non è né un'etichetta valida né una risorsa valida, questa variabile viene visualizzata nella notifica come stringa vuota. Quando esegui la migrazione di una regola di avviso Prometheus, i modelli di campi di avviso Prometheus {{$labels.KEY}} e {{humanize $labels.KEY}} vengono visualizzati come ${metric_or_resource.labels.KEY} nella configurazione della documentazione dei criteri di avviso.
policy.name	Il nome della risorsa REST del criterio, ad esempio projects/foo/alertPolicies/1234.
policy.display_name	Il nome visualizzato di un criterio, ad esempio High CPU rate of change.
policy.user_label.KEY	Il valore dell'etichetta utente KEY.^1 Le chiavi devono iniziare con una lettera minuscola. Le chiavi e i valori possono contenere solo lettere minuscole, cifre, trattini bassi e trattini.
project	L'ID del progetto di definizione dell'ambito di un ambito delle metriche, ad esempio a-gcp-project.
resource.type	Il tipo di risorsa monitorata, ad esempio gce_instance.
resource.project	L'ID progetto della risorsa monitorata per il criterio di avviso.
resource.label.KEY	Il valore dell'etichetta della risorsa KEY.^1,2,3 Per trovare le etichette associate al tipo di risorsa monitorata, consulta Elenco delle risorse.

¹ Ad esempio, ${resource.label.zone} viene sostituito con il valore dell'etichetta zone. I valori di queste variabili sono soggetti a raggruppamento. Per ulteriori informazioni, consulta Valori di null.
² Per recuperare il valore dell'etichetta project_id su una risorsa monitorata nel criterio di avviso, utilizza ${resource.project}.
³ Non puoi accedere alle etichette dei metadati delle risorse definite dall'utente utilizzando resource.label.KEY., invece, utilizza metadata.user_label.KEY.

Note sull'utilizzo

• Sono supportate solo le variabili nella tabella. Non puoi combinarle in espressioni più complesse come ${varname1 + varname2}.
• Per includere la stringa letterale ${ nella documentazione, esegui il escape del simbolo $ con un secondo simbolo $ e $${ nella documentazione viene eseguito come ${.
• Queste variabili vengono sostituite dai rispettivi valori solo nelle notifiche inviate tramite canali di notifica. Nella console Google Cloud, quando viene mostrata la documentazione, vedi le variabili, non i valori. Alcuni esempi nella console includono le descrizioni degli incidenti e l'anteprima della documentazione durante la creazione di un criterio di avviso.
• Assicurati che le impostazioni di aggregazione della condizione non eliminino l'etichetta. Se l'etichetta viene eliminata, il valore dell'etichetta nella notifica è null. Per maggiori informazioni, consulta la pagina La variabile per un'etichetta della metrica è nulla.

Nota: le etichette che aggiungi alle metriche basate su log non possono essere utilizzate nelle espressioni dei modelli. Tuttavia, puoi visualizzare queste etichette nelle legende dei grafici e filtrare le serie temporali in base ai relativi valori.

Esempio

L'esempio seguente mostra le versioni della documentazione del modello per la console Google Cloud e l'API Cloud Monitoring per un criterio di avviso sull'utilizzo della CPU e la documentazione visualizzata che appare nel corpo di una notifica. Questo esempio utilizza un indirizzo email per il tipo di canale di notifica. Il modello di documentazione include diverse variabili per riepilogare l'incidente e per fare riferimento al criterio di avviso e alla condizione delle risorse REST.

Console Google Cloud

Nota: l'oggetto della notifica è configurato nella sezione Notifiche e nome della pagina Crea criterio di avviso.

## CPU utilization exceeded

### Summary

The ${metric.display_name} of the ${resource.type}
${resource.label.instance_id} in the project ${resource.project} has
exceeded 90% for over 15 minutes.

### Additional resource information

Condition resource name: ${condition.name}  
Alerting policy resource name: ${policy.name}  

### Troubleshooting and Debug References

Repository with debug scripts: example.com  
Internal troubleshooting guide: example.com  
${resource.type} dashboard: example.com

API Cloud Monitoring

"documentation": {
"content": "## CPU utilization exceeded\n\n### Summary\n\nThe ${metric.display_name} of the ${resource.type} ${resource.label.instance_id} in the project ${resource.project} has exceeded 90% for over 15 minutes.\n\n### Additional resource information\n\nCondition resource name: ${condition.name}  \nAlerting policy resource name: ${policy.name}  \n\n### Troubleshooting and Debug References\n    \nRepository with debug scripts: example.com  \nInternal troubleshooting guide: example.com  \n${resource.type} dashboard: example.com",
"mimeType": "text/markdown",
"subject": "Alert: ${metric.display_name} exceeded"
}

Nota: il testo subject viene visualizzato nella riga dell'oggetto della notifica.

Formatta nella notifica

null valori

I valori delle variabili metric.*, resource.* e metadata.* vengono ricavati dalle serie temporali. I valori possono essere null se non viene restituito alcun valore dalla query delle serie temporali.

• Le variabili resource.label.KEY e metric.label.KEY possono avere valori null se il criterio di avviso utilizza l'aggregazione in più serie (riduzione), ad esempio calcolando la SOMMA in ognuna delle serie temporali che corrispondono a un filtro. Quando utilizzi l'aggregazione in più serie, tutte le etichette non utilizzate nel raggruppamento vengono eliminate e di conseguenza vengono visualizzate come null quando la variabile viene sostituita con il suo valore. Tutte le etichette vengono conservate quando non esiste aggregazione in più serie. Per maggiori informazioni, consulta la pagina La variabile per un'etichetta della metrica è nulla.

• I valori delle variabili metadata.* sono disponibili solo se le etichette sono incluse esplicitamente nel filtro o nel raggruppamento di una condizione per l'aggregazione tra serie. Ciò significa che devi fare riferimento all'etichetta dei metadati nel filtro o nel raggruppamento affinché abbia un valore per il modello.

Risoluzione variabile

Le variabili nei modelli di documentazione vengono risolte solo nelle notifiche inviate utilizzando i seguenti canali di notifica:

• Email
• Slack
• Pub/Sub, schema JSON versione 1.2
• Webhook, schema JSON versione 1.2
• PagerDuty, schema JSON versione 1.2

Le variabili non vengono risolte, ma vengono visualizzate come stringhe come ${varname} in altri contesti, tra cui:

• Nella pagina Dettagli incidente della console Google Cloud.
• Nelle notifiche inviate tramite altri canali di notifica.

Utilizzo dei controlli del canale

Il testo nel campo della documentazione può anche includere caratteri speciali utilizzati dal canale di notifica stesso per controllare la formattazione e le notifiche.

Ad esempio, Slack utilizza @ per le menzioni. Puoi utilizzare @ per collegare la notifica a un ID utente specifico. Le menzioni non possono includere nomi. Supponi di includere una stringa come questa nel campo della documentazione:

<@backendoncall> Incident created based on policy ${policy.display_name}

Quando il campo della documentazione viene ricevuto dal canale Slack pertinente nell'ambito della notifica, la stringa precedente fa sì che Slack invii un messaggio aggiuntivo all'ID utente backendoncall. Il messaggio inviato da Slack all'utente potrebbe contenere informazioni pertinenti della notifica, ad esempio "Incidente creato in base a un criterio High CPU rate of change".

Queste opzioni aggiuntive sono specifiche per i singoli canali; per ulteriori informazioni sulle possibili opzioni, consulta la documentazione fornita dal fornitore del canale.