Logbasierte Warnungen konfigurieren

Sie können logbasierte Benachrichtigungen verwenden, die Sie benachrichtigen, wenn eine bestimmte Nachricht in den betreffenden Logs angezeigt wird. Wenn Sie beispielsweise wissen möchten, wann eine bestimmte Nachricht zum Datenzugriff in einem Audit-Log aufgezeichnet wird, können Sie eine logbasierte Benachrichtigung erstellen, die der Nachricht entspricht und Sie benachrichtigt, wenn sie angezeigt wird. In diesem Dokument wird beschrieben, wie Sie mithilfe der Google Cloud Console und der Cloud Monitoring API Folgendes tun:

  • Logbasierte Benachrichtigung erstellen und testen
  • Logbasierte Benachrichtigung bearbeiten
  • Logbasierte Benachrichtigung löschen

Hinweise

Prüfen Sie den Benachrichtigungsvergleich, um zu ermitteln, ob logbasierte Benachrichtigungen für die Daten in Ihren Logs geeignet sind. Beispiel:

  • Logbasierte Benachrichtigungen funktionieren nicht bei ausgeschlossenen Logs.

  • Sie können keine logbasierten Benachrichtigungen verwenden, um Anzahlen aus Ihren Logs abzuleiten. Sie müssen stattdessen logbasierte Messwerte verwenden, um Anzahlen abzuleiten.

Zum Erstellen und Verwalten logbasierter Benachrichtigungen muss Ihre Rolle „Identity and Access Management“ die unter Berechtigungen für logbasierte Benachrichtigungen beschriebenen Berechtigungen enthalten.

Logbasierte Benachrichtigung mit dem Log-Explorer erstellen

Sie können logbasierte Benachrichtigungen auf der Seite Log-Explorer in der Google Cloud Console oder mithilfe der Monitoring API erstellen. In diesem Abschnitt wird beschrieben, wie Sie logbasierte Benachrichtigungen mit dem Log-Explorer erstellen. Informationen zum Erstellen logbasierter Benachrichtigungen mit der Monitoring API finden Sie unter Logbasierte Benachrichtigungen mit der Monitoring API erstellen.

Die Benutzeroberfläche von Log-Explorer zum Erstellen und Bearbeiten von logbasierten Benachrichtigungen führt Sie durch die folgenden Schritte:

  • Geben Sie einen Namen und eine Beschreibung für die Benachrichtigung ein.
  • Wählen Sie die Logs aus, für die Sie eine Benachrichtigung erhalten möchten.
  • Legen Sie die Zeit zwischen Benachrichtigungen fest.
  • Legen Sie die Zeit für das automatische Schließen von Vorfällen fest.
  • Geben Sie an, wer benachrichtigt werden soll.

Angenommen, Sie haben eine Anwendung, die einen syslog-Logeintrag mit dem Schweregrad NOTICE schreibt, wenn die Anwendung eine Netzwerkadresse ändert. Die Logeinträge für Änderungen der Netzwerkadresse enthalten eine JSON-Nutzlast, die in etwa so aussieht:

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

Sie möchten eine logbasierte Benachrichtigung erstellen, die Sie informiert, wenn eine ungültige IPv4-Adresse im Feld jsonPayload.result der Logeinträge in syslog mit dem Schweregrad NOTICE angezeigt wird.

