此页面由 Cloud Translation API 翻译。

配置基于日志的提醒

您可以使用基于日志的提醒，在包含的日志中出现特定消息时收到通知。例如，如果您想了解审核日志何时记录特定数据访问消息，则可以创建一个基于日志的提醒来匹配该消息并在该消息出现时通知您。本文档介绍了如何使用 Google Cloud 控制台和 Cloud Monitoring API 执行以下操作：

创建和测试基于日志的提醒。
修改基于日志的提醒。
删除基于日志的提醒。

准备工作

查看提醒比较，确定基于日志的提醒是否适合您的日志中的数据。例如：

基于日志的提醒不适用于已排除的日志。
您不能使用基于日志的提醒来获取日志计数。如需推算计数，您需要改为使用基于日志的指标。

如需创建和管理基于日志的提醒，您的 Identity and Access Management 角色必须包含基于日志的提醒的权限中所述的权限。

使用 Logs Explorer 创建基于日志的提醒

您可以通过 Google Cloud 控制台中的 Logs Explorer 页面或使用 Monitoring API 来创建基于日志的提醒。本部分介绍如何使用日志浏览器创建基于日志的提醒。如需使用 Monitoring API 创建基于日志的提醒，请参阅使用 Monitoring API 创建基于日志的提醒。

用于创建和修改基于日志的提醒的日志查看器界面将引导您完成以下步骤：

提供提醒的名称和说明。
选择您想要接收通知的日志。
设置通知之间的时间间隔。
设置自动关闭突发事件的时间。
指定要通知的人员。

例如，假设您有一个应用在更改网络地址时写入严重性为 NOTICE 的 syslog 日志条目。网络地址更改的日志条目包含如下所示的 JSON 载荷：

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

您希望创建一个基于日志的提醒，以便在 syslog（严重级别为 NOTICE）的日志条目的 jsonPayload.result 字段中出现无效 IPv4 地址时提醒您。

要创建基于日志的提醒，请执行以下操作：

在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择 Logs Explorer：
前往 Logs Explorer
使用查询窗格构建一个查询，该查询与要在基于日志的提醒中使用的消息匹配。

例如，要在 syslog 日志中查找严重级别为 NOTICE 且 JSON 载荷中包含无效 IP 地址的日志条目，您可以使用以下查询：
```
log_id("syslog")
severity = "NOTICE"
jsonPayload.result !~ "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.|$)){4}$"
```
在查询结果窗格中使用运行查询来验证查询。
在查询结果窗格的标题中，点击 创建提醒。当窗口缩小时，操作菜单上可能会显示创建提醒选项。
在提醒详情窗格中，为提醒指定名称和说明：
1. 在 Alert Policy Name 字段中输入提醒的名称。例如：“网络地址：IPv4 值无效”。
2. 从政策严重级别菜单中选择一个选项。突发事件和通知会显示严重级别。
3. 输入此提醒的说明。您也可以添加有助于通知接收人诊断问题的信息。以下字符串总结了发出提醒的原因：
```
Log-based alert in project ${project} detected an invalid IPv4 value.
```
  如需详细了解如何设置此字段格式并定制其内容，请参阅在文档模板中使用 Markdown 和变量。
要前进到下一步，请点击下一步。
在选择要包含在提醒中的日志窗格中，点击预览日志以检查查询和结果。

我们建议在日志浏览器查询窗格中构建查询。您在查询窗格中构建的查询也会显示在此窗格中，例如：
```
log_id("syslog")
severity = "NOTICE"
jsonPayload.result !~ "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.|$)){4}$"
```
如有必要，您可以在此窗格中修改查询。如果您修改了查询，请点击预览日志来检查结果。
点击下一步。
选择通知之间的最短时间间隔。如果此值被多次触发，您可以使用此值来控制从此提醒中收到的通知数量。对于此示例，请从选项中选择 5 分钟。
可选：选择突发事件自动关闭时长。默认情况下，突发事件自动关闭时长设置为 7 天。
点击下一步。
为提醒选择一个或多个通知渠道。在本示例中，请选择电子邮件通知渠道。

