Configurare i criteri di avviso basati su log

Puoi configurare un criterio di avviso per ricevere una notifica ogni volta che un messaggio specifico viene visualizzato nei log inclusi. Ad esempio, se vuoi sapere quando un log di controllo registra un determinato messaggio di accesso ai dati, puoi ricevere una notifica quando viene visualizzato il messaggio. Questi tipi di criteri di avviso sono chiamati criteri di avviso basati su log. Questo documento descrive come eseguire le seguenti operazioni utilizzando la console Google Cloud e l'API Cloud Monitoring:

  • Crea e testa un criterio di avviso basato su log.
  • Modifica un criterio di avviso basato su log.
  • Elimina un criterio di avviso basato su log.

Prima di iniziare

Consulta il confronto degli avvisi per determinare se i criteri di avviso basati su log sono adatti ai dati nei log. Ad esempio:

  • I criteri di avviso basati su log non operano sui log esclusi.

  • Non puoi utilizzare i criteri di avviso basati su log per ricavare i conteggi dai log. Per ottenere i conteggi, devi utilizzare le metriche basate su log.

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

Creare un criterio di avviso basato su log utilizzando Esplora log

Puoi creare criterio di avviso basati su log dalla pagina Esplora log nella console Google Cloud o utilizzando l'API Monitoring. Questa sezione descrive come creare criteri di avviso basati su log utilizzando Esplora log. Per informazioni sull'API Monitoring, consulta Creare un criterio di avviso basato su log utilizzando l'API Monitoring.

L'interfaccia di Esplora log ti guida attraverso i seguenti passaggi:

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

Ad esempio, supponiamo che tu abbia un'applicazione che scriva una syslog voce di log con gravità NOTICE quando l'applicazione modifica un indirizzo di rete. Le voci di log per le modifiche dell'indirizzo di rete includono un payload JSON simile al seguente:

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

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

Per creare questo criterio di avviso:

  1. Nella console Google Cloud, vai alla pagina Esplora log:

    Vai a Esplora log

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

  2. Utilizza il riquadro Query per creare una query che corrisponda al messaggio che vuoi utilizzare nel criterio di avviso basato su log.

    Ad esempio, per trovare le 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}$"

    Fai clic su Esegui query per convalidare la query.

  3. Nella barra degli strumenti Risultati delle query, espandi il menu Azioni e seleziona Crea avviso di log.

  4. Nel riquadro Dettagli avviso, assegna un nome e una descrizione al criterio di avviso:

    1. Inserisci un nome per il criterio di 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à delle norme. Gli incidenti e le notifiche mostrano il livello di gravità.

    3. Inserisci una descrizione per il criterio di avviso. Puoi anche includere informazioni che potrebbero aiutare il destinatario di una notifica a diagnosticare il problema. La seguente stringa riassume il motivo della notifica:

      Log-based alerting policy 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 variabili nei modelli di documentazione.

  5. Per passare al passaggio successivo, fai clic su Avanti.

  6. Nel riquadro Scegli i log da includere nell'avviso, controlla la query e i risultati facendo clic su Anteprima dei log.

    Ti consigliamo di creare la query nel riquadro Query di Esplora log. In questo riquadro viene visualizzata anche la query che hai creato 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 Anteprima dei log.

  7. Fai clic su Avanti.

  8. Seleziona il tempo minimo tra le notifiche. Questo valore consente di controllare il numero di notifiche che ricevi dal monitoraggio se questa condizione viene soddisfatta più volte. Per questo esempio, seleziona 5 min dalle opzioni.

  9. (Facoltativo) Seleziona la durata della chiusura automatica degli incidenti. Per impostazione predefinita, la durata della chiusura automatica degli incidenti è impostata su 7 giorni.

  10. Fai clic su Avanti.

  11. Seleziona uno o più canali di notifica per il criterio di 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, consulta la pagina Creare e gestire i canali di notifica.

  12. Fai clic su Salva.

Il criterio di avviso basato sui log è ora pronto per il test.

Testa il criterio di avviso basato su log di esempio

