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 un criterio di avviso è costituita 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 viene visualizzato nell'oggetto delle notifiche per gli incidenti correlati alle criterio di avviso. I destinatari delle notifiche possono gestirle e ordinarle per oggetto.

Le righe dell'oggetto sono limitate a 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.

Contenuti

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

• Email, nella sezione Documentazione delle norme
• 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 tua criterio di avviso. Ad esempio, potresti configurare la documentazione in modo che includa un riepilogo dell'incidente e informazioni sulle risorse pertinenti.

I contenuti della documentazione supportano quanto segue:

• Testo normale
• Variabili
• Controlli specifici per il canale

• Markdown

Link

Puoi aggiungere link alla documentazione in modo che coloro che sono preposti a reagire agli eventi possano accedere a risorse come playbook, repository e Google Cloud dashboard da una notifica.

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

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

### 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 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 doppi trattini bassi o asterischi 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 ulteriori informazioni su questo tagging, consulta qualsiasi riferimento Markdown, ad esempio la Guida Markdown.

Variabili nella documentazione

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.

¹ Ad esempio, ${resource.label.zone} viene sostituito con il valore dell'etichetta zone. I valori di queste variabili sono soggetti a raggruppamento; per maggiori informazioni, consulta la sezione Valori di null.
² Per recuperare il valore dell'etichetta project_id in 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.. Utilizza metadata.user_label.KEY in alternativa.

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 l'escape del simbolo $ con un secondo simbolo $ e $${ viene visualizzato come ${ nella documentazione.
• Queste variabili vengono sostituite dai relativi valori solo nelle notifiche inviate tramite i canali di notifica. Nella console Google Cloud , quando viene visualizzata la documentazione, vengono mostrate le variabili, non i valori. Esempi nella console includono le descrizioni degli incidenti e l'anteprima della documentazione durante la creazione di un 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 ulteriori informazioni, vedi La variabile per un'etichetta della metrica è nulla.

null valori

I valori delle variabili metric.*, resource.* e metadata.* derivano dalle serie temporali. I loro 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 valori null se il criterio di avviso utilizza l'aggregazione (riduzione) tra serie, ad esempio il calcolo della somma in tutte le serie temporali che corrispondono a un filtro. Quando utilizzi l'aggregazione tra serie, 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 è presente un'aggregazione tra serie. Per ulteriori informazioni, vedi 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. ovvero 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
• 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 la notifica a un ID utente specifico. Le menzioni non possono includere nomi. Supponiamo che tu includa 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 al criterio Tasso di variazione elevato della CPU".

Queste opzioni aggiuntive sono specifiche per i canali; per ulteriori informazioni su ciò che potrebbe essere disponibile, consulta la documentazione fornita dal fornitore del canale.

Esempio

L'esempio seguente mostra le versioni Google Cloud della console e dell'API Cloud Monitoring della documentazione del modello per una criterio di avviso sull'utilizzo della CPU. 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 per le condizioni e i criteri di criterio di avviso.

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

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