使用用户定义的文档为提醒添加注解

本页介绍如何配置提醒政策文档，以自定义通知的正文和主题行。文档字段支持纯文本、Markdown、变量和针对特定渠道的控件。

向通知中添加信息

您可以在创建提醒政策时指定相应内容，从而在通知中为提醒响应者提供修复措施步骤和有关突发事件的信息。例如，您可以配置提醒政策，在任何通知中包含指向内部 playbook 的链接。

如需查看示例实现，请参阅本页面的示例部分。

配置通知的主题行

您可以通过指定通知的主题行来管理通知并对其进行排序。主题行不得超过 255 个字符。 如果您未在文档中定义主题，则 Cloud Monitoring 会确定主题行。

使用 Cloud Monitoring API、Google Cloud CLI 或 Google Cloud 控制台时，您可以配置主题行。

如需查看示例实现，请参阅本页面的示例部分。

使用 Markdown

文档字段支持以下 Markdown 标记子集：

• 标题，以井号字符开头。
• 无序列表，以加号、减号或星号字符开头。
• 有序列表，以数字后跟英文句点开头。
• 斜体文本，由短语两边的单下划线或单星号表示。
• 粗体文本，由短语两边的双下划线或双星号表示。
• 链接，以 [link text](url) 语法表示。

如需详细了解此标记，请参阅任意 Markdown 参考文档，例如 Markdown 指南。

使用变量

如需自定义文档中的文本，您可以使用 ${varname} 形式的变量。当文档随通知一起发送时，字符串 ${varname} 会被替换为从相应 Google Cloud 资源提取的值，如下表所示。

变量	值
condition.name	条件的 REST 资源名称，例如 projects/foo/alertPolicies/1234/conditions/5678。
condition.display_name	条件的显示名称，例如 CPU usage increasing rapidly。
log.extracted_label.KEY	标签 KEY 的值，从日志条目中提取。仅适用于基于日志的提醒；如需了解详情，请参阅 使用 Monitoring API 创建基于日志的提醒。
metadata.system_label.KEY	系统提供的资源元数据标签 KEY 的值。^1
metadata.user_label.KEY	用户定义的资源元数据标签 KEY 的值。^1、3
metric.type	指标类型，如 compute.googleapis.com/instance/cpu/utilization。
metric.display_name	指标类型的显示名称，例如 CPU utilization。
metric.label.KEY	指标标签 KEY 的值。^1 要查找与指标类型关联的标签，请参阅指标列表。 如果变量 ${metric.label.KEY} 的值不是以数字、字母、正斜杠 (/) 或等号 (=) 开头，则 Monitoring 会省略通知的标签。 当您迁移 Prometheus 提醒规则时，Prometheus 提醒字段模板 {{$value}} 和 {{humanize $value}} 在提醒政策文档配置中显示为 ${metric.label.VALUE}。在本例中，VALUE 存储 PromQL 查询的值。 当您在 Google Cloud 中创建 PromQL 查询时，您还可以使用 ${metric.label.VALUE}。
metric_or_resource.labels	此变量会将所有指标和资源标签值呈现为 key-value 对的有序列表。如果指标标签和资源标签同名，则仅呈现指标标签。 当您迁移 Prometheus 提醒规则时，Prometheus 提醒字段模板 {{$labels}} 和 {{humanize $labels}} 在提醒政策文档配置中显示为 ${metric_or_resource.labels}。
metric_or_resource.label.KEY	如果 KEY 是有效标签，则此变量在通知中呈现为 ${metric.label.KEY} 的值。 如果 KEY 是有效资源，此变量将在通知中呈现为 ${resource.label.KEY} 的值。 如果 KEY 既不是有效标签，也不是有效资源，则此变量将在通知中呈现为空字符串。 当您迁移 Prometheus 提醒规则时，Prometheus 提醒字段模板 {{$labels.KEY}} 和 {{humanize $labels.KEY}} 在提醒政策文档配置中显示为 ${metric_or_resource.labels.KEY}。
policy.name	政策的 REST 资源名称，例如 projects/foo/alertPolicies/1234。
policy.display_name	政策的显示名，例如 High CPU rate of change。
policy.user_label.KEY	用户标签 KEY 的值。^1 键必须以小写字母开头。键和值只能包含小写字母、数字、下划线和短划线。
project	指标范围的范围限定项目的 ID，例如 a-gcp-project。
resource.type	受监控的资源类型，例如 gce_instance。
resource.project	提醒政策的受监控资源的项目 ID。
resource.label.KEY	资源标签 KEY 的值。^1、2、3 如需查找与受监控的资源类型关联的标签，请参阅资源列表。