Per testare il criterio di avviso che hai creato, puoi scrivere manualmente una voce di log corrispondente alla query. Per scrivere la voce di log:

  1. Configura la seguente voce di log modificando la variabile PROJECT_ID con il 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",
      },
    },
  },
  ],
}

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

    Vai a logEntries.write

  3. Copia la voce di log configurata in precedenza.

  4. Nel riquadro Prova questa API, segui questi passaggi:

    1. Sostituisci i contenuti del campo Request body (Corpo della richiesta) in Explorer API con la voce di log copiata nel passaggio precedente.

    2. Fai clic su Execute (Esegui). Se richiesto, segui la procedura di autenticazione.

      Se la chiamata logEntries.write va a buon fine, viene visualizzato 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 monitoraggio. Explorer API funziona allo stesso modo con l'API Logging.

La voce di log corrisponde al filtro specificato per il criterio di avviso nei seguenti modi:

  • Il valore logName specifica il log syslog nel 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. La voce di log soddisfa la condizione del criterio di 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 allo screenshot seguente:

    Il criterio di avviso basato su log di esempio genera una notifica via email.

Puoi fare clic su Visualizza incidente nell'email per visualizzare l'incidente in Cloud Monitoring. Per ulteriori informazioni sugli incidenti, consulta Gestire gli incidenti relativi ai criteri di avviso basati su log.

Altri scenari: avvisi sugli audit log

L'esempio nella sezione Creare un criterio di avviso basato su log è artificiale. In genere, non crei un criterio di avviso e poi scrivi manualmente le voci di log che soddisfano la condizione del criterio di avviso. Le voci di log vengono generalmente scritte da applicazioni o altri servizi. Tuttavia, l'origine delle voci di log non è importante; per i criteri di avviso basati su log, ciò che conta è la query utilizzata per selezionare le voci di log.

Le sezioni seguenti descrivono scenari realistici per le norme di avviso basate su log in base ai contenuti dei log di controllo. Ogni scenario illustra come creare una query che selezioni le voci del log di controllo appropriate. In caso contrario, la procedura per creare i criteri di avviso basati su log è la stessa descritta in Creare un avviso basato su log.

Criteri di avviso che monitorano l'accesso dei secret da parte di una persona

Supponiamo che il tuo progetto memorizzi i secret in Secret Manager e che alcuni di questi secret siano destinati solo all'utilizzo da parte degli account di servizio. Tranne in circostanze insolite, gli utenti umani non accedono mai a questi secret.

Se hai attivato il logging di controllo per Secret Manager, ogni tentativo riuscito di accedere a un segreto crea una voce di log di controllo. Ogni voce include il nome del secret e l'identità dell'utente che chiama.

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

Di seguito è riportato un estratto di una voce di log di controllo scritta da Secret Manager. L'estratto mostra i campi utili per creare la 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 campi secondari protoPayload sono di particolare interesse:

  • @type: indica che questa voce di log è una voce di log di controllo.
  • serviceName: registra il servizio che ha scritto la voce di log di controllo. Utilizza questo campo per identificare le voci scritte da Secret Manager.
  • methodName: identifica il metodo per cui è stata scritta questa voce di log di controllo. 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 invocato 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, cerca le voci di log di controllo scritte da Secret Manager. Vuoi trovare le voci di log in cui il metodo AccessSecretVersion è stato invocato da un principale 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 criterio di avviso basato su log per l'accesso umano ai secret, utilizza questa query nel riquadro Scegli i log da includere nell'avviso.

Criteri di avviso che monitorano gli 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 i log di controllo generati da Cloud KMS per rilevare quando un utente decripta un valore.

Per trovare le voci di log relative alla decrittografia eseguita da un utente, cerca le voci di audit log scritte da Cloud KMS. Devi trovare le voci di log in cui il metodo Decrypt è stato invocato da un principale 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 criterio di avviso basato su log per la decrittografia eseguita da un utente, utilizza questa query nel riquadro Scegli i log da includere nell'avviso.

Gestire i criteri di avviso basati su log in Monitoraggio

Puoi visualizzare, modificare ed eliminare i criteri di avviso basati su log utilizzando la console Google Cloud per il monitoraggio 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 Gestire i criteri di avviso tramite API.

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

  • Per spostarti da Logging:

    1. Nella console Google Cloud, vai alla pagina Esplora log:

      Vai a Esplora log

      Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

    2. Nella barra degli strumenti Risultati delle query, espandi il menu Azioni e seleziona Gestisci avvisi di log.

  • Per spostarti da Monitoring:

    1. Nella console Google Cloud, vai alla pagina  Avvisi:

      Vai ad Avvisi

      Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

    2. Per visualizzare tutti i criteri e attivare i filtri, nel riquadro Criteri, fai clic su Visualizza tutti i criteri.

