In questa pagina viene descritto come configurare la documentazione sui criterio di avviso in modo che le notifiche forniscano a chi risponde agli incidenti le risorse e informazioni aggiuntive per la risoluzione degli incidenti.
Struttura della documentazione
La documentazione di un criterio di avviso è composta da un oggetto, contenuti e link. Puoi configurare la documentazione nella console Google Cloud, nell'API Cloud Monitoring e in Google Cloud CLI.
Soggetti
L'oggetto della documentazione compare nell'oggetto del per gli incidenti correlati al criterio di avviso. I destinatari delle notifiche possono gestire e ordinare le notifiche per oggetto.
L'oggetto può contenere un massimo di 255 caratteri. Se non definisci un oggetto della documentazione, Cloud Monitoring determina l'oggetto. Le righe dell'oggetto supportano testo normale e variabili.
API Cloud Monitoring
Configura la riga dell'oggetto della notifica utilizzando il campo subject
del criterio di avviso documentation
.
Console Google Cloud
Configura la riga dell'oggetto della notifica utilizzando il campo Riga dell'oggetto della notifica nella sezione Notifiche e nome della pagina Crea criterio di avviso.
Contenuti
I contenuti della documentazione vengono visualizzati nella seguente notifica tipi:
- Email, sotto l'intestazione Documentazione sulle norme
- PagerDuty
- Pub/Sub
- Slack
- Webhook
Ti consigliamo di configurare i contenuti in modo che gli addetti all'intervento in caso di incidenti possano visualizzare i passaggi per la correzione e le informazioni sugli incidenti nelle notifiche relative alle norme di avviso. Ad esempio, potresti configurare documentazione per includere un riepilogo dell'incidente informazioni sulle risorse pertinenti.
I contenuti della documentazione supportano testo normale, Markdown, variabili e controlli specifici per i canali.
API Cloud Monitoring
Configura i contenuti della documentazione utilizzando il campo content
del criterio di avviso documentation
.
Console Google Cloud
Configura i contenuti della documentazione utilizzando il campo Documentazione nella Sezione Notifiche e nome della pagina Crea criterio di avviso.
Link
Puoi aggiungere link alla tua documentazione in modo che gli addetti alla risposta agli incidenti possano accedere a risorse come playbook, repository e dashboard di Google Cloud da una notifica.
API Cloud Monitoring
I link alla documentazione configurati nell'API Cloud Monitoring sono visualizzati nella i seguenti tipi di notifiche:
- Email, sotto l'intestazione Link rapidi
- PagerDuty
- Pub/Sub
- Webhook
Per configurare un collegamento, aggiungi una Link
al
documentation
del criterio di avviso.
Ogni link è rappresentato da un display_name
e da un url
. Puoi avere fino a
tre link nella documentazione.
La seguente configurazione utilizza links
con un solo URL
per creare un link a un playbook sugli incidenti. L'URL include una variabile che
che i destinatari delle notifiche possano accedere al playbook corretto in base
risorsa monitorata in cui si è verificato l'incidente:
"links" [
{
"displayName": "Playbook",
"url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
}
]
Console Google Cloud
I link alla documentazione configurati nella console Google Cloud sono visualizzati con altri contenuti della documentazione nei seguenti tipi di notifiche:
- Email, sotto l'intestazione Documentazione delle norme
- PagerDuty
- Pub/Sub
- Slack
- Webhook
Puoi aggiungere link ai contenuti della documentazione includendoli nel campo Documentazione del criterio di avviso. Ad esempio, la seguente documentazione elenca l'URL di un playbook per i clienti:
### Troubleshooting and Debug References Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}
Markdown nei contenuti della documentazione
Puoi utilizzare Markdown per formattare i contenuti della documentazione. I contenuti della documentazione supportano il seguente sottoinsieme di tagging Markdown:
- Intestazioni, indicate dai caratteri iniziali dell'hash.
- 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 trattini bassi o asterischi singoli 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)
. Tuttavia, ti consigliamo di utilizzareLink
per configurare i link per i tuoi contenuti.
Per ulteriori informazioni su questo tagging, consulta qualsiasi riferimento Markdown, ad esempio, Guida al markup.
Variabili nella documentazione
Per personalizzare il testo della documentazione, puoi usare le variabili
nel formato ${varname}
. Quando la documentazione viene inviata con
una notifica, la stringa ${varname}
viene sostituita con un valore tratto 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 criteri di avviso basati su log. per altre
informazioni,
vedi
Crea 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 esempiocompute.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 Quando il valore della variabile Quando esegui la migrazione di una regola di avviso Prometheus, i modelli dei campi di avviso Prometheus Puoi usare |
metric_or_resource.labels |
Questa variabile mostra tutti i valori delle etichette delle metriche e delle risorse sotto forma di elenco ordinato di coppie Quando esegui la migrazione di una regola di avviso Prometheus, i modelli dei campi di avviso Prometheus |
metric_or_resource.label.KEY |
Quando esegui la migrazione di una regola di avviso Prometheus, i modelli di campo di avviso Prometheus |
policy.name |
Il nome della risorsa REST del criterio, ad esempio
projects/foo/alertPolicies/1234 . |
policy.display_name |
Il nome visualizzato di una norma, 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, numeri, 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 del criterio di avviso. |
resource.label.KEY |
Il valore dell'etichetta della risorsa
KEY .1,2,3Per trovare le etichette associate al tipo di risorsa monitorata, consulta Elenco delle risorse: |
1 Ad esempio, ${resource.label.zone}
viene sostituito con
il valore dell'etichetta zone
. I valori di queste variabili sono soggetti
raggruppamento; consulta i valori di null
per ulteriori informazioni.
2 Per recuperare il valore dell'etichetta project_id
su una
risorsa monitorata nel criterio di avviso, utilizza ${resource.project}
.
3 Non puoi accedere alle etichette dei metadati delle risorse definite dall'utente utilizzando resource.label.KEY.
. Utilizza metadata.user_label.KEY
.
Note sull'utilizzo
- Sono supportate solo le variabili nella tabella. Non puoi combinarli in
espressioni più complesse, come
${varname1 + varname2}
. - Per includere la stringa letterale
${
nella documentazione, esegui il comando di escape in$
con un secondo simbolo$
e$${
viene visualizzato come${
documentazione. - Queste variabili vengono sostituite con i rispettivi valori solo nelle notifiche inviate tramite i canali di notifica. Nella console Google Cloud, quando viene mostrata la documentazione, vedi le variabili, non i valori. Esempi nella console includono le descrizioni degli incidenti e l'anteprima quando crei un criterio di avviso.
- Assicurati che le impostazioni di aggregazione della condizione non eliminino
dell'etichetta. Se l'etichetta viene eliminata, viene restituito il valore dell'etichetta nella
la notifica è
null
. Per ulteriori informazioni, consulta La variabile per un'etichetta di metrica è nullo.
null
valori
Valori per le variabili metric.*
, resource.*
e metadata.*
derivano da serie temporali. Se non sono presenti valori, questi possono essere null
dalla query della serie temporale.
Le variabili
resource.label.KEY
emetric.label.KEY
possono averenull
valori se il criterio di avviso utilizza l'aggregazione tra serie (riduzione), ad esempio calcolando la SOMMA su ciascuno dei a serie temporali corrispondenti a un filtro. Quando usi l'aggregazione in più serie, tutte le etichette non utilizzate nel raggruppamento vengono eliminate e di conseguenza vengono visualizzate comenull
quando la variabile viene sostituita con il relativo valore. Tutte le etichette vengono conservati in assenza di aggregazioni tra serie. Per ulteriori informazioni, consulta La variabile per l'etichetta di una metrica è null.I valori delle variabili
metadata.*
sono disponibili solo se le etichette sono incluse esplicitamente in un filtro o raggruppamento di una condizione per l'aggregazione in più serie. Vale a dire che devi fare riferimento all'etichetta dei metadati filtra o raggruppa per avere un valore per il modello.
Risoluzione variabile
Le variabili nei modelli di documentazione vengono risolte solo nelle notifiche inviato tramite i seguenti canali di notifica:
- Google Chat
- Slack
- Pub/Sub, schema JSON versione 1.2
- Webhook, schema JSON versione 1.2
- PagerDuty, schema JSON versione 1.2
Controlli del canale
Il testo nel campo della documentazione può includere anche 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
a uno specifico ID utente. 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 utentebackendoncall
. Il messaggio inviato da Slack all'utente
potrebbero contenere informazioni pertinenti tratte dalla notifica; ad esempio
"Incidente creato in base a una frequenza di modifica della CPU elevata per il criterio".
Queste opzioni aggiuntive sono specifiche per i canali. Per ulteriori informazioni su quelle che potrebbero essere disponibili, consulta la documentazione fornita dal fornitore del canale.
Esempio
L'esempio seguente mostra le versioni della console Google Cloud e dell'API Cloud Monitoring documentazione del modello per un criterio di avviso relativo all'utilizzo della CPU. In questi esempi viene utilizzato un indirizzo email per il tipo di canale di notifica. I modelli di documentazione includono diverse variabili per riepilogare l'incidente e fare riferimento al criterio di avviso e alla condizione delle risorse REST.
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 5% for over 60 seconds.\n\n#### Additional resource information\n\nCondition resource name: ${condition.name} \nAlerting policy resource name: ${policy.name}",
"mimeType": "text/markdown",
"subject": "Alert: ${metric.display_name} exceeded",
"links": [
{
"displayName": "Playbook",
"url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
},
{
"displayName": "Repository with debug scripts",
"url": "https://altostrat.com"
},
{
"displayName": "Google Cloud dashboard",
"url": "https://example.com"
}
]
}
La seguente immagine mostra come viene visualizzato questo modello in un'email notifica:
Console Google Cloud
### CPU utilization exceeded #### Summary The ${metric.display_name} of the ${resource.type} ${resource.label.instance_id} in the project ${resource.project} has exceeded 5% for over 60 seconds. #### Additional resource information Condition resource name: ${condition.name} Alerting policy resource name: ${policy.name} #### Troubleshooting and Debug References Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type} Repository with debug scripts: https://altostrat.com ${resource.type} dashboard: https://example.com
La seguente immagine mostra come viene visualizzato questo modello in un'email notifica: