Questa pagina è stata tradotta dall'API Cloud Translation.

Configurazione degli avvisi basati su log

Puoi utilizzare gli avvisi basati su log per ricevere una notifica ogni volta che viene visualizzato un messaggio specifico nei log inclusi. Ad esempio, se vuoi sapere quando un log di controllo registra un determinato messaggio di accesso ai dati, puoi creare un avviso basato su log che corrisponda al messaggio e ti venga inviata una notifica quando viene visualizzato. Questo documento descrive come effettuare le seguenti operazioni utilizzando la console Google Cloud e l'API Cloud Monitoring:

Crea e testa un avviso basato su log.
Modifica un avviso basato su log.
Elimina un avviso basato su log.

Prima di iniziare

Consulta la pagina Confronto degli avvisi per determinare se gli avvisi basati su log sono adatti ai dati dei log. Ad esempio:

Gli avvisi basati su log non funzionano sui log esclusi.
Non puoi utilizzare gli avvisi basati su log per ricavare i conteggi dai log. Per ricavare i conteggi, devi utilizzare invece metriche basate su log.

Per creare e gestire avvisi basati su log, il tuo ruolo Identity and Access Management deve includere le autorizzazioni descritte in Autorizzazioni per gli avvisi basati su log.

Crea un avviso basato su log utilizzando Esplora log

Puoi creare avvisi basati su log dalla pagina Esplora log nella console Google Cloud o utilizzando l'API Monitoring. Questa sezione descrive come creare avvisi basati su log utilizzando Esplora log. Per creare avvisi basati su log utilizzando l'API Monitoring, vedi Creare un avviso basato su log utilizzando l'API Monitoring.

L'interfaccia di Esplora log per la creazione e la modifica di avvisi basati su log ti guida nei seguenti passaggi:

Specifica un nome e una descrizione per l'avviso.
Scegli i log per i quali vuoi ricevere una notifica.
Imposta l'orario tra le notifiche.
Imposta l'ora di chiusura automatica degli incidenti.
Specifica a chi inviare la notifica.

Ad esempio, supponiamo di avere un'applicazione che scrive una voce di log syslog con gravità NOTICE quando l'applicazione cambia un indirizzo di rete. Le voci di log per le modifiche all'indirizzo di rete includono un payload JSON simile al seguente:

"jsonPayload": {
  "type": "Configuration change",
  "action": "Set network address",
  "result": "IP_ADDRESS",
}

Vuoi creare un avviso basato su log che ti avvisi quando viene visualizzato un indirizzo IPv4 non valido nel campo jsonPayload.result delle voci di log in syslog con gravità NOTICE.

Per creare l'avviso basato su log:

Nel pannello di navigazione della console Google Cloud, seleziona Logging, quindi Esplora log:
Vai a Esplora log
Utilizza il riquadro Query per creare una query che corrisponda al messaggio che vuoi utilizzare nell'avviso basato su log.

Ad esempio, per trovare voci di log con un livello di gravità NOTICE nel log syslog che hanno indirizzi IP non validi nel payload JSON, puoi utilizzare la seguente query:
```
log_id("syslog")
severity = "NOTICE"
jsonPayload.result !~ "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.|$)){4}$"
```
Utilizza Esegui query nel riquadro Risultati delle query per convalidare la query.
Nell'intestazione del riquadro Risultati query, fai clic su Crea avviso. Quando la finestra è stretta, nel menu Azioni potrebbe essere visualizzata l'opzione Crea avviso.
Nel riquadro Dettagli avviso, assegna all'avviso un nome e una descrizione:
1. Inserisci un nome per l'avviso nel campo Nome criterio di avviso. Ad esempio: "Indirizzo di rete: valore IPv4 non valido".
2. Seleziona un'opzione dal menu Livello di gravità del criterio. Gli incidenti e le notifiche mostrano il livello di gravità.
3. Inserisci una descrizione per questo avviso. Puoi anche includere informazioni che potrebbero aiutare il destinatario di una notifica a diagnosticare il problema. La stringa seguente riassume il motivo dell'avviso:
```
Log-based alert in project ${project} detected an invalid IPv4 value.
```
  Per informazioni su come formattare e personalizzare i contenuti di questo campo, consulta Utilizzo di Markdown e delle variabili nei modelli di documentazione.
Per andare al passaggio successivo, fai clic su Avanti.
Nel riquadro Scegli i log da includere nell'avviso, controlla la query e i risultati facendo clic su Visualizza l'anteprima dei log.

Ti consigliamo di creare la query nel riquadro Query di Esplora log. In questo riquadro viene visualizzata anche la query creata nel riquadro Query, ad esempio:
```
log_id("syslog")
severity = "NOTICE"
jsonPayload.result !~ "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.|$)){4}$"
```
Se necessario, puoi modificare la query in questo riquadro. Se modifichi la query, controlla i risultati facendo clic su Visualizza l'anteprima dei log.
Tocca Avanti.
Seleziona il tempo minimo tra le notifiche. Questo valore consente di controllare il numero di notifiche che ricevi da questo avviso se viene attivato più volte. Per questo esempio, seleziona 5 min dalle opzioni.
(Facoltativo) Seleziona la durata della chiusura automatica dell'incidente. Per impostazione predefinita, la durata della chiusura automatica dell'incidente è impostata su 7 giorni.
Tocca Avanti.
Seleziona uno o più canali di notifica per il tuo avviso. In questo esempio, seleziona un canale di notifica via email.

Se hai già configurato un canale di notifica via email, puoi selezionarlo dall'elenco. In caso contrario, fai clic su Gestisci canali di notifica e aggiungi un canale email. Per informazioni sulla creazione dei canali di notifica, vedi Gestione dei canali di notifica.
Fai clic su Salva.

L'avviso basato su log è ora pronto per essere testato.

Testa l'avviso basato su log di esempio

Per testare l'avviso che hai creato, puoi scrivere manualmente una voce di log che corrisponda alla query. Per scrivere la voce di log:

Configura la seguente voce di log modificando la variabile PROJECT_ID nel tuo ID progetto:

{
  "entries": [
  {
    "logName": "projects/PROJECT_ID/logs/syslog",
    "jsonPayload": {
      "type": "Configuration change",
      "action": "Set network address",
      "result": "999.027.405.1",
    },
    "severity": "NOTICE",
    "resource": {
      "type": "generic_task",
      "labels" : {
        "project_id": "PROJECT_ID",
        "location": "us-east1",
        "namespace": "fake-task-2",
        "job": "write-log-entry",
        "task_id": "11",
      },
    },
  },
  ],
}

Vai alla pagina di riferimento di logEntries.write o fai clic sul pulsante seguente:

Vai a logEntries.write
Copia la voce di log configurata in precedenza.
Nel riquadro Prova questa API, segui questi passaggi:
1. Sostituisci il contenuto del campo Corpo della richiesta in Explorer API con la voce di log copiata nel passaggio precedente.
2. Fai clic su Execute (Esegui). Se richiesto, segui il flusso di autenticazione.
  
  Se la chiamata logEntries.write ha esito positivo, riceverai un codice di risposta 200 HTTP e un corpo della risposta vuoto, {}. Per ulteriori informazioni su Explorer API, consulta Utilizzo di Explorer API nella documentazione di Monitoring. Explorer API funziona allo stesso modo con l'API Logging.

La voce di log corrisponde al filtro specificato per l'avviso nei seguenti modi:

Il valore logName specifica il log syslog nel tuo progetto Google Cloud.
Il valore severity per questa voce di log è NOTICE.
Il valore jsonPayload.result non è un indirizzo IPv4 valido.

Dopo aver scritto la voce di log, si verifica la seguente sequenza:

La nuova voce di log viene visualizzata in Esplora log e attiva l'avviso.
Viene aperto un incidente in Cloud Monitoring.
Riceverai una notifica relativa all'incidente. Se hai configurato un canale di notifica via email, la notifica sarà simile al seguente screenshot:

Puoi fare clic su Visualizza incidente nell'email per visualizzarlo in Cloud Monitoring. Per ulteriori informazioni sugli incidenti, consulta Gestione degli incidenti per gli avvisi basati su log.

Altri scenari: avvisi sugli audit log

L'esempio in Creazione di un avviso basato su log è artificiale. In genere non si crea un avviso e poi si scrivono manualmente le voci di log per attivarlo. Le voci di log sono in genere scritte da applicazioni o altri servizi. Tuttavia, l'origine delle voci di log non è importante; per gli avvisi basati su log, ciò che conta è la query utilizzata per selezionare le voci di log.

Le seguenti sezioni descrivono scenari realistici per gli avvisi basati su log in base ai contenuti degli audit log. Ogni scenario illustra come creare una query che isola le voci dell'audit log desiderate. In caso contrario, la procedura per creare gli avvisi basati su log è la stessa visualizzata in Creazione di un avviso basato su log.

Avvisi sull'accesso umano ai segreti

Supponiamo che il tuo progetto archivi i secret in Secret Manager e che alcuni di questi secret siano utilizzati solo per gli account di servizio. Fatta eccezione per circostanze insolite, gli utenti umani non accedono mai a questi secret.

Se hai abilitato l'audit logging per Secret Manager, a ogni tentativo riuscito di accedere a un secret viene creata una voce di audit log. Ogni voce include il nome del secret e l'identità del chiamante.

Puoi creare un avviso basato su log che ti invii una notifica quando un utente umano accede a un secret.

Di seguito è riportato un estratto di una voce di audit log scritta da Secret Manager. L'estratto mostra i campi utili per la creazione della query per un avviso basato su log:

{
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "serviceName": "secretmanager.googleapis.com",
    "methodName": "google.cloud.secretmanager.v1.SecretManagerService.AccessSecretVersion",
    "authenticationInfo": {
      "principalEmail": "my-svc-account@PROJECT_ID.iam.gserviceaccount.com",
      "serviceAccountDelegationInfo": [],
      "principalSubject": "serviceAccount:my-svc-account@PROJECT_ID.iam.gserviceaccount.com"
    },
    ...
  },
  ...
}

I seguenti protoPayload sottocampi sono di particolare interesse:

@type: indica che si tratta di una voce di log di controllo.
serviceName: registra il servizio che ha scritto la voce dell'audit log. Utilizza questo campo per identificare le voci scritte da Secret Manager.
methodName: identifica il metodo per cui è stata scritta la voce di audit log. Utilizza questo campo per identificare l'azione che ha causato la creazione di questa voce. In questo esempio si tratta del metodo AccessSecretVersion.
authenticationInfo.principalEmail: registra l'account che ha richiamato il metodo nel campo methodName. Il valore previsto per questo campo è un account di servizio, che termina con gserviceaccount.com.

Per trovare le voci di log per l'accesso ai secret da parte di un utente umano, cerca le voci di audit log scritte da Secret Manager. Vuoi trovare le voci di log in cui il metodo AccessSecretVersion è stato richiamato da un'entità che non termina con gserviceaccount.com. La seguente query isola queste voci di log:

protoPayload.@type = "type.googleapis.com/google.cloud.audit.AuditLog"
protoPayload.serviceName = "secretmanager.googleapis.com"
protoPayload.methodName =~ "AccessSecretVersion$"
protoPayload.authenticationInfo.principalEmail !~ "gserviceaccount.com$"

Per creare un avviso basato su log per l'accesso da parte di persone fisiche ai secret, utilizza questa query nel riquadro Scegli i log da includere nell'avviso.

Avvisi sugli eventi di decrittografia

L'analisi nell'esempio precedente può essere adattata ad altri servizi. Ad esempio, se utilizzi Cloud Key Management Service per criptare e decriptare i dati sensibili, puoi utilizzare gli audit log generati da Cloud KMS per rilevare quando un utente umano decripta un valore.

Per trovare le voci di log per la decrittografia eseguite da un utente umano, cerca le voci di audit log scritte da Cloud KMS. Vuoi trovare le voci di log in cui il metodo Decrypt è stato richiamato da un'entità che non termina con gserviceaccount.com, che indica un account di servizio. La seguente query isola queste voci di log:

protoPayload.@type = "type.googleapis.com/google.cloud.audit.AuditLog"
protoPayload.serviceName = "cloudkms.googleapis.com"
protoPayload.methodName = "Decrypt"
protoPayload.authenticationInfo.principalEmail !~ "gserviceaccount.com$"

Per creare un avviso basato su log per la decrittografia da parte di un utente umano, utilizza questa query nel riquadro Scegli i log da includere nel riquadro di avviso.

Gestisci gli avvisi basati su log in Monitoring

Puoi visualizzare, modificare ed eliminare gli avvisi basati su log utilizzando la console Google Cloud per Monitoring o l'API Monitoring. Questo documento descrive come gestire i criteri di avviso utilizzando la console Google Cloud. Per informazioni sull'utilizzo dell'API Monitoring per gestire i criteri di avviso, consulta Gestione dei criteri di avviso per API.

Per visualizzare un elenco di tutti i criteri di avviso nel tuo progetto Google Cloud, esegui una di queste operazioni:

Per passare da Logging:
1. Nel pannello di navigazione della console Google Cloud, seleziona Logging, quindi Esplora log:
  Vai a Esplora log
2. Nell'intestazione del riquadro Risultati delle query, menu Azioni e seleziona Gestisci avvisi.
Per passare da Monitoring:
1. Nel pannello di navigazione della console Google Cloud, seleziona Monitoring e poi Avvisi:
  Vai ad Avvisi
2. Per visualizzare tutti i criteri e attivare i filtri, nel riquadro Norme fai clic su Visualizza tutti i criteri.

Entrambe queste azioni ti indirizzano alla pagina Criteri di Monitoring, in cui sono elencati tutti i criteri di avviso presenti nel tuo progetto Google Cloud.

Aggiungi filtri per limitare i criteri di avviso elencati. Ciascun filtro è composto da un nome e da un valore. Ad esempio, puoi impostare il valore in modo che sia una corrispondenza esatta per il nome di una norma o una corrispondenza parziale. Le corrispondenze non sono sensibili alle maiuscole. Se specifichi più filtri, questi vengono uniti implicitamente da un AND logico, a meno che non inserisci un filtro OR. Il seguente screenshot elenca i criteri di avviso attualmente attivati creati dopo il 1° gennaio 2021:

Elenco dei criteri di avviso attivati creati dopo il 1° gennaio 2021.

Nella pagina Criteri puoi modificare, eliminare, copiare, attivare o disattivare un criterio di avviso:

Per modificare o copiare un criterio, fai clic su Altre opzioni e seleziona l'opzione che ti interessa. La modifica e la copia di un criterio sono simili alla procedura descritta in Creazione di un avviso basato su log . Puoi modificare e, in alcuni casi, eliminare i valori nei campi. Al termine, fai clic su Salva.

Puoi anche modificare un criterio di avviso basato su log facendo clic sul suo nome nell'elenco dei criteri.
Per eliminare un criterio, fai clic su Altre opzioni e seleziona Elimina. Nella finestra di dialogo di conferma, seleziona Elimina.
Per abilitare o disabilitare il criterio di avviso, fai clic sul pulsante di attivazione/disattivazione sotto l'intestazione Abilitato.

Crea un avviso basato su log utilizzando l'API Monitoring

Puoi creare avvisi basati su log utilizzando l'API Monitoring. Devi fornire all'API Monitoring le stesse informazioni che fornisci quando utilizzi Esplora log nella console Google Cloud:

Un nome e una descrizione per l'avviso.
I log per cui desideri ricevere una notifica.
Il tempo che intercorre tra le notifiche.
Il tempo per la chiusura automatica degli incidenti.
A chi inviare la notifica.

Per creare criteri di avviso utilizzando l'API Monitoring, devi creare un oggetto AlertPolicy e inviarlo al metodo alertPolicies.create.

Prima di poter utilizzare l'API Monitoring, devi abilitare l'API e disporre dell'autorizzazione per utilizzarla. Per ulteriori informazioni, consulta la seguente documentazione:

Struttura dei criteri di avviso

L'API Monitoring rappresenta un criterio di avviso utilizzando la struttura AlertPolicy. La struttura AlertPolicy ha diverse strutture incorporate, tra cui una descrizione della condizione che attiva l'avviso. I criteri di avviso basati su log differiscono da quelli basati su metriche per i seguenti aspetti:

Puoi descrivere la condizione utilizzando il tipo di condizione LogMatch. I criteri di avviso basati sulle metriche utilizzano tipi di condizioni diversi.
Un criterio di avviso basato su log può avere una sola condizione.
Puoi specificare il tempo che intercorre tra le notifiche e il periodo di chiusura automatica degli incidenti includendo una struttura AlertStrategy. I criteri di avviso basati sulle metriche non includono un intervallo di tempo tra le notifiche.

Questa sezione descrive come creare un criterio di avviso basato su log. Per il tipo di condizione in uso, questi criteri sono diversi dai criteri di avviso basati su metriche. Per gli avvisi basati su log, il tipo di condizione è LogMatch. Quando utilizzi l'API Monitoring per gestire i criteri di avviso, non esistono differenze nel modo in cui elenchi, modifichi o elimini le metriche e i criteri basati su log. Gestione dei criteri di avviso tramite API descrive come creare, elencare, modificare ed eliminare i criterio di avviso utilizzando l'API Monitoring.