Entrambe le azioni portano alla pagina Criteri monitoring, che elenca tutti i criteri di avviso nel progetto Google Cloud.

Per limitare i criteri di avviso elencati, aggiungi filtri. Ogni filtro è composto da un nome e un valore. Ad esempio, puoi impostare il valore in modo che corrisponda esattamente al nome di un criterio o a 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. Lo screenshot seguente mostra i criteri di avviso abilitati e creati dopo il 1° gennaio 2021:

Elenco dei criteri di avviso abilitati 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 un'opzione. La modifica e la copia di un criterio è simile alla procedura descritta in Creare un criterio di 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 relativo 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 attivare o disattivare il criterio di avviso, fai clic sul pulsante di attivazione/disattivazione situato sotto l'intestazione Attivato.

Creare un criterio di avviso basato su log utilizzando l'API Monitoring

Puoi creare criteri di avviso basati su log utilizzando l'API Monitoring. Fornisci all'API Monitoring le stesse informazioni che fornisci quando utilizzi Esplora log nella console Google Cloud:

  • Un nome e una descrizione per il criterio di avviso.
  • I log per i quali vuoi ricevere una notifica.
  • Il tempo che intercorre tra le notifiche.
  • L'ora di 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 lAPI Monitoring, devi attivarla 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 contiene diverse strutture incorporate, tra cui una descrizione della condizione del criterio di avviso. I criteri di avviso basati su log differiscono da quelli basati su metriche nei seguenti modi:

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

Questa sezione descrive come creare un criterio di avviso basato su log. Questi criteri differiscono dai criteri di avviso basati su metriche per il tipo di condizione utilizzato. Per i criteri di avviso basati su log, il tipo di condizione è LogMatch. Quando utilizzi l'API Monitoring per gestire i criteri di avviso, non ci sono differenze nel modo in cui elenchi, modifichi o elimini i criteri basati su metriche e log. L'articolo Gestire i criteri di avviso tramite API descrive come creare, elencare, modificare ed eliminare i criterio di avviso utilizzando l'API Monitoring.

Regole di notifica

Quando crei un criterio di avviso basato su log, Logging crea un oggetto interno chiamato regola di notifica. La registrazione utilizza la regola di notifica per associare le voci di log in arrivo al filtro del criterio di avviso e poi per creare una notifica quando una voce corrisponde ai criteri del filtro. Non interagisci direttamente con la regola di notifica. Tuttavia, per creare un criterio di avviso basato su log, devi disporre dell'autorizzazione logging.notificationRules.create.

Progettare il criterio di avviso

La sezione Creare un criterio di avviso basato su log utilizzando Esplora log descrive un modo per creare un criterio di avviso basato su log. Questa sezione mostra come creare un criterio di avviso basato su log che ti invia una notifica 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 criterio di avviso basato su log utilizzando l'API Monitoring, crea un oggetto AlertPolicy simile alla seguente struttura JSON:

{
  "displayName": "Network address: invalid IPv4 value (API)",
  "documentation": {
    "content": "Log-based alerting policy 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 che specifichi quando crei un criterio di avviso basato su log utilizzando Esplora log. Le sezioni seguenti mappano i contenuti di questa struttura AlertPolicy ai passaggi da seguire 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 le notifiche per assistere gli utenti che rispondono. In Esplora log, questi campi sono denominati Nome avviso e Descrizione avviso. Rappresenta questi valori in una struttura AlertPolicy come segue:

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

In questo esempio, il valore di displayName include "(API)" in modo da poter distinguere i due criteri di esempio quando visualizzi l'elenco dei criteri nella console Google Cloud. La pagina Criteri di monitoraggio elenca i criteri in base al nome visualizzato e indica se il criterio si basa su metriche o log. Per ulteriori informazioni, consulta la pagina Gestire i criteri di avviso basati su log in Monitoraggio.

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

Scegli i log per i quali vuoi ricevere una notifica

Un criterio di avviso basato su log ha una singola condizione. In Esplora log, specifica la condizione quando fornisci una query nel campo Definisci voci di log per attivare l'avviso. Rappresenta questi valori in una struttura AlertPolicy come segue:

{ ...
  "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 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 criteri di avviso 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 e le eventuali virgolette all'interno della query stessa devono essere inserite con il carattere \ (barra).

  • La struttura LogMatch include anche un campo facoltativo labelExtractors. Puoi utilizzare gli estrattori di etichette per comporre etichette personalizzate dalle tue voci di log e poi 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 avere il seguente aspetto:

    "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 trovare una corrispondenza con l'intero valore o la funzione REGEXP_EXTRACT per trovare corrispondenze con le sottostringhe in base alle espressioni regolari. Si tratta della stessa funzione utilizzata per l'estrazione delle etichette nelle metriche basate su log. Per ulteriori informazioni, consulta Creare un'etichetta.

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

    L'esempio seguente mostra come fare riferimento alla chiave per l'etichetta vm_identifier estratta, in modo che il valore dell'etichetta log labels."compute.googleapis.com/resource_id" sia incluso nelle notifiche:

    "documentation": {
  "content": "Log-based alerting policy 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 nei criteri di avviso basati su log e devi specificare il campo combiner con il valore "OR". Non puoi creare criteri di avviso basati su log con più condizioni.

Impostare i valori di notifica e chiusura automatica

Un criterio di avviso basato su log specifica il tempo minimo tra le notifiche. In Esplora log, seleziona un valore dal menu Tempo tra le notifiche. Rappresenta questo valore in una struttura AlertPolicy specificando 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 autoclose campo nella struttura dell'API AlertStrategy. Quando utilizzi questo campo, specifica il valore in secondi. Il valore minimo è di 1800 secondi o 30 minuti.

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

Il valore del campo period in questo esempio, 300s, è equivalente 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, seleziona i canali da un menu. Rappresenta questi valori in una struttura AlertPolicy fornendo 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, viene assegnato un nome della risorsa. Per informazioni su come recuperare l'elenco dei canali di notifica disponibili, inclusi i relativi nomi delle risorse, consulta la sezione Recupero dei canali nella documentazione di monitoraggio. Non puoi ottenere 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 invocare alertPolicies.create utilizzando Google Cloud CLI, chiamando direttamente l'API Monitoring.

Puoi anche creare criteri di avviso basati su log utilizzando le librerie client per C#, Go, Java, Python e Ruby. Potresti anche 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, segui questi passaggi:

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

  2. Passa questo file JSON alla gcloud CLI utilizzando il seguente comando:

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

  3. In caso di esito positivo, questo comando restituisce il nome della risorsa del nuovo criterio, ad esempio:

    Created alerting 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:

  1. Vai alla pagina di riferimento alertPolicies.create.

  2. 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 Request body (Corpo della richiesta) in Esplora API con il criterio di avviso copiato.

    3. Fai clic su Execute (Esegui).

      Se la chiamata alertPolicies.create va a buon fine, viene visualizzato un codice di risposta HTTP200 e un corpo della risposta vuoto, {}. Per ulteriori informazioni su Explorer API, consulta Utilizzo di Explorer API nella documentazione di monitoraggio.

Per ulteriori informazioni sulla creazione di criteri di avviso utilizzando l'API Monitoring, consulta Creare criteri. Gli esempi riportati 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 Eseguire il test dell'avviso basato su log di esempio.

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

Questo esempio utilizza 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:

  1. Nella console Google Cloud, vai alla pagina Esplora log:

    Vai a Esplora log

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

  2. 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 con il nome test-log le voci di log che hanno un campo textPayload contenente la stringa "Oops".

  3. Nella barra degli strumenti Risultati delle query, espandi il menu Azioni e seleziona Crea avviso di log. Quindi, 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.

  4. Per testare il criterio di avviso, apri Cloud Shell ed esegui il seguente 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.

  5. In Esplora log, fai clic su Esegui query.

    Dopo l'aggiornamento della visualizzazione, puoi visualizzare i dettagli della voce di log che hai scritto nel passaggio precedente.

  6. Nella console Google Cloud, vai alla pagina  Avvisi:

    Vai ad Avvisi

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

    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.

Se ripeti immediatamente il comando Google Cloud CLI, non vedrai un altro incidente né riceverai un'altra notifica. Le impostazioni dei criterio di avviso specificano il periodo di tempo minimo tra gli incidenti. Puoi visualizzare e modificare queste impostazioni modificando il criterio.