So erstellen Sie die logbasierte Benachrichtigung:

  1. Wählen Sie im Navigationsbereich der Google Cloud Console Logging und anschließend Log-Explorer aus:

    Zum Log-Explorer

  2. Erstellen Sie im Bereich Abfrage eine Abfrage, die der Nachricht entspricht, die Sie in Ihrer logbasierten Benachrichtigung verwenden möchten.

    Für die Suche nach Logeinträgen mit dem Schweregrad NOTICE im Log syslog mit ungültigen IP-Adressen in der JSON-Nutzlast können Sie beispielsweise die folgende Abfrage verwenden:

    log_id("syslog")
    severity = "NOTICE"
    jsonPayload.result !~ "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.|$)){4}$"
    

    Verwenden Sie Abfrage ausführen im Bereich Abfrageergebnisse, um die Abfrage zu validieren.

  3. Klicken Sie im Header des Bereichs Abfrageergebnisse auf  Benachrichtigung erstellen. Wenn das Fenster schmal ist, wird stattdessen möglicherweise die Option Benachrichtigung erstellen im Menü Aktionen angezeigt.

  4. Geben Sie im Bereich Benachrichtigungsdetails einen Namen und eine Beschreibung für die Benachrichtigung ein:

    1. Geben Sie im Feld Name der Benachrichtigungsrichtlinie einen Namen für die Benachrichtigung ein. Beispiel: „Netzwerkadresse: ungültiger IPv4-Wert“.

    2. Wählen Sie eine Option aus dem Menü Schweregrad der Richtlinie aus. Bei Vorfällen und Benachrichtigungen wird der Schweregrad angezeigt.

    3. Geben Sie eine Beschreibung dieser Benachrichtigung ein. Sie können auch Informationen angeben, die dem Empfänger einer Benachrichtigung helfen können, das Problem zu diagnostizieren. Der folgende String fasst den Grund für die Benachrichtigung zusammen:

      Log-based alert in project ${project} detected an invalid IPv4 value.
      

      Informationen zum Formatieren und Anpassen des Inhalts dieses Felds finden Sie unter Markdown und Variablen in Dokumentationsvorlagen verwenden.

  5. Um mit dem nächsten Schritt fortzufahren, klicken Sie auf Weiter.

  6. Prüfen Sie im Bereich Logs auswählen, die in die Benachrichtigung aufgenommen werden sollen die Abfrage und die Ergebnisse. Klicken Sie dazu auf Logvorschau ansehen.

    Wir empfehlen, die Abfrage im Bereich Abfrage des Log-Explorers zu erstellen. Die Abfrage, die Sie im Bereich Abfrage erstellt haben, wird in diesem Bereich ebenfalls angezeigt. Beispiel:

    log_id("syslog")
    severity = "NOTICE"
    jsonPayload.result !~ "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.|$)){4}$"
    

    Bei Bedarf können Sie die Abfrage in diesem Bereich bearbeiten. Falls Sie die Abfrage bearbeiten, können Sie die Ergebnisse prüfen, indem Sie auf Logs anzeigen klicken.

  7. Klicken Sie auf Next (Weiter).

  8. Wählen Sie die Mindestdauer zwischen Benachrichtigungen aus. Mit diesem Wert können Sie die Anzahl der Benachrichtigungen dieser Art steuern, wenn sie mehrmals ausgelöst wird. Wählen Sie für dieses Beispiel 5 Min. aus den Optionen aus.

  9. Optional: Wählen Sie die Dauer für das automatische Schließen des Vorfalls aus. Standardmäßig ist die Dauer für das automatische Schließen von Vorfällen auf 7 Tage festgelegt.

  10. Klicken Sie auf Next (Weiter).

  11. Wählen Sie einen oder mehrere Benachrichtigungskanäle für Ihre Benachrichtigung aus. Wählen Sie für dieses Beispiel einen E-Mail-Benachrichtigungskanal aus.

    Wenn Sie bereits einen E-Mail-Benachrichtigungskanal konfiguriert haben, können Sie ihn aus der Liste auswählen. Wenn nicht, klicken Sie auf Benachrichtigungskanäle verwalten und fügen Sie einen E-Mail-Kanal hinzu. Informationen zum Erstellen von Benachrichtigungskanälen finden Sie unter Benachrichtigungskanäle verwalten.

  12. Klicken Sie auf Speichern.

Ihre logbasierte Benachrichtigung kann jetzt getestet werden.

Logbasierte Beispielbenachrichtigung testen

