Configurer des alertes basées sur les journaux

Vous pouvez utiliser les alertes basées sur les journaux pour vous avertir lorsqu'un message spécifique apparaît dans vos journaux inclus. Par exemple, si vous souhaitez savoir quand un journal d'audit enregistre un message d'accès aux données particulier, vous pouvez créer une alerte basée sur les journaux qui correspond au message et vous avertit lorsqu'il apparaît. Ce document explique comment effectuer les opérations suivantes à l'aide de la console Google Cloud et de l'API Cloud Monitoring:

  • Créer et tester une alerte basée sur les journaux.
  • Modifier une alerte basée sur les journaux.
  • Supprimer une alerte basée sur les journaux.

Avant de commencer

Consultez la page Comparaison des alertes afin de déterminer si les alertes basées sur les journaux sont adaptées aux données de vos journaux. Exemple :

  • Les alertes basées sur les journaux ne fonctionnent pas avec les journaux exclus.

  • Vous ne pouvez pas utiliser les alertes basées sur les journaux pour obtenir des décomptes à partir de vos journaux. Pour le calcul des décomptes, vous devez utiliser les métriques basées sur les journaux.

Pour créer et gérer des alertes basées sur les journaux, votre rôle Identity and Access Management doit inclure les autorisations décrites dans la section Autorisations pour les alertes basées sur les journaux.

Créer une alerte basée sur les journaux à l'aide de l'explorateur de journaux

Vous pouvez créer des alertes basées sur les journaux à partir de la page Explorateur de journaux de la console Google Cloud, ou en utilisant l'API Monitoring. Cette section explique comment créer des alertes basées sur les journaux à l'aide de l'explorateur de journaux. Pour créer des alertes basées sur les journaux à l'aide de l'API Monitoring, consultez la section Créer une alerte basée sur les journaux à l'aide de l'API Monitoring.

L'interface de l'explorateur de journaux permettant de créer et de modifier des alertes basées sur les journaux vous guide tout au long des étapes suivantes :

  • Saisissez un nom et une description pour l'alerte.
  • Choisissez les journaux pour lesquels vous souhaitez recevoir une notification.
  • Définissez le délai entre les notifications.
  • Définissez l'heure de fermeture automatique des incidents.
  • Indiquez les personnes à avertir.

Par exemple, supposons que vous disposiez d'une application qui écrit une entrée de journal syslog avec une gravité définie sur NOTICE lorsque l'application modifie une adresse réseau. Les entrées de journal des modifications d'adresse réseau incluent une charge utile JSON semblable à celle-ci :

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

Vous souhaitez créer une alerte basée sur les journaux qui vous avertit lorsqu'une adresse IPv4 non valide apparaît dans le champ jsonPayload.result des entrées de journal de syslog avec une gravité définie sur NOTICE.