如果您已配置电子邮件通知渠道，则可以从列表中选择它。如未配置，请点击管理通知渠道并添加电子邮件渠道。如需了解如何创建通知渠道，请参阅管理通知渠道。
点击保存。

您现在可以测试基于日志的提醒了。

测试基于日志的示例提醒

如需测试您创建的提醒，则可以手动写入与查询匹配的日志条目。要写入日志条目，请执行以下操作：

通过将 PROJECT_ID 变量更改为您的项目 ID，配置以下日志条目：

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

转到 logEntries.write 参考页面，或点击以下按钮：

转到 logEntries.write
复制您之前配置的日志条目。
在试用此 API 窗格中，执行以下操作：
1. 将 API Explorer 中请求正文字段的内容替换为您在上一步中复制的日志条目。
2. 点击执行。如果出现提示，请按照身份验证流程操作。
  
  如果 logEntries.write 调用成功，您会收到 HTTP 200 响应代码和空响应正文 {}。如需详细了解 API Explorer，请参阅 Monitoring 文档中的使用 API Explorer；API Explorer 的工作方式与 Logging API 相同。

日志条目与为提醒指定的过滤条件匹配，指定方法如下：

logName 值用于指定 Google Cloud 项目中的 syslog 日志。
此日志条目的 severity 值为 NOTICE。
jsonPayload.result 值不是有效的 IPv4 地址。

写入日志条目后，会发生以下序列：

新日志条目会显示在日志浏览器中并触发提醒。
Cloud Monitoring 中会打开一个突发事件。
您会收到突发事件通知。如果您配置了电子邮件通知渠道，则通知类似于以下屏幕截图：

您可以点击电子邮件中的查看突发事件，查看 Cloud Monitoring 中的突发事件。如需详细了解突发事件，请参阅管理基于日志的提醒的突发事件。

其他场景：审核日志提醒

创建基于日志的提醒中的示例是人为的；您通常不会创建提醒，而是会手动写入日志条目以触发该提醒。日志条目通常由应用或其他服务写入。但日志条目的来源无关紧要。对于基于日志的提醒，重要的是您用于选择日志条目的查询。

以下部分介绍了基于审核日志内容的基于日志的提醒的实际场景。每个情景说明了如何创建隔离所需审核日志条目的查询。否则，创建基于日志的提醒的过程与创建基于日志的提醒所示的过程相同。

有关 secret 人工访问的提醒

假设您的项目将 Secret 存储在 Secret Manager 中，其中的部分 secret 仅供服务账号使用。除非出现异常情况，否则真人用户绝不会访问这些 Secret。

如果您启用了 Secret Manager 审核日志记录功能，每次成功访问 secret 都会创建审核日志条目。每个条目都包含 secret 的名称和调用者的身份。

您可以创建基于日志的提醒，在真人用户访问 Secret 时通知您。

下面显示了 Secret Manager 写入的审核日志条目摘录。以下摘录展示了为基于日志的提醒创建查询有用的字段：

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

以下 protoPayload 子字段尤其重要：

@type：表示此日志条目是审核日志条目。
serviceName：记录写入审核日志条目的服务。使用此字段标识由 Secret Manager 写入的条目。
methodName：标识写入此审核日志条目的方法。使用此字段标识导致此条目创建的操作。在此示例中，它是 AccessSecretVersion 方法。
authenticationInfo.principalEmail：在 methodName 字段中记录调用该方法的账号。此字段的预期值是服务账号，以 gserviceaccount.com 结尾。

如需查找真人用户访问的 secret 日志条目，请查找 Secret Manager 写入的审核日志条目。您希望查找其 AccessSecretVersion 方法由主账号（不以 gserviceaccount.com 结尾）调用的日志条目。以下查询会隔离这些日志条目：

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

如需为 Secret 人工访问创建基于日志的提醒，请在选择要包含在提醒中的日志窗格中使用此查询。

有关解密事件的提醒

上一示例中的分析可用于其他服务。例如，如果您使用 Cloud Key Management Service 来加密和解密敏感数据，则可以使用 Cloud KMS 生成的审核日志检测真人用户何时解密值。

如要查找真人用户解密的日志条目，请查找由 Cloud KMS 写入的审核日志条目。您希望查找其 Decrypt 方法由并非以 gserviceaccount.com （指示服务账号）结尾的主账号调用的日志条目。以下查询会隔离这些日志条目：

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