Um die von Ihnen erstellte Benachrichtigung zu testen, können Sie manuell einen Logeintrag schreiben, der der Abfrage entspricht. So schreiben Sie den Logeintrag:

  1. Konfigurieren Sie den folgenden Logeintrag, indem Sie die Variable PROJECT_ID in Ihre Projekt-ID ändern:

    {
      "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. Rufen Sie die Referenzseite logEntries.write auf oder klicken Sie auf die folgende Schaltfläche:

    Zu „logEntries.write“

  3. Kopieren Sie den zuvor konfigurierten Logeintrag.

  4. Führen Sie im Bereich API testen folgende Schritte aus:

    1. Ersetzen Sie den Inhalt des Felds Anfragetext in APIs Explorer durch den Logeintrag, den Sie im vorherigen Schritt kopiert haben.

    2. Klicken Sie auf Execute. Wenn Sie dazu aufgefordert werden, folgen Sie dem Authentifizierungsvorgang.

      Wenn der Aufruf logEntries.write erfolgreich ist, erhalten Sie einen HTTP 200-Antwortcode und einen leeren Antworttext: {}. Weitere Informationen zum APIs Explorer finden Sie in der Monitoring-Dokumentation unter APIs Explorer verwenden. Der APIs Explorer funktioniert genauso wie die Logging API.

Der Logeintrag stimmt mit dem für die Benachrichtigung angegebenen Filter auf folgende Weise überein:

  • Der Wert logName gibt das syslog-Log in Ihrem Google Cloud-Projekt an.
  • Der severity-Wert für diesen Logeintrag ist NOTICE.
  • Der jsonPayload.result-Wert ist keine gültige IPv4-Adresse.

Nach dem Schreiben des Logeintrags tritt die folgende Sequenz auf:

  • Der neue Logeintrag wird im Log-Explorer angezeigt und löst die Benachrichtigung aus.
  • Ein Vorfall wird in Cloud Monitoring geöffnet.
  • Sie erhalten dann eine Benachrichtigung für den Vorfall. Wenn Sie einen E-Mail-Benachrichtigungskanal konfiguriert haben, sieht die Benachrichtigung wie im folgenden Screenshot aus:

    Die logbasierte Beispielbenachrichtigung führt zu einer E-Mail-Benachrichtigung.

Sie können in der E-Mail auf Vorfall ansehen klicken, um den Vorfall in Cloud Monitoring aufzurufen. Weitere Informationen zu Vorfällen finden Sie unter Vorfälle für logbasierte Benachrichtigungen verwalten.

Andere Szenarien: Benachrichtigungen zu Audit-Logs

Das Beispiel unter Logbasierte Benachrichtigung erstellen ist künstlich. Normalerweise erstellen Sie keine Benachrichtigung und schreiben dann manuell Logeinträge, die die Benachrichtigung auslösen. Logeinträge werden normalerweise von Anwendungen oder anderen Diensten geschrieben. Die Quelle der Logeinträge spielt jedoch keine Rolle. Bei logbasierten Benachrichtigungen spielt die Abfrage eine Rolle, mit der Sie die Logeinträge auswählen.

In den folgenden Abschnitten werden realistische Szenarien für logbasierte Benachrichtigungen beschrieben, die auf dem Inhalt von Audit-Logs basieren. Jedes Szenario veranschaulicht, wie Sie eine Abfrage erstellen, mit der die gewünschten Audit-Log-Einträge isoliert werden. Ansonsten ist das Verfahren zum Erstellen logbasierter Benachrichtigungen dasselbe wie unter Logbasierte Benachrichtigung erstellen beschrieben.

Benachrichtigungen zum menschlichen Zugriff auf Secrets

Angenommen, Ihr Projekt speichert Secrets in Secret Manager und einige dieser Secrets sind nur für die Verwendung durch Dienstkonten vorgesehen. Außer unter ungewöhnlichen Umständen greifen menschliche Nutzer niemals auf diese Geheimnisse zu.

Wenn Sie das Audit-Logging für Secret Manager aktiviert haben, wird bei jedem erfolgreichen Versuch, auf ein Secret zuzugreifen, ein Audit-Logeintrag erstellt. Jeder Eintrag enthält den Namen des Secrets und die Identität des Aufrufers.

Sie können eine logbasierte Benachrichtigung erstellen, die Sie benachrichtigt, wenn ein Nutzer auf ein Secret zugreift.

Das folgende Beispiel zeigt einen Auszug aus einem Audit-Logeintrag, der von Secret Manager geschrieben wurde. Der Auszug zeigt die Felder, die zum Erstellen der Abfrage für eine logbasierte Benachrichtigung nützlich sind:

{
  "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"
    },
    ...
  },
  ...
}

Besonders interessant sind die folgenden protoPayload-Unterfelder:

  • @type: Gibt an, dass dieser Logeintrag ein Audit-Logeintrag ist.
  • serviceName: Zeichnet den Dienst auf, der den Audit-Logeintrag geschrieben hat. Verwenden Sie dieses Feld, um Einträge zu identifizieren, die von Secret Manager geschrieben wurden.
  • methodName: Gibt die Methode an, für die dieser Audit-Logeintrag geschrieben wurde. Mit diesem Feld können Sie die Aktion identifizieren, die zur Erstellung dieses Eintrags geführt hat. In diesem Beispiel ist es die Methode AccessSecretVersion.
  • authenticationInfo.principalEmail: Zeichnet das Konto auf, das die Methode im Feld methodName aufgerufen hat. Der erwartete Wert für dieses Feld ist ein Dienstkonto, das mit gserviceaccount.com endet.