Progetta il criterio di avviso

La sezione Crea un avviso basato su log con Esplora log descrive un modo per creare un avviso basato su log. Questa sezione mostra come creare un avviso basato su log che ti avvisi quando una voce di log syslog ha un livello di gravità NOTICE e un indirizzo IPv4 non valido nel campo jsonPayload.result.

Per creare lo stesso avviso basato su log utilizzando l'API Monitoring, devi creare un oggetto AlertPolicy che abbia la seguente struttura JSON:

{
  "displayName": "Network address: invalid IPv4 value (API)",
  "documentation": {
    "content": "Log-based alert in project ${project} detected an invalid IPv4 value.",
    "mimeType": "text/markdown"
  },

  "conditions": [
    {
      "displayName": "Log match condition: invalid IP addr (API)",
      "conditionMatchedLog": {
        "filter": "log_id(\"syslog\") severity = \"NOTICE\" jsonPayload.result !~ \"^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\\.|$)){4}$\"",
      },
    }
  ],
  "combiner": "OR",

  "alertStrategy": {
    "notificationRateLimit": {
      "period": "300s"
    },
    "autoClose": "604800s",
  },

  "notificationChannels": [
    "projects/PROJECT_ID/notificationChannels/CHANNEL_ID"
  ]
}

Questo codice JSON specifica le stesse informazioni specificate durante la creazione di un avviso basato su log utilizzando Esplora log. Le seguenti sezioni mappano i contenuti di questa struttura AlertPolicy ai passaggi che segui quando utilizzi Esplora log per creare un avviso basato su log. Il valore del campo conditionMatchedLog è una struttura LogMatch.

Fornisci un nome e una descrizione

Un criterio di avviso ha un nome visualizzato e la documentazione associata che viene fornita con notifiche per aiutare gli utenti che possono rispondere. In Esplora log, questi campi sono denominati Nome avviso e Descrizione avviso. Rappresenti questi valori in una struttura AlertPolicy nel seguente modo:

{
  "displayName": "Network address: invalid IPv4 value (API)",
  "documentation": {
    "content": "Log-based alert in project ${project} detected an invalid IPv4 value.",
    "mimeType": "text/markdown"
  },
  ...
}

In questo esempio, il valore di displayName include "(API)", in modo che tu possa distinguere tra i due criteri di esempio quando visualizzi l'elenco di criteri nella console Google Cloud. La pagina Criteri di Monitoring elenca i criteri in base al nome visualizzato e indica se si basano su metriche o log. Per maggiori informazioni, consulta Gestire gli avvisi basati su log in Monitoring.

Il campo documentation include, nel sottocampo content, la descrizione che potresti fornire quando utilizzi Esplora log. Il secondo sottocampo, mimeType, è obbligatorio quando specifichi un valore per il campo documentation. L'unico valore valido è "text/markdown".

Scegli i log per cui desideri ricevere una notifica

Un criterio di avviso basato su log ha una singola condizione. In Esplora log, specifichi la condizione quando fornisci una query nel campo Definisci le voci di log per le quali inviare un avviso. Rappresenti questi valori in una struttura AlertPolicy nel seguente modo:

{ ...
  "conditions": [
    {
      "displayName": "Log match condition: invalid IP addr (API)",
      "conditionMatchedLog": {
        "filter": "log_id(\"syslog\" severity = \"NOTICE\" jsonPayload.result !~ \"^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\\.|$)){4}$\"",
      },
    }
  ],
  "combiner": "OR",
  ...
}

Il campo conditions accetta un elenco di strutture Condition, anche se un criterio di avviso basato su log deve avere una sola condizione. Ogni elemento Condition ha un nome visualizzato e una descrizione della condizione.

Il valore del campo displayName è una breve descrizione della condizione. Quando utilizzi Esplora log per creare avvisi basati su log, il nome visualizzato è sempre "Condizione di corrispondenza dei log". Quando utilizzi l'API Monitoring, puoi fornire un nome visualizzato più preciso. È obbligatorio indicare un valore.
Il valore del campo conditionMatchedLog è una struttura LogMatch e il valore del campo filter è la query specificata in Esplora log. Poiché questa query viene fornita come valore di un campo JSON, l'intera query viene visualizzata tra virgolette ed eventuali virgolette nella query stessa devono essere precedute dal carattere di escape \ (barra rovesciata).
La struttura LogMatch include anche un campo facoltativo labelExtractors. Puoi utilizzare gli estrattori di etichette per scrivere etichette personalizzate dalle voci di log e fare riferimento a queste etichette nelle notifiche.