如需真人用户解密创建基于日志的提醒，请在选择要包含在提醒中的日志窗格中使用该查询。

在 Monitoring 中管理基于日志的提醒

您可以使用适用于 Monitoring 的 Google Cloud 控制台或使用 Monitoring API 查看、修改和删除基于日志的提醒。本文档介绍如何使用 Google Cloud 控制台管理提醒政策。如需了解如何使用 Monitoring API 管理提醒政策，请参阅使用 API 管理提醒政策。

如需查看 Google Cloud 项目中所有提醒政策的列表，请执行以下某项操作：

如要从 Logging 中导航，请执行以下操作：
1. 在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择 Logs Explorer：
  前往 Logs Explorer
2. 在查询结果窗格的标题中，选择操作菜单，然后选择管理提醒。
如要从 Monitoring 导航，请执行以下操作：
1. 在 Google Cloud 控制台的导航面板中，选择 Monitoring，然后选择提醒：
  进入提醒
2. 如需查看所有政策并启用过滤，请在 Policies 窗格中，点击查看所有政策。

这两项操作都会将您转到 Monitoring Policies 页面，其中列出了 Google Cloud 项目中的所有提醒政策。

要限制列出的提醒政策，请添加过滤条件。每个过滤条件都由名称和值组成。例如，您可以将该值设置为与政策名称完全匹配或部分匹配。匹配项不区分大小写。如果您指定了多个过滤条件，则除非您插入 OR 过滤条件，否则这些过滤条件会由逻辑 AND 隐式联接。以下屏幕截图列出了当前启用的提醒政策，这些提醒政策是在 2021 年 1 月 1 日之后创建的：

在 2021 年 1 月 1 日之后创建的已启用提醒政策的列表。

在政策页面中，您可以修改、删除、复制、启用或停用提醒政策：

要修改或复制政策，请点击更多选项，并选择所需选项。修改和复制政策类似于创建基于日志的提醒中所述的过程。您可以更改字段中的值，在某些情况下还可以删除这些值。完成后，点击保存。

您还可以通过在政策列表中点击其名称来修改基于日志的提醒政策。
要删除政策，请点击更多选项，然后选择删除。在确认对话框中，选择删除。
如要启用或停用提醒政策，请点击已启用标题下的切换按钮。

使用 Monitoring API 创建基于日志的提醒

您可以使用 Monitoring API 创建基于日志的提醒。向 Monitoring API 提供的信息应与在 Google Cloud 控制台中使用 Logs Explorer 时提供的信息相同：

提醒的名称和说明。
您要接收通知的日志。
通知之间的时间间隔。
自动关闭突发事件的时间。
选择通知对象。

如需使用 Monitoring API 创建提醒政策，请创建 AlertPolicy 对象并将其提交到 alertPolicies.create 方法。

您必须先启用 API 并拥有使用该 API 的授权，然后才能使用 Monitoring API。如需了解详情，请参阅以下文档：

提醒政策的结构

Monitoring API 使用 AlertPolicy 结构表示提醒政策。AlertPolicy 结构具有多个嵌入式结构，包括对触发提醒的条件说明。基于日志的提醒政策在以下方面与基于指标的提醒政策不同：

您可以使用 LogMatch 条件类型来描述条件。基于指标的提醒政策使用不同的条件类型。
基于日志的提醒政策只能有一个条件。
您可以通过添加 AlertStrategy 结构来指定通知与自动关闭突发事件期限之间的时间。基于指标的提醒政策不包含通知之间的时间间隔。

本部分介绍如何创建基于日志的提醒政策。这些政策在您使用的条件类型方面不同于基于指标的提醒政策。对于基于日志的提醒，条件类型为 LogMatch。当您使用 Monitoring API 管理提醒政策时，列出、修改或删除指标和基于日志的指标的方式没有区别。使用 API 管理提醒政策介绍如何使用 Monitoring API 创建、列出、修改和删除提醒政策。

设计提醒政策

标题为使用日志浏览器创建基于日志的提醒部分介绍了创建基于日志的提醒的一种方法。该部分介绍了如何创建基于日志的提醒，以便在 syslog 日志条目的严重级别为 NOTICE 且 jsonPayload.result 字段中的 IPv4 地址无效时向您发出通知。