Suchen Sie nach Audit-Logeinträgen, die von Secret Manager geschrieben wurden, um Logeinträge für den Secret-Zugriff durch einen menschlichen Nutzer zu finden. Sie möchten die Logeinträge finden, in denen die Methode AccessSecretVersion von einem Hauptkonto aufgerufen wurde, das nicht mit gserviceaccount.com endet. Die folgende Abfrage isoliert diese Logeinträge:

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

Verwenden Sie diese Abfrage im Bereich Logs auswählen, die in die Benachrichtigung aufgenommen werden sollen, um eine logbasierte Benachrichtigung für den menschlichen Zugriff auf Secrets zu erstellen.

Benachrichtigungen zu Entschlüsselungsereignissen

Die Analyse im vorherigen Beispiel kann an andere Dienste angepasst werden. Wenn Sie beispielsweise Cloud Key Management Service zum Verschlüsseln und Entschlüsseln sensibler Daten verwenden, können Sie mithilfe von von Cloud KMS generierten Audit-Logs erkennen, wenn ein menschlicher Nutzer einen Wert entschlüsselt.

Suchen Sie nach Audit-Logeinträgen von Cloud KMS, um Logeinträge für Entschlüsselungen zu finden, die von Nutzern durchgeführt wurden. Sie müssen die Logeinträge finden, in denen die Methode Decrypt von einem Hauptkonto aufgerufen wurde, das nicht mit gserviceaccount.com endet. Dies gibt ein Dienstkonto an. Die folgende Abfrage isoliert diese Logeinträge:

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

Verwenden Sie diese Abfrage im Bereich Logs auswählen, die in die Benachrichtigung aufgenommen werden sollen, um eine logbasierte Benachrichtigung für die Entschlüsselung durch einen menschlichen Nutzer zu erstellen.

Logbasierte Benachrichtigungen in Monitoring verwalten

Sie können logbasierte Benachrichtigungen mit der Google Cloud Console für Monitoring oder mit der Monitoring API ansehen, bearbeiten und löschen. In diesem Dokument wird beschrieben, wie Sie Benachrichtigungsrichtlinien mithilfe der Google Cloud Console verwalten. Informationen zur Verwendung der Monitoring API zum Verwalten von Benachrichtigungsrichtlinien finden Sie unter Benachrichtigungsrichtlinien nach API verwalten.

Führen Sie einen der folgenden Schritte aus, um eine Liste aller Benachrichtigungsrichtlinien in Ihrem Google Cloud-Projekt aufzurufen:

  • So navigieren Sie über Logging:

    1. Wählen Sie im Navigationsbereich der Google Cloud Console Logging und anschließend Log-Explorer aus:

      Zum Log-Explorer

    2. Wählen Sie in der Kopfzeile des Bereichs Abfrageergebnisse im Menü Aktionen die Option Benachrichtigungen verwalten aus.

  • So navigieren Sie über Monitoring:

    1. Wählen Sie im Navigationsbereich der Google Cloud Console Monitoring und anschließend  Benachrichtigungen aus:

      Zu Benachrichtigungen

    2. Klicken Sie im Bereich Richtlinien auf Alle Richtlinien ansehen, um alle Richtlinien anzusehen und die Filterung zu aktivieren.

Beide Aktionen führen Sie zur Seite Monitoring-Richtlinien, auf der alle Benachrichtigungsrichtlinien in Ihrem Google Cloud-Projekt aufgeführt sind.

Fügen Sie Filter hinzu, um die aufgeführten Benachrichtigungsrichtlinien einzuschränken. Jeder Filter besteht aus einem Namen und einem Wert. Sie können den Wert beispielsweise so festlegen, dass er genau oder teilweise mit einem Richtliniennamen übereinstimmt. Beim Abgleich wird nicht zwischen Groß- und Kleinschreibung unterschieden. Wenn Sie mehrere Filter angeben, werden die Filter implizit durch einen logischen AND verbunden, sofern Sie keinen OR-Filter einfügen. Der folgende Screenshot zeigt die derzeit aktivierten Benachrichtigungsrichtlinien, die nach dem 1. Januar 2021 erstellt wurden:

Liste der aktivierten Benachrichtigungsrichtlinien, die nach dem 1. Januar 2021 erstellt wurden

Auf der Seite Richtlinien können Sie eine Benachrichtigungsrichtlinie bearbeiten, löschen, kopieren, aktivieren oder deaktivieren:

  • Klicken Sie zum Bearbeiten oder Kopieren einer Richtlinie auf Mehr Optionen und wählen Sie die entsprechende Option aus. Beim Bearbeiten und Kopieren einer Richtlinie gehen Sie ähnlich wie unter Logbasierte Benachrichtigung erstellen beschrieben vor. Sie können die Werte in den Feldern ändern und in einigen Fällen löschen. Wenn Sie fertig sind, klicken Sie auf Save (Speichern).

    Sie können eine logbasierte Benachrichtigungsrichtlinie auch bearbeiten. Klicken Sie dazu in der Liste der Richtlinien auf ihren Namen.

  • Klicken Sie zum Löschen einer Richtlinie auf Mehr Optionen und wählen Sie Löschen aus. Wählen Sie im Bestätigungsdialogfeld noch einmal Löschen aus.

  • Klicken Sie zum Aktivieren oder Deaktivieren der Benachrichtigungsrichtlinie auf die Ein/Aus-Schaltfläche unter der Überschrift Aktiviert.

Logbasierte Benachrichtigung mit der Monitoring API erstellen

Mit der Monitoring API können Sie logbasierte Benachrichtigungen erstellen. Für die Monitoring API müssen Sie dieselben Informationen angeben wie bei Verwendung des Log-Explorers in der Google Cloud Console:

  • Einen Namen und eine Beschreibung für die Benachrichtigung
  • Die Logs, für die Sie eine Benachrichtigung erhalten möchten
  • Die Zeit zwischen den Benachrichtigungen
  • Die Zeit für das automatische Schließen von Vorfällen.
  • Wer benachrichtigt werden soll

Zum Erstellen von Benachrichtigungsrichtlinien mithilfe der Monitoring API erstellen Sie ein AlertPolicy-Objekt und senden es an die Methode alertPolicies.create.

Bevor Sie die Monitoring API verwenden können, müssen Sie die API aktivieren und die Berechtigung zu ihrer Verwendung haben. Weitere Informationen erhalten Sie in dieser Dokumentation:

Struktur von Benachrichtigungsrichtlinien

Die Monitoring API stellt eine Benachrichtigungsrichtlinie mithilfe der AlertPolicy-Struktur dar. Die AlertPolicy-Struktur hat mehrere eingebettete Strukturen, darunter eine Beschreibung der Bedingung, die die Benachrichtigung auslöst. Logbasierte Benachrichtigungsrichtlinien unterscheiden sich in folgenden Punkten von messwertbasierten Benachrichtigungsrichtlinien:

  • Die Bedingung wird von Ihnen mithilfe des LogMatch-Bedingungstyps beschrieben. Messwertbasierte Benachrichtigungsrichtlinien verwenden unterschiedliche Bedingungstypen.
  • Eine logbasierte Benachrichtigungsrichtlinie kann nur eine Bedingung haben.
  • Mit einer AlertStrategy-Struktur legen Sie die Zeitspanne zwischen den Benachrichtigungen und dem Zeitraum für das automatische Beenden von Vorfällen fest. Messwertbasierte Benachrichtigungsrichtlinien enthalten keine Zeit zwischen Benachrichtigungen.

In diesem Abschnitt wird beschrieben, wie Sie eine logbasierte Benachrichtigungsrichtlinie erstellen. Diese Richtlinien unterscheiden sich von messwertbasierten Benachrichtigungsrichtlinien beim Typ der verwendeten Bedingung. Für logbasierte Benachrichtigungen ist der Bedingungstyp LogMatch. Wenn Sie die Monitoring API zum Verwalten von Benachrichtigungsrichtlinien verwenden, gibt es keine Unterschiede beim Auflisten, Bearbeiten oder Löschen von Messwert- und logbasierten Richtlinien. Unter Benachrichtigungsrichtlinien nach API verwalten wird beschrieben, wie Sie Benachrichtigungsrichtlinien mithilfe der Monitoring API erstellen, auflisten, bearbeiten und löschen.

Benachrichtigungsrichtlinie entwerfen

Im Abschnitt Logbasierte Benachrichtigungen mit dem Log-Explorer erstellen wird eine Möglichkeit zum Erstellen einer logbasierten Benachrichtigung beschrieben. In diesem Abschnitt wird beschrieben, wie Sie eine logbasierte Benachrichtigung erstellen, die Sie benachrichtigt, wenn ein syslog-Logeintrag die Wichtigkeitsstufe NOTICE und eine ungültige IPv4-Adresse im Feld jsonPayload.result hat.

