Annotare le notifiche con la documentazione definita dall'utente

Questa pagina descrive come configurare la documentazione criterio di avviso in modo che le notifiche forniscano ai responsabili della risposta agli incidenti risorse e informazioni aggiuntive per la risoluzione degli incidenti.

Struttura della documentazione

La documentazione di una criterio di avviso è composta da un oggetto, contenuti e link. Puoi configurare la documentazione nella Google Cloud console, nell' API Cloud Monitoring e in Google Cloud CLI.

Oggetti

L'oggetto della documentazione viene visualizzato nell'oggetto delle notifiche per gli incidenti correlati alla criterio di avviso. I destinatari delle notifiche possono gestire e ordinare le notifiche per oggetto.

Le righe dell'oggetto non possono superare 255 caratteri. Se non definisci un oggetto nella documentazione, Cloud Monitoring determina la riga dell'oggetto. Le righe dell'oggetto supportano testo normale e variabili.

API Cloud Monitoring

Configura la riga dell'oggetto della notifica utilizzando il campo subject della documentationdella criterio di avviso.

Google Cloud Console

Configura la riga dell'oggetto della notifica utilizzando il campo Oggetto della notifica nella sezione Notifiche e nome della pagina Crea policy di avviso.

Contenuti

I contenuti della documentazione vengono visualizzati nei seguenti tipi di notifiche:

  • Email, nella sezione Documentazione della policy
  • PagerDuty
  • Pub/Sub
  • Slack
  • Webhook

Ti consigliamo di configurare i contenuti in modo che i responsabili della risposta agli incidenti possano visualizzare i passaggi di correzione e le informazioni sugli incidenti nelle notifiche relative alla criterio di avviso. Ad esempio, potresti configurare la documentazione in modo da includere un riepilogo dell'incidente e informazioni sulle risorse pertinenti.

I contenuti della documentazione supportano quanto segue:

API Cloud Monitoring

Configura i contenuti della documentazione utilizzando il campo content della documentationdella criterio di avviso.

Google Cloud Console

Configura i contenuti della documentazione utilizzando il campo Documentazione nella sezione Notifiche e nome della pagina Crea policy di avviso.

Puoi aggiungere link alla documentazione in modo che i responsabili della risposta agli incidenti possano accedere a risorse come playbook, repository e Google Cloud dashboard da una notifica.

L'API Cloud Monitoring consente di definire un oggetto che contiene i link più pertinenti per i responsabili della risposta agli incidenti. Sebbene la Google Cloud console non abbia un campo specifico per i link, puoi aggiungere una sezione per i link nel corpo della documentazione.

API Cloud Monitoring

Puoi aggiungere link alla documentazione definendo uno o più Link oggetti nel campo links della criterio di avviso documentation. Ogni oggetto Link è composto da un display_name e un url. Puoi avere fino a tre link nella documentazione.

La seguente configurazione mostra il campo links con un oggetto Link che rappresenta un URL a un playbook per gli incidenti. L'URL include una variabile in modo che i destinatari delle notifiche possano accedere al playbook corretto in base alla risorsa monitorata in cui si è verificato l'incidente:

"links" [
  {
    "displayName": "Playbook",
    "url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
  }
]

I link alla documentazione aggiunti utilizzando il campo Link vengono visualizzati nei seguenti tipi di notifiche:

  • Email, nella sezione Link rapidi
  • PagerDuty
  • Pub/Sub
  • Webhook

Google Cloud Console

Puoi aggiungere link ai contenuti della documentazione includendoli nel campo Documentazione della criterio di avviso. Ad esempio, la seguente documentazione elenca un URL per un playbook del cliente:

### Troubleshooting and Debug References

Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}

I link alla documentazione aggiunti utilizzando la Google Cloud console vengono visualizzati con il resto dei contenuti della documentazione nei seguenti tipi di notifiche:

  • Email, nella sezione Documentazione della policy
  • PagerDuty
  • Pub/Sub
  • Slack
  • Webhook

Markdown nei contenuti della documentazione

Puoi utilizzare Markdown per formattare i contenuti della documentazione. I contenuti della documentazione supportano il seguente sottoinsieme di tag Markdown:

  • Intestazioni, indicate dai caratteri hash iniziali.
  • Elenchi non ordinati, indicati dai caratteri iniziali più, meno o asterisco.
  • 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 trattini bassi o asterischi doppi intorno a una frase.
  • Link, indicati dalla sintassi [link text](url). Per aggiungere link alla notifica, ti consigliamo di utilizzare l' API Cloud Monitoring e configurare l'oggetto Link.

Per saperne di più su questi tag, consulta qualsiasi riferimento Markdown, ad esempio, la guida di Markdown.

Variabili nella documentazione

Per personalizzare il testo della 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.

Per le policy di avviso basate su log create utilizzando l' Esplora log, il valore di questo campo è "Log match condition". Per personalizzare il valore di questo campo, utilizza l'API Cloud Monitoring.
log.extracted_label.KEY Il valore dell'etichetta KEY, estratto da una voce di log. Solo per le policy di avviso basate su log; per saperne di più, consulta Crea una criterio di avviso basata su log utilizzando l'API Monitoring.
metadata.system_label.KEY Il valore dell'etichetta dei metadati delle risorse fornita dal sistema KEY.1
metadata.user_label.KEY Il valore dell'etichetta dei metadati delle risorse 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 una cifra, una lettera, una barra (/), o un segno di uguale (=), Monitoring omette l'etichetta dalle notifiche.