Ad esempio, per estrarre il valore dell'etichetta labels."compute.googleapis.com/resource_id" dalla voce di log in un'etichetta denominata vm_identifier, la condizione precedente potrebbe essere la seguente:
```
"conditions": [
  {
    "displayName": "Log match condition: invalid IP addr (API)",
    "conditionMatchedLog": {
      "filter": "log_id(\"syslog\" severity = \"NOTICE\" jsonPayload.result !~ \"^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\\.|$)){4}$\"",
      "labelExtractors": {
        "vm_identifier": "EXTRACT(labels.\"compute.googleapis.com/resource_id\")"
      }
    },
  }
],
```
Utilizza la funzione EXTRACT per associare l'intero valore oppure la REGEXP_EXTRACT per associare sottostringhe basate su espressioni regolari. Si tratta delle stesse funzioni utilizzate per l'estrazione delle etichette nelle metriche basate su log. Per ulteriori informazioni, consulta Creare un'etichetta.

Puoi utilizzare queste etichette estratte nella documentazione degli avvisi in modo che vengano segnalate nelle notifiche. Nel campo documentation del criterio di avviso, fai riferimento alle etichette estratte utilizzando una variabile nel formato ${log.extracted_label.KEY}, dove KEY è il nome assegnato all'etichetta estratta.

L'esempio seguente mostra come fare riferimento alla chiave per l'etichetta estratta vm_identifier, in modo che il valore dell'etichetta di log labels."compute.googleapis.com/resource_id" sia incluso nelle notifiche di avviso:
```
"documentation": {
  "content": "Log-based alert in project ${project} detected an
   invalid IPv4 value on VM with ID ${log.extracted_label.vm_identifier}.",
  "mimeType": "text/markdown"
},
```

Il valore del campo combiner specifica come combinare i risultati di più condizioni nei criteri di avviso basati su metriche. Puoi utilizzare una sola condizione negli avvisi basati su log e devi specificare il campo combiner con il valore "OR". Non puoi creare avvisi basati su log con più condizioni.

Imposta valori di notifica e chiusura automatica

Un criterio di avviso per un avviso basato su log specifica il tempo minimo tra le notifiche. In Esplora log, seleziona un valore dal menu Tempo tra le notifiche. Per rappresentare questo valore in una struttura AlertPolicy, specifica un valore in secondi per il campo period di una struttura NotificationRateLimit incorporata in una struttura AlertStrategy.

Analogamente, il criterio di avviso include il periodo per la chiusura automatica degli incidenti. Il valore predefinito è 7 giorni. In Esplora log, puoi selezionare un valore diverso dal menu Durata della chiusura automatica dell'incidente. L'opzione corrisponde al campo autoclose nella struttura dell'API AlertStrategy. Quando utilizzi questo campo, specifica il valore in secondi. Il valore minimo è 1800 secondi o 30 minuti.

{ ...
  "alertStrategy": {
    "notificationRateLimit": {
      "period": "300s"
    },
    "autoClose": "604800s",
  },
  ...
}

Il valore del campo period in questo esempio, 300s, equivale a 5 minuti. Il valore autoclose, 604800s, equivale a 7 giorni.

Specifica a chi inviare la notifica

Un criterio di avviso può includere un elenco di canali di notifica. In Esplora log, puoi selezionare i canali da un menu. Per rappresentare questi valori in una struttura AlertPolicy, fornisci un elenco di uno o più nomi di risorse per gli oggetti NotificationChannel configurati:

{ ...
  "notificationChannels": [
    "projects/PROJECT_ID/notificationChannels/CHANNEL_ID"
  ]
}

Quando crei un canale di notifica, gli viene assegnato un nome di risorsa. Per informazioni sul recupero dell'elenco dei canali di notifica disponibili, che include i nomi delle risorse, consulta Recupero dei canali nella documentazione di Monitoring. Non puoi recuperare gli ID canale utilizzando la console Google Cloud.

Invia il criterio di avviso all'API Monitoring