Zum Erstellen derselben logbasierten Benachrichtigung mithilfe der Monitoring API erstellen Sie ein AlertPolicy-Objekt, das die folgende JSON-Struktur aussieht:

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

Dieser JSON-Code gibt die gleichen Informationen an, die Sie auch beim Erstellen einer logbasierten Benachrichtigung im Log-Explorer angeben. In den folgenden Abschnitten wird der Inhalt dieser AlertPolicy-Struktur den Schritten zugeordnet, die Sie ausführen, wenn Sie mit dem Log-Explorer eine logbasierte Benachrichtigung erstellen. Der Wert des Felds conditionMatchedLog ist eine LogMatch-Struktur.

Namen und Beschreibung angeben

Eine Benachrichtigungsrichtlinie hat einen Anzeigenamen und eine zugehörige Dokumentation, die mit Benachrichtigungen bereitgestellt wird, um Empfängern zu helfen. Im Log-Explorer heißen diese Felder Benachrichtigungsname und Benachrichtigungsbeschreibung. Sie stellen diese Werte in einer AlertPolicy-Struktur so dar:

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

In diesem Beispiel enthält der Wert für displayName „(API)“, sodass Sie in der Liste der Richtlinien in der Google Cloud Console zwischen den beiden Beispielrichtlinien unterscheiden können. Auf der Monitoring-Seite Richtlinien werden Richtlinien nach angezeigtem Namen aufgelistet und es wird angegeben, ob die Richtlinie auf Messwerten oder Logs basiert. Weitere Informationen finden Sie unter Logbasierte Benachrichtigungen in Monitoring verwalten.

Das Feld documentation enthält im Unterfeld content die Beschreibung, die Sie bei der Verwendung von Log-Explorer angeben können. Das zweite Unterfeld mimeType ist erforderlich, wenn du einen Wert für das Feld documentation angibst. Der einzige gültige Wert ist "text/markdown".

Logs auswählen, für die Sie eine Benachrichtigung erhalten möchten

Eine logbasierte Benachrichtigungsrichtlinie hat eine einzelne Bedingung. Im Log-Explorer geben Sie die Bedingung an, wenn Sie eine Abfrage im Feld Logeinträge für gewünschte Benachrichtigungen definieren angeben. Sie stellen diese Werte in einer AlertPolicy-Struktur so dar:

{ ...
  "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",
  ...
}

Im Feld conditions wird eine Liste von Condition-Strukturen verwendet, wobei eine logbasierte Benachrichtigungsrichtlinie nur eine Bedingung enthalten darf. Jeder Condition hat einen Anzeigenamen und eine Beschreibung der Bedingung.

  • Der Wert des Felds displayName ist eine kurze Beschreibung der Bedingung. Wenn Sie den Log-Explorer verwenden, um logbasierte Benachrichtigungen zu erstellen, lautet der angezeigte Name immer "Logübereinstimmungsbedingung". Wenn Sie die Monitoring API verwenden, können Sie einen genaueren Anzeigenamen angeben. Ein Wert ist erforderlich.

  • Der Wert des Felds conditionMatchedLog ist eine LogMatch-Struktur und der Wert des Felds filter ist die Abfrage, die Sie im Log-Explorer angeben. Da diese Abfrage als Wert eines JSON-Felds bereitgestellt wird, wird die gesamte Abfrage in Anführungszeichen gesetzt. Anführungszeichen in der Abfrage selbst müssen mit dem umgekehrten Schrägstrich \ maskiert werden.

  • Die LogMatch-Struktur enthält auch ein optionales labelExtractors-Feld. Mit Labelextraktoren können Sie benutzerdefinierte Labels aus Ihren Logeinträgen erstellen und dann in Ihren Benachrichtigungen auf diese Labels verweisen.

    Um beispielsweise den Wert des Labels labels."compute.googleapis.com/resource_id" aus dem Logeintrag in ein Label namens vm_identifier zu extrahieren, könnte die vorherige Bedingung so aussehen:

    "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\")"
          }
        },
      }
    ],
    

    Verwenden Sie die Funktion EXTRACT, um den gesamten Wert abzugleichen, oder REGEXP_EXTRACT, um Teilstrings basierend auf regulären Ausdrücken abzugleichen. Dies sind die gleichen Funktionen, die für die Labelextraktion in logbasierten Messwerten verwendet werden. Weitere Informationen finden Sie unter Label erstellen.

    Sie können diese extrahierten Labels in der Benachrichtigungsdokumentation verwenden, damit sie in Benachrichtigungen gemeldet werden. Im Feld documentation Ihrer Benachrichtigungsrichtlinie verweisen Sie mit einer Variablen im Format ${log.extracted_label.KEY} auf die extrahierten Labels. Dabei ist KEY der Name, den Sie dem extrahierten Label gegeben haben.

    Das folgende Beispiel zeigt, wie auf den Schlüssel für das extrahierte Label vm_identifier verwiesen wird, damit der Wert des Loglabels labels."compute.googleapis.com/resource_id" in Benachrichtigungen enthalten ist:

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

