Questa pagina è stata tradotta dall'API Cloud Translation.

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 agli addetti alla 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 relative agli 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 il testo normale e le 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 nei seguenti tipi di notifiche:

Email, sotto l'intestazione Documentazione delle 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 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:

Testo normale
Variabili
Controlli specifici per i canali
Markdown nei canali di notifica non Slack

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 vengono visualizzati nei seguenti tipi di notifiche:

Email, sotto l'intestazione Link rapidi
PagerDuty
Pub/Sub
Webhook

Per configurare un link, aggiungi un Link al documentation del criterio di avviso. Ogni link è rappresentato da un display_name e un url. Puoi avere fino a tre link nella documentazione.

La seguente configurazione utilizza links con un URL per creare un link 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}"
  }
]

Console Google Cloud

I link alla documentazione configurati nella console Google Cloud vengono visualizzati con il resto dei 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 delle criterio di avviso. Ad esempio, la documentazione seguente elenca un URL per un playbook del cliente:

### 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 di 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). Tuttavia, ti consigliamo di utilizzare l'oggetto Link per configurare i link per i tuoi contenuti.

Per ulteriori informazioni su questo tagging, consulta un riferimento Markdown, ad esempio la guida di Markdown.

Variabili nella documentazione

Per personalizzare il testo nella documentazione, puoi utilizzare le variabili del tipo ${varname}. Quando la documentazione viene inviata con una notifica, la stringa ${varname} viene sostituita con un valore ricavato 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`, estratto 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`	Il valore dell'etichetta dei metadati della risorsa fornita dal sistema `KEY`.¹
`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`.¹ 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 (`=`), il monitoraggio omette l'etichetta dalle notifiche. Quando esegui la migrazione di una regola di avviso Prometheus, i modelli di campo 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.label.metadata_system_VALUE`	Fa riferimento a un'etichetta del sistema di metadati PromQL, dove `VALUE` è il nome specifico dell'etichetta, 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 specifico dell'etichetta, ad esempio `region` o `name`. Esempio di utilizzo: `${metric.label.metadata_user_name}`.
`metric_or_resource.labels`	Questa variabile mostra tutti i valori delle etichette delle metriche e delle risorse sotto forma di elenco ordinato di coppie `key-value`. Se un'etichetta metrica e un'etichetta risorsa hanno lo stesso nome, viene visualizzata solo l'etichetta metrica. Quando esegui la migrazione di una regola di avviso Prometheus, i modelli di campo 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 `KEY`.`${resource.label.KEY}` Se `KEY` non è un'etichetta 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 campo 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`.¹ 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 del 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 la sezione Valori 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.. 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 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 visualizzate le variabili, non i valori. Gli 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 notification è null. Per ulteriori informazioni, consulta La variabile per l'etichetta di una metrica è null.

`null` valori

I valori delle variabili metric.*, resource.* e metadata.* sono ricavati dalle serie temporali. I relativi valori possono essere null se non vengono restituiti valori dalla query sulle serie temporali.

Le variabili resource.label.KEY e metric.label.KEY possono avere valori null se il criterio di avviso utilizza l'aggregazione tra serie (riduzione), ad esempio calcolando la SOMMA in 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 un'aggregazione tra serie. Per ulteriori informazioni, consulta La variabile per l'etichetta di una metrica è null.
I valori per le variabili metadata.* sono disponibili solo se le etichette sono incluse esplicitamente nel filtro o nel raggruppamento di una condizione per l'aggregazione tra serie. In altre parole, 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, versione dello schema JSON 1.2
Webhook, schema JSON versione 1.2
PagerDuty, versione dello schema JSON 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 notification a un ID utente specifico. Le menzioni non possono includere nomi. Supponiamo 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 potrebbe contenere informazioni pertinenti della notifica, ad esempio "Incident created based on policy High CPU rate of change".

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 documentazione del modello per un criterio di avviso relativo all'utilizzo della CPU per la console Google Cloud e l'API Cloud Monitoring. 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 dei criterio di avviso e delle condizioni.

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 la documentazione viene visualizzata in una notifica. I link vengono visualizzati nella sezione "Link rapidi".

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

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

Esempio di come la documentazione viene visualizzata in una notifica. I link vengono visualizzati sotto l'intestazione "Riferimenti per la risoluzione dei problemi e il debug".

Annotare le notifiche con la documentazione definita dall'utente

Struttura della documentazione

Soggetti

API Cloud Monitoring

Console Google Cloud

Contenuti

API Cloud Monitoring

Console Google Cloud

Link

API Cloud Monitoring

Console Google Cloud

Markdown nei contenuti della documentazione

Variabili nella documentazione

Note sull'utilizzo

null valori

Risoluzione variabile

Controlli del canale

Esempio

API Cloud Monitoring

Console Google Cloud

`null` valori