Pour créer l'alerte basée sur les journaux, procédez comme suit :

  1. Dans le panneau de navigation de la console Google Cloud, sélectionnez Logging, puis Explorateur de journaux :

    Accéder à l'explorateur de journaux

  2. Utilisez le volet Requête pour créer une requête correspondant au message que vous souhaitez utiliser dans votre alerte basée sur les journaux.

    Par exemple, pour rechercher dans le journal syslog des entrées de journal dont le niveau de gravité est NOTICE et qui possèdent des adresses IP non valides, vous pouvez utiliser la requête suivante :

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

    Utilisez Exécuter la requête dans le volet Résultats de requête pour valider la requête.

  3. Dans l'en-tête du volet Résultats de la requête, cliquez sur  Créer une alerte. Lorsque votre fenêtre est étroite, l'option Créer une alerte peut s'afficher dans le menu Actions.

  4. Dans le volet Détails de l'alerte, attribuez un nom et une description à l'alerte :

    1. Saisissez un nom pour l'alerte dans le champ Nom de la règle d'alerte. Par exemple: "Adresse réseau: valeur IPv4 non valide".

    2. Sélectionnez une option dans le menu Niveau de gravité de la règle. Les incidents et les notifications affichent le niveau de gravité.

    3. Saisissez une description pour cette alerte. Vous pouvez également inclure des informations susceptibles d'aider le destinataire d'une notification à diagnostiquer le problème. La chaîne suivante résume le motif de l'alerte:

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

      Pour obtenir des informations sur la mise en forme et la personnalisation du contenu de ce champ, consultez la section Utiliser Markdown et les variables dans les modèles de documentation.

  5. Pour passer à l'étape suivante, cliquez sur Suivant.

  6. Dans le volet Sélectionner les journaux à inclure dans l'alerte, vérifiez la requête et les résultats en cliquant sur Prévisualiser les journaux.

    Nous vous recommandons de créer la requête dans le volet Requête de l'explorateur de journaux. La requête que vous avez créée dans le volet Requête s'affiche également dans ce volet ; par exemple :

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

    Si nécessaire, vous pouvez modifier la requête dans ce volet. Si vous modifiez la requête, vérifiez les résultats en cliquant sur Prévisualiser les journaux.

  7. Cliquez sur Suivant.

  8. Sélectionnez le délai minimal entre les notifications. Cette valeur vous permet de contrôler le nombre de notifications que vous recevez de cette alerte si elle est déclenchée plusieurs fois. Pour cet exemple, sélectionnez l'option 5 min.

  9. (Facultatif) Sélectionnez la durée de fermeture automatique de l'incident. Par défaut, la durée de fermeture automatique de l'incident est définie sur sept jours.

  10. Cliquez sur Suivant.

  11. Sélectionnez un ou plusieurs canaux de notification pour votre alerte. Pour cet exemple, sélectionnez un canal de notification par e-mail.

    Si vous avez déjà configuré un canal de notification par e-mail, vous pouvez le sélectionner dans la liste. Si ce n'est pas le cas, cliquez sur Gérer les canaux de notification et ajoutez un canal de notification par e-mail. Pour plus d'informations sur la création de canaux de notification, consultez la page Gérer les canaux de notification.

  12. Cliquez sur Enregistrer.

Votre alerte basée sur les journaux est maintenant prête à être testée.

Tester l'exemple d'alerte basée sur les journaux