¹ 例如，${resource.label.zone} 被替换为 zone 标签的值。这些变量的值会进行分组；如需了解详情，请参阅 null 值。
² 如需检索提醒政策中受监控的资源的 project_id 标签值，请使用 ${resource.project}。
³ 您无法通过使用 resource.label.KEY. 访问用户定义的资源元数据标签，请改用 metadata.user_label.KEY。

使用说明

• 只有上表中的变量受支持。您无法将它们组合成更复杂的表达式，如 ${varname1 + varname2}。
• 要将字面量字符串 ${ 包含在您的文档中，请再使用一个 $ 符号对 $ 符号进行转义，即 $${ 将在您的文档中呈现为 ${。
• 只有在通过通知渠道发送的通知中，这些变量才会被它们的值替换。在 Google Cloud 控制台中，所示文档时，您看到的是变量，而不是值。控制台中的示例包括创建提醒政策时的突发事件说明和文档预览。
• 确保条件的汇总设置不会消除标签。如果标签被消除，则通知中标签的值为 null。如需了解详情，请参阅指标标签的变量为 null。

注意 ：添加到基于日志的指标的标签不能用于模板表达式。但是，您可以在图表图例中显示这些标签，还可以按标签值过滤时序。

示例

以下示例展示了 Google Cloud 控制台和 Cloud Monitoring API 版本的 CPU 利用率提醒政策模板文档，以及显示在通知正文中的渲染文档。此示例使用通知渠道类型的电子邮件地址。该文档模板包含几个变量，用于总结突发事件并引用提醒政策和条件 REST 资源。

Google Cloud 控制台

注意 ：通知主题行在“创建提醒政策”页面的“通知和名称”部分进行配置。

## CPU utilization exceeded

### Summary

The ${metric.display_name} of the ${resource.type}
${resource.label.instance_id} in the project ${resource.project} has
exceeded 90% for over 15 minutes.

### Additional resource information

Condition resource name: ${condition.name}
Alerting policy resource name: ${policy.name}

### Troubleshooting and Debug References

Repository with debug scripts: example.com
Internal troubleshooting guide: example.com
${resource.type} dashboard: example.com

Cloud Monitoring API

"documentation": {
"content": "## CPU utilization exceeded\n\n### Summary\n\nThe ${metric.display_name} of the ${resource.type} ${resource.label.instance_id} in the project ${resource.project} has exceeded 90% for over 15 minutes.\n\n### Additional resource information\n\nCondition resource name: ${condition.name}  \nAlerting policy resource name: ${policy.name}  \n\n### Troubleshooting and Debug References\n    \nRepository with debug scripts: example.com  \nInternal troubleshooting guide: example.com  \n${resource.type} dashboard: example.com",
"mimeType": "text/markdown",
"subject": "Alert: ${metric.display_name} exceeded"
}

注意 ：subject 文本会显示在通知的主题行中。

通知中的格式

null 个值

metric.*、resource.* 和 metadata.* 变量的值是根据时序得出的。如果时序查询未返回任何值，则其值可以为 null。

• 如果您的提醒政策使用跨系列聚合（归约）（例如，计算与过滤条件匹配的每个时间序列的总和），则 resource.label.KEY 和 metric.label.KEY 变量可以具有 null 值。使用跨序列聚合时，没有用于分组的所有标签都会被舍弃，因此当变量被其值替换时，它们将呈现为 null。不存在跨系列汇总时，系统会保留所有标签。如需了解详情，请参阅指标标签的变量为 null。

• 只有在条件的过滤条件或用于跨序列聚合的分组中明确包含标签时，才可以使用 metadata.* 变量的值。也就是说，您必须在过滤条件或分组中引用元数据标签，才能让模板具有值。

可变分辨率

文档模板中的变量仅在使用以下通知渠道发送的通知中解析：

• 电子邮件
• Slack
• Pub/Sub、JSON 架构版本 1.2
• 网络钩子，JSON 架构版本 1.2
• PagerDuty，JSON 架构版本 1.2

变量不会被解析，但会在其他上下文中显示为字符串，如 ${varname}，包括以下内容：

• 在 Google Cloud 控制台的突发事件详情页面上。
• 在使用其他通知渠道发送的通知中。

使用渠道控制功能

文档字段中的文本还可以包含通知渠道本身用来控制格式和通知的特殊字符。

例如，Slack 使用 @ 表示提及。您可以使用 @ 将通知与特定用户 ID 相关联。提及的内容不能包含姓名。 假设您在文档字段中添加了一个如下所示的字符串：

<@backendoncall> Incident created based on policy ${policy.display_name}

当相关 Slack 频道在通知中收到该文档字段时，上一个字符串会导致 Slack 向用户 ID backendoncall 发送额外的消息。Slack 发送给用户的消息可能包含通知中的相关信息；例如，“Incident created based on policy High CPU rate of change”。

这些附加选项是特定于渠道的。如需详细了解可用选项，请参考渠道供应商提供的文档。