Der Wert für das Feld combiner gibt an, wie die Ergebnisse mehrerer Bedingungen in messwertbasierten Benachrichtigungsrichtlinien kombiniert werden sollen. Sie können nur eine Bedingung in logbasierten Benachrichtigungen verwenden und müssen das Feld combiner mit dem Wert "OR" angeben. Sie können keine logbasierten Benachrichtigungen mit mehreren Bedingungen erstellen.

Werte für Benachrichtigungen und automatisches Schließen festlegen

Eine Benachrichtigungsrichtlinie für eine logbasierte Benachrichtigung gibt die Mindestzeit zwischen Benachrichtigungen an. Im Log-Explorer wählen Sie im Menü Zeit zwischen Benachrichtigungen einen Wert aus. Um diesen Wert in einer AlertPolicy-Struktur darzustellen, geben Sie für das Feld period einer NotificationRateLimit-Struktur einen Wert in Sekunden an, der in eine AlertStrategy-Struktur eingebettet ist.

Ebenso enthält die Benachrichtigungsrichtlinie den Zeitraum für das automatische Schließen von Vorfällen. Der Standardwert ist 7 Tage. Im Log-Explorer können Sie im Menü Dauer der automatischen Schließung von Vorfällen einen anderen Wert auswählen. Die Option entspricht dem Feld autoclose in der API-Struktur AlertStrategy. Wenn Sie dieses Feld verwenden, geben Sie den Wert in Sekunden an. Der Mindestwert beträgt 1.800 Sekunden oder 30 Minuten.

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

Der Wert für das Feld period in diesem Beispiel (300s) entspricht 5 Minuten. Der Wert für autoclose (604800s) entspricht 7 Tagen.

Angeben, wer benachrichtigt werden soll

Eine Benachrichtigungsrichtlinie kann eine Liste mit Benachrichtigungskanälen enthalten. Im Log-Explorer wählen Sie Kanäle aus einem Menü aus. Sie stellen diese Werte in einer AlertPolicy-Struktur dar, indem Sie eine Liste mit einem oder mehreren Ressourcennamen für konfigurierte NotificationChannel-Objekte angeben:

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

Wenn Sie einen Benachrichtigungskanal erstellen, wird ihm ein Ressourcenname zugewiesen. Informationen zum Abrufen der Liste der verfügbaren Benachrichtigungskanäle, einschließlich ihrer Ressourcennamen, finden Sie in der Monitoring-Dokumentation unter Kanäle abrufen. Du kannst die Kanal-IDs nicht über die Google Cloud Console abrufen.

Benachrichtigungsrichtlinie an die Monitoring API senden

Zum Erstellen einer Benachrichtigungsrichtlinie mit der Monitoring API erstellen Sie ein AlertPolicy-Objekt und senden es an die Methode alertPolicies.create. Sie können den alertPolicies.create über die Google Cloud CLI aufrufen und die Monitoring API direkt aufrufen.

Sie können logbasierte Benachrichtigungen auch mithilfe der Clientbibliotheken für C#, Go, Java, Python und Ruby erstellen. Sie können eventuell auch andere Clientbibliotheken verwenden. Die Bibliothek für Ihre Sprache muss den Bedingungstyp LogMatch enthalten.

So erstellen Sie eine Benachrichtigungsrichtlinie über die gcloud CLI:

  1. Fügen Sie die JSON-Darstellung Ihrer Benachrichtigungsrichtlinie in eine Textdatei ein, z. B. in eine Datei namens alert-invalid-ip.json.

  2. Übergeben Sie diese JSON-Datei mit dem folgenden Befehl an die gcloud CLI:

    gcloud alpha monitoring policies create --policy-from-file="alert-invalid-ip.json"
    
  3. Bei Erfolg gibt dieser Befehl den Ressourcennamen der neuen Richtlinie zurück. Beispiel:

    Created alert policy [projects/PROJECT_ID/alertPolicies/POLICY_ID].
    