如要使用 Monitoring API 创建相同的基于日志的提醒，请创建一个类似于以下 JSON 结构的 AlertPolicy 对象：

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

此 JSON 代码指定的信息与使用日志浏览器创建基于日志的提醒时指定的信息相同。以下部分将此 AlertPolicy 结构的内容映射到您在使用日志浏览器创建基于日志的提醒时遵循的步骤。conditionMatchedLog 字段的值为 LogMatch 结构。

提供名称和说明

提醒政策具有显示名和相关文档，该文档与通知一起提供以协助响应人员。在日志浏览器中，这些字段名称为提醒名称和提醒说明。这些值在 AlertPolicy 结构中的表示如下所示：

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

在本例中，displayName 的值包含“(API)”，以便您在 Google Cloud 控制台中查看政策列表时区分这两个示例政策。Monitoring 政策页面按显示名列出政策，并指明政策是基于指标还是日志。如需了解详情，请参阅管理 Monitoring 中基于日志的提醒。

documentation 字段包含 content 子字段中使用日志浏览器时可能提供的说明。当您指定了 documentation 字段的值，则必须输入第二个子字段 mimeType。唯一的有效值为 "text/markdown"。

选择您想要接收通知的日志

基于日志的提醒政策只有一个条件。在日志浏览器中，您可以在定义日志条目以提醒字段中指定提供查询时的条件。这些值在 AlertPolicy 结构中的表示如下所示：

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

conditions 字段采用 Condition 结构列表，但基于日志的提醒政策必须只有一个条件。每个 Condition 都有一个显示名和条件说明。

displayName 字段的值是对条件的简要说明。使用日志浏览器创建基于日志的提醒时，显示名始终为“日志匹配条件”。使用 Monitoring API 时，您可以提供更精确的显示名。必须提供值。
conditionMatchedLog 字段的值是一个 LogMatch 结构，而 filter 字段的值是您在日志浏览器中指定的查询。由于此查询是作为 JSON 字段的值提供的，因此整个查询会出现在英文引号中，并且查询本身中的任何英文引号都必须使用 \（反斜杠）字符进行转义。
LogMatch 结构还包含一个可选的 labelExtractors 字段。您可以使用标签提取器根据日志条目编写自定义标签，然后在通知中引用这些标签。

例如，如需将日志条目中的标签 labels."compute.googleapis.com/resource_id" 的值提取到名为 vm_identifier 的标签中，上述条件可能如下所示：
```
"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\")"
      }
    },
  }
],
```
使用 EXTRACT 函数匹配整个值，或使用 REGEXP_EXTRACT 根据正则表达式匹配子字符串。这些函数与基于日志的指标中的标签提取功能相同；如需了解详情，请参阅创建标签。

您可以在提醒文档中使用这些提取的标签，以便在通知中报告它们。在提醒政策的 documentation 字段中，您可以使用 ${log.extracted_label.KEY} 形式的变量来引用提取的标签，其中 KEY 是您为提取的标签指定的名称。

以下示例展示了如何引用已提取标签 vm_identifier 的键，以便在提醒通知中包含日志标签 labels."compute.googleapis.com/resource_id" 的值：
```
"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"
},
```

combiner 字段的值指定如何在基于指标的提醒政策中组合多个条件的结果。您只能在基于日志的提醒中使用一个条件，并且必须使用值 "OR" 指定 combiner。您无法创建具有多个条件的基于日志的提醒。

设置通知值和自动关闭值

基于日志的提醒政策指定通知之间的最短时间间隔。在日志浏览器中，您可以从通知时间间隔菜单中选择一个值。您可通过为嵌入到 AlertStrategy 结构的 NotificationRateLimit 结构的 period 字段指定值（以秒为单位），以 AlertPolicy 结构表示该值。

同样，提醒政策包括自动关闭突发事件的时长。默认值为 7 天。在日志浏览器中，您可以从突发事件自动关闭时长菜单中选择其他值。该选项对应于 AlertStrategy API 结构中的 autoclose 字段。使用此字段时，请指定该值（以秒为单位）。最小值为 1800 秒，或 30 分钟。

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