Pour tester l'alerte que vous avez créée, vous pouvez écrire manuellement une entrée de journal correspondant à la requête. Pour écrire l'entrée de journal, procédez comme suit:

  1. Configurez l'entrée de journal suivante en remplaçant la variable PROJECT_ID par l'ID de votre projet:

    {
      "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. Accédez à la page de référence logEntries.write ou cliquez sur le bouton suivant :

    Accéder à logEntries.write

  3. Copiez l'entrée de journal que vous avez configurée précédemment.

  4. Dans le volet Essayer cette API, procédez comme suit :

    1. Remplacez le contenu du champ Corps de la requête dans APIs Explorer par l'entrée de journal que vous avez copiée à l'étape précédente.

    2. Cliquez sur Exécuter. Si vous y êtes invité, suivez la procédure d'authentification.

      Si l'appel logEntries.write aboutit, vous obtenez un code de réponse HTTP 200 et un corps de réponse vide, {}. Pour en savoir plus sur l'explorateur d'API, consultez la page Utiliser l'explorateur d'API dans la documentation de Monitoring. L'explorateur d'API fonctionne de la même manière avec l'API Logging.

L'entrée de journal correspond au filtre spécifié pour l'alerte comme suit :

  • La valeur logName spécifie le journal syslog dans votre projet Google Cloud.
  • La valeur severity de cette entrée de journal est NOTICE.
  • La valeur jsonPayload.result n'est pas une adresse IPv4 valide.

Une fois l'entrée de journal écrite, la séquence suivante se produit :

  • La nouvelle entrée de journal apparaît dans l'explorateur de journaux et déclenche l'alerte.
  • Un incident est ouvert dans Cloud Monitoring.
  • Vous recevez une notification pour l'incident. Si vous avez configuré un canal de notification par e-mail, la notification se présente comme suit:

    L'exemple d'alerte basé sur les journaux génère une notification par e-mail.

Vous pouvez cliquer sur Afficher l'incident dans l'e-mail pour afficher l'incident dans Cloud Monitoring. Pour en savoir plus sur les incidents, consultez la page Gérer les incidents pour les alertes basées sur les journaux.

Autres scénarios : Alertes sur les journaux d'audit

L'exemple présenté dans la section Créer une alerte basée sur les journaux est artificiel. En règle générale, vous ne créez pas d'alerte, puis vous écrivez manuellement des entrées de journal pour la déclencher. Les entrées de journal sont généralement écrites par des applications ou d'autres services. Toutefois, la source des entrées de journal n'a pas d'importance. Pour les alertes basées sur les journaux, ce qui importe est la requête que vous utilisez pour sélectionner les entrées de journal.

Les sections suivantes décrivent des scénarios réalistes pour les alertes basées sur les journaux et sur le contenu des journaux d'audit. Chaque scénario montre comment créer une requête qui isole les entrées de journal d'audit souhaitées. Sinon, la procédure de création d'une alerte basée sur les journaux est identique à celle décrite dans la section Créer une alerte basée sur les journaux.

Alertes en cas d'accès humain aux secrets

Supposons que votre projet stocke des secrets dans Secret Manager, et que certains de ces secrets ne sont destinés qu'aux comptes de service. Sauf dans des circonstances inhabituelles, les utilisateurs humains n'accèdent jamais à ces secrets.

Si vous avez activé les journaux d'audit pour Secret Manager, chaque tentative réussie d'accès à un secret crée une entrée de journal d'audit. Chaque entrée inclut le nom du secret et l'identité de l'appelant.

Vous pouvez créer une alerte basée sur les journaux qui vous avertit lorsqu'un utilisateur humain accède à un secret.

Vous trouverez ci-dessous un extrait d'une entrée de journal d'audit écrite par Secret Manager. L'extrait montre les champs utiles pour créer la requête d'une alerte basée sur les journaux :

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

Les sous-champs protoPayload suivants présentent un intérêt particulier:

  • @type : indique que cette entrée de journal est une entrée de journal d'audit.
  • serviceName : enregistre le service qui a écrit l'entrée de journal d'audit. Utilisez ce champ pour identifier les entrées écrites par Secret Manager.
  • methodName : identifie la méthode pour laquelle cette entrée de journal d'audit a été écrite. Utilisez ce champ pour identifier l'action qui a entraîné la création de l'entrée de journal. Dans cet exemple, il s'agit de la méthode AccessSecretVersion.
  • authenticationInfo.principalEmail : enregistre le compte qui a appelé la méthode dans le champ methodName. La valeur attendue pour ce champ est un compte de service, qui se termine par gserviceaccount.com.

Pour rechercher les entrées de journal d'un utilisateur humain, consultez les entrées de journal d'audit écrites par Secret Manager. Vous devez rechercher les entrées de journal dans lesquelles la méthode AccessSecretVersion a été appelée par un compte principal qui ne se termine pas par gserviceaccount.com. La requête suivante isole ces entrées de journal :

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

Pour créer une alerte basée sur les journaux pour l'accès des utilisateurs humains aux secrets, utilisez la requête suivante dans le volet Sélectionner les journaux à inclure dans l'alerte.

Alertes en cas d'événement de déchiffrement

L'analyse de l'exemple précédent peut être adaptée à d'autres services. Par exemple, si vous utilisez Cloud Key Management Service pour chiffrer et déchiffrer des données sensibles, vous pouvez utiliser les journaux d'audit générés par Cloud KMS pour détecter à quel moment un utilisateur humain déchiffre une valeur.

Pour rechercher les entrées de journal correspondant à un déchiffrement effectué par un utilisateur humain, recherchez les entrées de journal d'audit écrites par Cloud KMS. Vous devez rechercher les entrées de journal dans lesquelles la méthode Decrypt a été appelée par un compte principal qui ne se termine pas par gserviceaccount.com (ce qui indique un compte de service). La requête suivante isole ces entrées de journal :

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

Pour créer une alerte basée sur les journaux en cas de déchiffrement effectué par un utilisateur humain, utilisez cette requête dans le volet Sélectionner les journaux à inclure dans l'alerte.

Gérer les alertes basées sur les journaux dans Monitoring

Vous pouvez afficher, modifier et supprimer des alertes basées sur les journaux à l'aide de la console Google Cloud pour Monitoring ou de l'API Monitoring. Ce document explique comment gérer les règles d'alerte à l'aide de la console Google Cloud. Pour en savoir plus sur l'utilisation de l'API Monitoring pour gérer les règles d'alerte, consultez la page Gérer des règles d'alerte à l'aide d'API.

Pour afficher la liste de toutes les règles d'alerte de votre projet Google Cloud, effectuez l'une des opérations suivantes :

  • Pour naviguer depuis Logging :

    1. Dans le panneau de navigation de la console Google Cloud, sélectionnez Logging, puis Explorateur de journaux :

      Accéder à l'explorateur de journaux

    2. Dans l'en-tête du volet Résultats de la requête, sélectionnez le menu Actions et sélectionnez Gérer les alertes.

  • Pour naviguer depuis Monitoring :

    1. Dans le panneau de navigation de la console Google Cloud, sélectionnez Monitoring, puis  Alertes :

      Accéder à l'interface des alertes

    2. Pour afficher toutes les règles et activer le filtrage, dans le volet Règles, cliquez sur Afficher toutes les règles.

Ces deux actions vous redirigent vers la page Règles de Monitoring, qui répertorie toutes les règles d'alerte de votre projet Google Cloud.

Pour restreindre les règles d'alerte répertoriées, ajoutez des filtres. Chaque filtre est composé d'un nom et d'une valeur. Par exemple, vous pouvez définir cette valeur comme étant une correspondance exacte ou partielle d'un nom de règle. Les correspondances ne sont pas sensibles à la casse. Si vous spécifiez plusieurs filtres, ils sont implicitement reliés par un AND logique, sauf si vous insérez un filtre OR. La capture d'écran suivante répertorie les règles d'alerte actuellement activées après le 1er janvier 2021 :

Liste des règles d'alerte actives qui ont été créées après le 1er janvier 2021.

Sur la page Policies (Règles), vous pouvez modifier, supprimer, copier, activer ou désactiver les règles d'alerte :

  • Pour modifier ou copier une règle, cliquez sur Plus d'options, puis sélectionnez l'option correspondante. La modification et la copie d'une règle sont similaires à la procédure décrite dans la section Créer une alerte basée sur les journaux. Vous pouvez modifier et, dans certains cas, supprimer les valeurs dans les champs. Lorsque vous avez terminé, cliquez sur Enregistrer.

    Vous pouvez également modifier une règle d'alerte basée sur les journaux en cliquant sur son nom dans la liste des règles.

  • Pour supprimer une règle, cliquez sur Plus d'options , puis sélectionnez Supprimer. Dans la boîte de dialogue de confirmation, sélectionnez Delete (Supprimer).

  • Pour activer ou désactiver la règle d'alerte, cliquez sur le bouton situé sous l'en-tête Enabled (Activé).

Créer une alerte basée sur les journaux à l'aide de l'API Monitoring

Vous pouvez créer des alertes basées sur les journaux à l'aide de l'API Monitoring. Vous fournissez à l'API Monitoring les mêmes informations que lorsque vous utilisez l'explorateur de journaux dans la console Google Cloud:

  • Un nom et une description pour l'alerte.
  • Les journaux pour lesquels vous souhaitez recevoir une notification.
  • Le délai entre les notifications.
  • le délai de fermeture automatique des incidents ;
  • Personne(s) à avertir.

Pour créer des règles d'alerte à l'aide de l'API Monitoring, créez un objet AlertPolicy et envoyez-le à la méthode alertPolicies.create.

Pour pouvoir utiliser l'API Monitoring, vous devez l'activer et être autorisé à l'utiliser. Pour en savoir plus, consultez la documentation suivante :

Structure des règles d'alerte

L'API Monitoring représente une règle d'alerte à l'aide de la structure AlertPolicy. La structure AlertPolicy comporte plusieurs structures intégrées qui incluent notamment une description de la condition qui déclenche l'alerte. Les règles d'alerte basées sur les journaux présentent les différences suivantes par rapport aux règles d'alerte basées sur les métriques :

  • Vous décrivez la condition à l'aide du type de condition LogMatch. Les règles d'alerte basées sur des métriques utilisent différents types de conditions.
  • Une règle d'alerte basée sur les journaux ne peut avoir qu'une seule condition.
  • Vous spécifiez le délai entre les notifications et la période de fermeture automatique de l'incident en incluant une structure AlertStrategy. Les règles d'alerte basées sur les métriques n'incluent pas de délai entre les notifications.

Cette section explique comment créer une règle d'alerte basée sur les journaux. Ces règles diffèrent des règles d'alerte basées sur les métriques dans le type de condition que vous utilisez. Pour les alertes basées sur les journaux, le type de condition est LogMatch. Lorsque vous utilisez l'API Monitoring pour gérer les règles d'alerte, il n'existe aucune différence dans la manière de répertorier, modifier ou supprimer les règles basées sur les journaux et les métriques. La page Gérer les règles d'alerte à l'aide de l'API explique comment créer, répertorier, modifier et supprimer une règle d'alerte à l'aide de l'API Monitoring.

Concevoir la règle d'alerte

La section intitulée Créer une alerte basée sur les journaux à l'aide de l'explorateur de journaux décrit une façon de créer une alerte basée sur les journaux. Cette section explique comment créer une alerte basée sur les journaux qui vous avertit lorsqu'une entrée de journal syslog présente un niveau de gravité NOTICE et une adresse IPv4 non valide dans le champ jsonPayload.result.

Pour créer la même alerte basée sur les journaux à l'aide de l'API Monitoring, créez un objet AlertPolicy qui ressemble à la structure JSON suivante :

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

Ce code JSON spécifie les mêmes informations que celles que vous spécifiez lorsque vous créez une alerte basée sur les journaux à l'aide de l'explorateur de journaux. Les sections suivantes font le parallèle entre le contenu de cette structure AlertPolicy et les étapes que vous suivez lorsque vous utilisez l'explorateur de journaux pour créer une alerte basée sur les journaux. La valeur du champ conditionMatchedLog est une structure LogMatch.

Saisir un nom et une description

Une règle d'alerte a un nom à afficher et une description associée qui est fournie avec les notifications pour en faciliter la compréhension. Dans l'explorateur de journaux, ces champs sont appelés Nom de l'alerte et Description de l'alerte. Vous représentez ces valeurs dans une structure AlertPolicy comme suit :

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

Dans cet exemple, la valeur de displayName inclut "(API)" pour que vous puissiez faire la distinction entre les deux exemples de règles lorsque vous consultez la liste des règles dans la console Google Cloud. La page Règles de Monitoring répertorie les règles avec leur nom à afficher et indique si elles sont basées sur des métriques ou des journaux. Pour en savoir plus, consultez la page Gérer les alertes basées sur les journaux dans Monitoring.

Le champ documentation inclut, dans le sous-champ content, la description que vous pouvez fournir lorsque vous utilisez l'explorateur de journaux. Le deuxième sous-champ, mimeType, est obligatoire lorsque vous spécifiez une valeur pour le champ documentation. La seule valeur valide est "text/markdown".

Choisissez les journaux pour lesquels vous souhaitez recevoir une notification.

Une règle d'alerte basée sur les journaux comporte une seule condition. Dans l'explorateur de journaux, vous spécifiez la condition lorsque vous fournissez une requête dans le champ Définir les entrées de journal pour lesquelles déclencher l'alerte. Vous représentez ces valeurs dans une structure AlertPolicy comme suit :

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

Le champ conditions accepte une liste de structures Condition, même si une règle d'alerte basée sur les journaux ne doit comporter qu'une seule condition. Chaque Condition possède un nom à afficher et une description de la condition.

  • La valeur du champ displayName est une brève description de la condition. Lorsque vous utilisez l'explorateur de journaux pour créer des alertes basées sur les journaux, le nom à afficher est toujours "Condition de correspondance des journaux". Lorsque vous utilisez l'API Monitoring, vous pouvez fournir un nom à afficher plus précis. Veuillez saisir une valeur.

  • La valeur du champ conditionMatchedLog est une structure LogMatch, tandis que la valeur du champ filter correspond à la requête que vous spécifiez dans l'explorateur de journaux. Étant donné que cette requête est fournie en tant que valeur d'un champ JSON, la requête entière apparaît entre guillemets, et tous les guillemets de la requête elle-même doivent être échappés avec le caractère \ (barre oblique inverse).

  • La structure LogMatch inclut également un champ labelExtractors facultatif. Vous pouvez utiliser des extracteurs d'étiquettes pour composer des étiquettes personnalisées à partir de vos entrées de journal, puis les référencer dans vos notifications.

    Par exemple, pour extraire la valeur de l'étiquette labels."compute.googleapis.com/resource_id" de votre entrée de journal dans une étiquette appelée vm_identifier, la condition précédente peut se présenter comme suit:

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

    Utilisez la fonction EXTRACT pour correspondre à la valeur entière ou utilisez REGEXP_EXTRACT pour faire correspondre des sous-chaînes en fonction d'expressions régulières. Il s'agit de la même fonction utilisée pour extraire des libellés dans les métriques basées sur les journaux. Pour en savoir plus, consultez la section Créer une étiquette.

    Vous pouvez utiliser ces libellés extraits dans la documentation de l'alerte afin qu'ils soient signalés dans les notifications. Dans le champ documentation de votre règle d'alerte, vous faites référence aux libellés extraits à l'aide d'une variable au format ${log.extracted_label.KEY}, où KEY est le nom que vous avez attribué à l'étiquette extraite.

    L'exemple suivant montre comment faire référence à la clé du libellé extrait vm_identifier afin que la valeur du libellé de journal labels."compute.googleapis.com/resource_id" soit incluse dans les notifications d'alerte:

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

La valeur du champ combiner indique comment combiner les résultats de plusieurs conditions dans des règles d'alerte basées sur des métriques. Vous ne pouvez utiliser qu'une seule condition dans les alertes basées sur les journaux, et vous devez spécifier le champ combiner avec la valeur "OR". Vous ne pouvez pas créer d'alertes basées sur les journaux avec plusieurs conditions.

Définir les valeurs de notification et de fermeture automatique

Une règle d'alerte pour une alerte basée sur les journaux spécifie le délai minimum entre les notifications. Dans l'explorateur de journaux, vous sélectionnez une valeur dans le menu Délai entre les notifications. Pour représenter cette valeur dans une structure AlertPolicy, spécifiez une valeur, en secondes, pour le champ period d'une structure NotificationRateLimit intégrée dans une structure AlertStrategy.

De même, la règle d'alerte spécifie la période de fermeture automatique des incidents. La valeur par défaut est de 7 jours. Dans l'explorateur de journaux, vous pouvez sélectionner une valeur différente dans le menu Délai de fermeture automatique de l'incident. Cette option correspond au champ autoclose dans la structure d'API AlertStrategy. Lorsque vous utilisez ce champ, indiquez la valeur en secondes. La valeur minimale est de 1 800 secondes ou 30 minutes.

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

Dans cet exemple, 300s, la valeur du champ period équivaut à cinq minutes. La valeur autoclose, 604800s, équivaut à sept jours.

Indiquer les personnes à avertir

Une règle d'alerte peut inclure une liste de canaux de notification. Dans l'explorateur de journaux, vous sélectionnez des canaux dans un menu. Vous représentez ces valeurs dans une structure AlertPolicy en fournissant une liste d'un ou de plusieurs noms de ressources pour les objets NotificationChannel configurés :

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

Lorsque vous créez un canal de notification, un nom de ressource lui est attribué. Pour en savoir plus sur la récupération de la liste des canaux de notification disponibles, y compris leurs noms de ressources, consultez la page Récupérer les canaux dans la documentation de Monitoring. Vous ne pouvez pas obtenir les ID des canaux à l'aide de la console Google Cloud.

Envoyer votre règle d'alerte à l'API Monitoring

Pour créer une règle d'alerte à l'aide de l'API Monitoring, créez un objet AlertPolicy et envoyez-le à la méthode alertPolicies.create. Vous pouvez appeler alertPolicies.create à l'aide de la Google Cloud CLI, en appelant directement l'API Monitoring.

Vous pouvez également créer des alertes basées sur les journaux à l'aide des bibliothèques clientes pour C#, Go, Java, Python et Ruby. Vous pouvez également utiliser d'autres bibliothèques clientes, mais la bibliothèque pour votre langage doit inclure le type de condition LogMatch.

Pour créer une règle d'alerte à l'aide de la gcloud CLI, procédez comme suit:

  1. Placez la représentation JSON de votre règle d'alerte dans un fichier texte ; par exemple, dans un fichier appelé alert-invalid-ip.json.

  2. Transmettez ce fichier JSON à la gcloud CLI à l'aide de la commande suivante:

    gcloud alpha monitoring policies create --policy-from-file="alert-invalid-ip.json"
    
  3. Si la commande réussit, elle renvoie le nom de ressource de la nouvelle règle ; par exemple :

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

Pour créer une règle d'alerte en appelant directement alertPolicies.create, vous pouvez utiliser l'outil APIs Explorer comme suit :

  1. Accédez à la page de référence sur alertPolicies.create.

  2. Dans le volet Essayer cette API, procédez comme suit :

    1. Dans le champ name, saisissez la valeur suivante :

      projects/PROJECT_ID
      
    2. Copiez la représentation JSON de votre règle d'alerte et remplacez le contenu du champ Corps de la requête dans l'explorateur d'API par la règle d'alerte copiée.

    3. Cliquez sur Exécuter.

      Si l'appel alertPolicies.create aboutit, vous obtenez un code de réponse HTTP 200 et un corps de réponse vide, {}. Pour en savoir plus sur l'explorateur d'API, consultez la page Utiliser l'explorateur d'API dans la documentation de Monitoring.

Pour en savoir plus sur la création de règles d'alerte à l'aide de l'API Monitoring, consultez la page Créer des règles. Les exemples de ce document utilisent des types de conditions pour les règles d'alerte basées sur les métriques, mais les principes sont les mêmes.

Tester la règle d'alerte

Pour tester votre nouvelle règle d'alerte, vous pouvez utiliser la même procédure que celle décrite dans la section Tester l'exemple d'alerte basée sur les journaux.

Exemple: Créer une alerte lorsqu'une entrée de journal contient une chaîne de texte

Cet exemple utilise la console Google Cloud pour créer une règle d'alerte, l'explorateur de journaux pour afficher les entrées de journal et la Google Cloud CLI pour écrire une entrée de journal:

  1. Dans le panneau de navigation de la console Google Cloud, sélectionnez Logging, puis Explorateur de journaux :

    Accéder à l'explorateur de journaux

  2. Dans le volet Requête, saisissez la requête suivante après avoir mis à jour la valeur de PROJECT_ID:

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

    La requête recherche dans le journal test-log les entrées de journal dont le champ textPayload contient la chaîne "Oops".

  3. Cliquez sur Créer une alerte et remplissez les champs de la boîte de dialogue. Vous devez saisir un nom pour la règle, par exemple Alert on Oops. La requête que vous avez saisie à l'étape précédente est automatiquement incluse dans la règle d'alerte.

  4. Pour tester la règle d'alerte, ouvrez Cloud Shell, puis exécutez la commande suivante:

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

    La commande précédente écrit une entrée dans le journal nommé test-log. L'entrée présente un niveau de gravité ERROR et inclut un champ textPayload.

  5. Dans l'explorateur de journaux, cliquez sur Exécuter la requête.

    Une fois l'affichage actualisé, vous pouvez consulter les détails de l'entrée de journal que vous avez écrite à l'étape précédente.

  6. Pour afficher l'alerte, dans le volet de navigation, sélectionnez Monitoring, puis Alertes. Le volet Incidents affiche l'incident et les détails de la règle d'alerte.

    Si vous ne voyez pas d'incident lorsque vous ouvrez la page Alertes, attendez quelques minutes, puis actualisez la page.

Si vous répétez immédiatement la commande Google Cloud CLI, vous ne verrez pas d'autre incident et vous ne recevrez pas d'autre notification. Les paramètres des règles d'alerte spécifient la période minimale entre les incidents. Vous pouvez afficher et modifier ces paramètres en modifiant la règle.