Zum Erstellen einer Benachrichtigungsrichtlinie durch direktes Aufrufen von alertPolicies.create können Sie das APIs Explorer-Tool so verwenden:

  1. Rufen Sie die Referenzseite alertPolicies.create auf.

  2. Führen Sie im Bereich API testen folgende Schritte aus:

    1. Geben Sie im Feld name den folgenden Wert ein:

      projects/PROJECT_ID
      
    2. Kopieren Sie die JSON-Darstellung der Benachrichtigungsrichtlinie und ersetzen Sie den Inhalt des Felds Anfragetext in APIs Explorer durch die kopierte Benachrichtigungsrichtlinie.

    3. Klicken Sie auf Ausführen.

      Wenn der Aufruf alertPolicies.create erfolgreich ist, erhalten Sie einen HTTP 200-Antwortcode und einen leeren Antworttext: {}. Weitere Informationen zu APIs Explorer finden Sie in der Monitoring-Dokumentation unter APIs Explorer verwenden.

Weitere Informationen zum Erstellen von Benachrichtigungsrichtlinien mithilfe der Monitoring API finden Sie unter Richtlinien erstellen. In den Beispielen in diesem Dokument werden Bedingungstypen für messwertbasierte Benachrichtigungsrichtlinien verwendet, das Prinzip ist jedoch dasselbe.

Benachrichtigungsrichtlinie testen

Zum Testen der neuen Benachrichtigungsrichtlinie können Sie das gleiche Verfahren verwenden, das unter Logbasierte Beispielbenachrichtigung testen beschrieben wird.

Beispiel: Benachrichtigung erstellen, wenn ein Logeintrag einen Textstring enthält

In diesem Beispiel wird die Google Cloud Console zum Erstellen einer Benachrichtigungsrichtlinie, der Log-Explorer zum Anzeigen von Logeinträgen und die Google Cloud CLI zum Schreiben eines Logeintrags verwendet:

  1. Wählen Sie im Navigationsbereich der Google Cloud Console Logging und anschließend Log-Explorer aus:

    Zum Log-Explorer

  2. Geben Sie im Bereich Query (Abfrage) die folgende Abfrage ein, nachdem Sie den Wert von PROJECT_ID aktualisiert haben:

    logName="projects/PROJECT_ID/logs/test-log"
    textPayload:"Oops"
    

    Mit der Abfrage wird das Log mit dem Namen test-log nach Logeinträgen durchsucht, deren Feld textPayload den String „Hoppla“ enthält.

  3. Klicken Sie auf Benachrichtigung erstellen und füllen Sie das Dialogfeld aus. Sie müssen einen Namen für die Richtlinie eingeben, z. B. Alert on Oops. Die Abfrage, die Sie im vorherigen Schritt eingegeben haben, wird automatisch in die Benachrichtigungsrichtlinie aufgenommen.

  4. Öffnen Sie Cloud Shell und führen Sie den folgenden Befehl aus, um die Benachrichtigungsrichtlinie zu testen:

    gcloud logging write test-log --severity=ERROR --payload-type=text 'This log entry contains Oops'
    

    Mit dem vorherigen Befehl wird ein Eintrag in das Log mit dem Namen test-log geschrieben. Der Eintrag hat die Wichtigkeitsstufe ERROR und enthält das Feld textPayload.

  5. Klicken Sie im Log-Explorer auf Abfrage ausführen.

    Nachdem die Anzeige aktualisiert wurde, können Sie die Details des Logeintrags anzeigen, den Sie im vorherigen Schritt geschrieben haben.

  6. Wählen Sie im Navigationsbereich Monitoring und dann Benachrichtigungen aus, um die Benachrichtigung anzusehen. Im Bereich Vorfälle werden der Vorfall und Details zur Benachrichtigungsrichtlinie angezeigt.

    Wenn Sie beim Öffnen der Seite Benachrichtigungen keinen Vorfall sehen, warten Sie einige Minuten und aktualisieren Sie dann die Seite.

Wenn Sie den Befehl der Google Cloud CLI sofort wiederholen, wird kein weiterer Vorfall angezeigt und Sie erhalten keine weitere Benachrichtigung. In den Einstellungen der Benachrichtigungsrichtlinie ist der Mindestzeitraum zwischen Vorfällen angegeben. Sie können diese Einstellungen aufrufen und ändern, indem Sie die Richtlinie bearbeiten.