此示例中 period 字段的值 (300s) 等于 5 分钟。autoclose 值 604800s 等于 7 天。

指定要通知的联系人

提醒政策可包含通知渠道列表。在日志浏览器中，从菜单中选择渠道。您可以通过为已配置的 NotificationChannel 对象提供一个或多个资源名称列表，以 AlertPolicy 结构表示这些值：

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

当您创建通知渠道时，系统会为其分配一个资源名称。如需了解如何检索可用通知渠道的列表（包括其资源名称），请参阅 Monitoring 文档中的检索渠道。您无法使用 Google Cloud 控制台获取渠道 ID。

将提醒政策发送到 Monitoring API

如需使用 Monitoring API 创建提醒政策，请创建 AlertPolicy 对象并将其提交到 alertPolicies.create 方法。您可以使用 Google Cloud CLI（直接调用 Monitoring API）来调用 alertPolicies.create。

您还可以使用 C#、Go、Java、Python 和 Ruby 版客户端库创建基于日志的提醒。您或许还可以使用其他客户端库；您的语言库必须包含 LogMatch 条件类型。

如需使用 gcloud CLI 创建提醒政策，请执行以下操作：

将提醒政策的 JSON 表示法放入文本文件中，例如，放在名为 alert-invalid-ip.json 的文件中。

使用以下命令将此 JSON 文件传递给 gcloud CLI：

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

如果成功，则该命令将返回新政策的资源名称，例如：
```
Created alert policy [projects/PROJECT_ID/alertPolicies/POLICY_ID].
```

如要通过直接调用 alertPolicies.create 创建提醒政策，您可以使用 API Explorer 工具，如下所示：

转到 alertPolicies.create 参考页面。
在试用此 API 窗格中，执行以下操作：
1. 在 name 字段中，输入以下值：
```
projects/PROJECT_ID
```
2. 复制提醒政策的 JSON 表示法，并将 API Explorer 中请求正文字段的内容替换为复制的提醒政策。
3. 点击执行。
  
  如果 alertPolicies.create 调用成功，您会收到 HTTP 200 响应代码和空响应正文 {}。如需详细了解 API Explorer，请参阅 Monitoring 文档中的使用 API Explorer。

如需详细了解如何使用 Monitoring API 创建提醒政策，请参阅创建政策。该文档中的示例将各种条件类型用于基于指标的提醒政策，但原则相同。

测试提醒政策

如需测试新的提醒政策，您可以按照测试基于日志的示例提醒中所述的步骤进行操作。

示例：在日志条目包含文本字符串时创建提醒

此示例使用 Google Cloud 控制台创建提醒政策，使用 Logs Explorer 查看日志条目，并使用 Google Cloud CLI 写入日志条目：

在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择 Logs Explorer：
前往 Logs Explorer
在查询窗格中，更新 PROJECT_ID 的值后输入以下查询：
```
logName="projects/PROJECT_ID/logs/test-log"
textPayload:"Oops"
```
该查询在名称为 test-log 的日志中搜索 textPayload 字段包含字符串“Oops”的日志条目。
点击创建提醒并完成对话框。您必须输入政策的名称，例如 Alert on Oops。您在上一步中输入的查询将自动包含在提醒政策中。
如需测试提醒政策，请打开 Cloud Shell，然后运行以下命令：
```
gcloud logging write test-log --severity=ERROR --payload-type=text 'This log entry contains Oops'
```
上一条命令会向日志中写入一个名为 test-log 的条目。该条目的严重级别为 ERROR，并且包含 textPayload 字段。
在日志浏览器中，点击运行查询。

刷新显示内容后，您可以查看在上一步中写入的日志条目的详细信息。
如需查看提醒，请在导航窗格中选择 Monitoring，然后选择提醒。Incidents 窗格会显示相应突发事件以及有关提醒政策的详细信息。

如果您在打开提醒页面时没有看到突发事件，请等待几分钟，然后刷新页面。

如果您立即重复执行 Google Cloud CLI 命令，则不会看到其他突发事件或收到其他通知。提醒政策设置指定了事件之间的最短时间段。您可以通过修改政策来查看和更改这些设置。