Quando esegui la migrazione di una regola di avviso di Prometheus, i modelli di campo di avviso di Prometheus {{$value}} e {{humanize $value}} vengono visualizzati come ${metric.label.value} nella configurazione della documentazione della criterio di avviso. In questo caso, ${metric.label.value} contiene il valore del trigger della regola di avviso di Prometheus.

Puoi utilizzare ${metric.label.value} anche quando crei query PromQL queries in Google Cloud.
metric.label.metadata_system_VALUE

Fa riferimento a un'etichetta di sistema dei metadati PromQL, dove VALUE è il nome dell'etichetta specifica, ad esempio region o version.

Esempio di utilizzo: ${metric.label.metadata_system_version}.
metric.label.metadata_user_VALUE

Fa riferimento a un'etichetta utente dei metadati PromQL, dove VALUE è il nome dell'etichetta specifica, ad esempio region o name.

Esempio di utilizzo: ${metric.label.metadata_user_name}.
metric_or_resource.labels

Questa variabile esegue il rendering di tutti i valori delle etichette di metriche e risorse come un elenco ordinato di coppie key-value. Se un'etichetta di metrica e un'etichetta di risorsa hanno lo stesso nome, viene eseguito il rendering solo dell'etichetta di metrica.

Quando esegui la migrazione di una regola di avviso di Prometheus, i modelli di campo di avviso di Prometheus {{$labels}} e {{humanize $labels}} vengono visualizzati come ${metric_or_resource.labels} nella configurazione della documentazione della criterio di avviso.
metric_or_resource.label.KEY
  • Se KEY è un'etichetta valida, questa variabile viene visualizzata nella notifica come il valore di ${metric.label.KEY}.
  • Se KEY è una risorsa valida, questa variabile viene visualizzata nella notifica come il valore di ${resource.label.KEY}.
  • Se KEY non è né un'etichetta valida né una risorsa valida, questa variabile viene visualizzata nella notifica come una stringa vuota.

Quando esegui la migrazione di una regola di avviso di Prometheus, i modelli di campo di avviso di Prometheus {{$labels.KEY}} e {{humanize $labels.KEY}} vengono visualizzati come ${metric_or_resource.labels.KEY} nella configurazione della documentazione della policy di avviso.
policy.name Il nome della risorsa REST della policy, ad esempio projects/foo/alertPolicies/1234.
policy.display_name Il nome visualizzato di una policy, 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 scoping 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 della 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.

1 Ad esempio, ${resource.label.zone} viene sostituito con il valore dell'etichetta zone. I valori di queste variabili sono soggetti a raggruppamento; per saperne di più, consulta null valori.
 2 Per recuperare il valore dell'project_id etichetta su una risorsa monitorata nella 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 invece.

Note sull'utilizzo

  • Sono supportate solo le variabili nella tabella. Non puoi combinarle in espressioni più complesse, ad esempio ${varname1 + varname2}.
  • Per includere la stringa letterale ${ nella documentazione, inserisci un carattere di escape per il $ simbolo con un secondo simbolo $ e $${ viene visualizzato come ${ nella tua documentazione.
  • Queste variabili vengono sostituite dai relativi valori solo nelle notifiche inviate tramite i canali di notifica. Nella Google Cloud console, quando viene visualizzata la documentazione, vengono visualizzate le variabili, non i valori. Gli esempi nella console includono le descrizioni degli incidenti e l'anteprima della documentazione durante la creazione di una criterio di avviso.
  • Verifica che le impostazioni di aggregazione della condizione non eliminino l'etichetta. Se l'etichetta viene eliminata, il valore dell'etichetta nella notifica è null. Per saperne di più, consulta La variabile per un'etichetta di metrica è null.

Valori null

I valori delle variabili metric.*, resource.* e metadata.* derivano dalle serie temporali. I valori possono essere null se non vengono restituiti valori dalla query della serie temporale.

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

  • 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 delle variabili

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

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

Controlli dei canali

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 la notifica a un ID utente specifico. Le menzioni non possono includere nomi. Supponiamo di includere una stringa di questo tipo nel campo della documentazione:

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

Quando il campo della documentazione viene ricevuto dal canale Slack pertinente come parte 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 dalla notifica, ad esempio "Incidente creato in base alla policy High CPU rate of change".

Queste opzioni aggiuntive sono specifiche dei canali; per saperne di più su ciò che potrebbe essere disponibile, consulta la documentazione fornita dal fornitore del canale.

Esempio

L'esempio seguente mostra le versioni della console e dell'API Cloud Monitoring della documentazione del modello per una policy di avviso sull'utilizzo della CPU. Google Cloud Questi esempi utilizzano un'email per il tipo di canale di notifica. I modelli di documentazione includono diverse variabili per riepilogare l'incidente e fare riferimento alle risorse REST della criterio di avviso e della condizione.

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"
      }
    ]
  }

L'immagine seguente mostra come viene visualizzato questo modello in una notifica via email:

Esempio di come viene visualizzata la documentazione in una notifica. I link vengono visualizzati nella sezione &quot;Link rapidi&quot;.

Google Cloud Console 

### 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

L'immagine seguente mostra come viene visualizzato questo modello in una notifica via email:

Esempio di come viene visualizzata la documentazione in una notifica. I link vengono visualizzati sotto l&#39;intestazione &quot;Riferimenti per la risoluzione dei problemi e il debug&quot;.