Per creare un criterio di avviso utilizzando l'API Monitoring, devi creare un oggetto AlertPolicy e inviarlo al metodo alertPolicies.create. Puoi richiamare alertPolicies.create utilizzando Google Cloud CLI, chiamando direttamente l'API Monitoring.

Puoi anche creare avvisi basati su log utilizzando le librerie client per C#, Go, Java, Python e Ruby. Potresti anche essere in grado di utilizzare altre librerie client; la libreria per la tua lingua deve includere il tipo di condizione LogMatch.

Per creare un criterio di avviso utilizzando gcloud CLI, procedi come segue:

Inserisci la rappresentazione JSON del criterio di avviso in un file di testo, ad esempio, in un file chiamato alert-invalid-ip.json.

Passa questo file JSON a gcloud CLI utilizzando il seguente comando:

gcloud alpha monitoring policies create --policy-from-file="alert-invalid-ip.json"

Se l'esito è positivo, questo comando restituisce il nome della risorsa del nuovo criterio, ad esempio:
```
Created alert policy [projects/PROJECT_ID/alertPolicies/POLICY_ID].
```

Per creare un criterio di avviso chiamando direttamente alertPolicies.create, puoi utilizzare lo strumento Explorer API come segue:

Vai alla pagina di riferimento di alertPolicies.create.
Nel riquadro Prova questa API, segui questi passaggi:
1. Nel campo name, inserisci il seguente valore:
```
projects/PROJECT_ID
```
2. Copia la rappresentazione JSON del criterio di avviso e sostituisci i contenuti del campo Corpo della richiesta in Explorer API con il criterio di avviso copiato.
3. Fai clic su Execute (Esegui).
  
  Se la chiamata alertPolicies.create ha esito positivo, riceverai un codice di risposta HTTP 200 e un corpo della risposta vuoto, {}. Per ulteriori informazioni su Explorer API, consulta Utilizzo di Explorer API nella documentazione di Monitoring.

Per saperne di più sulla creazione di criteri di avviso tramite l'API Monitoring, consulta Creazione di criteri. Gli esempi contenuti nel documento utilizzano tipi di condizioni per i criteri di avviso basati su metriche, ma i principi sono gli stessi.

Esegui il test del criterio di avviso

Per testare il nuovo criterio di avviso, puoi utilizzare la stessa procedura descritta in Testare l'esempio di avviso basato su log.

Esempio: creare un avviso quando una voce di log contiene una stringa di testo

In questo esempio viene utilizzata la console Google Cloud per creare un criterio di avviso, Esplora log per visualizzare le voci di log e Google Cloud CLI per scrivere una voce di log:

Nel pannello di navigazione della console Google Cloud, seleziona Logging, quindi Esplora log:
Vai a Esplora log
Nel riquadro Query, inserisci la seguente query dopo aver aggiornato il valore di PROJECT_ID:
```
logName="projects/PROJECT_ID/logs/test-log"
textPayload:"Oops"
```
La query cerca nel log il nome test-log le voci di log che hanno un campo textPayload contenente la stringa "Spiacenti".
Fai clic su Crea avviso e completa la finestra di dialogo. Devi inserire un nome per il criterio, ad esempio Alert on Oops. La query inserita nel passaggio precedente viene inclusa automaticamente nel criterio di avviso.
Per testare il criterio di avviso, apri Cloud Shell ed esegui questo comando:
```
gcloud logging write test-log --severity=ERROR --payload-type=text 'This log entry contains Oops'
```
Il comando precedente scrive una voce nel log denominato test-log. La voce ha un livello di gravità ERROR e include un campo textPayload.
In Esplora log, fai clic su Esegui query.

Dopo aver aggiornato la visualizzazione, puoi visualizzare i dettagli della voce di log che hai scritto nel passaggio precedente.
Per visualizzare l'avviso, nel riquadro di navigazione, seleziona Monitoraggio e poi Avvisi. Il riquadro Incidenti mostra l'incidente e i dettagli sul criterio di avviso.

Se non vedi un incidente quando apri la pagina Avvisi, attendi qualche minuto e poi aggiorna la pagina.

Non vedrai un altro incidente o non riceverai un'altra notifica se ripeti immediatamente il comando di Google Cloud CLI. Le impostazioni dei criterio di avviso specificano il periodo di tempo minimo tra gli incidenti. Puoi visualizzare e cambiare queste impostazioni modificando il criterio.