本页面介绍了如何配置提醒政策文档。 以便通知为突发事件响应人员提供资源和 获取更多信息，以便解决突发事件。
文档结构
提醒政策文档包含主题、内容和链接。您可以在 Google Cloud 控制台、Cloud Monitoring API 和 Google Cloud CLI 中配置文档。
主体
文档的主题显示在 与提醒政策相关的突发事件的通知。 通知接收者可以管理通知并按主题分类。
主题行不得超过 255 个字符。如果您未在 Cloud Monitoring 会确定主题行。 主题行支持纯文本和变量。
Cloud Monitoring API
使用 subject 字段配置通知主题行
提醒政策 documentation。
Google Cloud 控制台
在创建提醒政策页面的通知和名称部分中，使用通知主题行字段配置通知主题行。
内容
文档内容显示在以下通知中 类型：
- 电子邮件（位于政策文档标题下）
- PagerDuty
- Pub/Sub
- Slack
- Webhook
我们建议您配置内容 响应者可以在通知中查看补救步骤和事件信息 与提醒政策相关例如，您可以将 包含事件摘要和 了解相关资源的信息。
文档内容支持纯文本、Markdown、 variables和渠道专用控件。
Cloud Monitoring API
使用 content 字段配置文档内容
提醒政策 documentation。
Google Cloud 控制台
使用 Documentation 字段（位于 创建提醒政策页面的通知和名称部分。
链接
您可以添加指向文档的链接，以便突发事件响应人员 访问策略方案、代码库和 Google Cloud 信息中心等资源 。
Cloud Monitoring API
在 Cloud Monitoring API 中配置的文档链接会显示在以下通知类型中：
- 快速链接标题下的电子邮件
- PagerDuty
- Pub/Sub
- Webhook
如需配置链接，请将 Link 添加到提醒政策的 documentation。每个链接由一个 display_name 和 url 表示。文档中最多可以包含三个链接。
以下配置使用 links 和 1 个网址
创建指向突发事件策略方案的链接。网址包含一个变量
通知接收者可以根据
发生突发事件的受监控的资源：
"links" [
{
"displayName": "Playbook",
"url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
}
]
Google Cloud 控制台
在 Google Cloud 控制台中配置的文档链接会与 以下通知类型中的其他文档内容：
- Policy Documentation 标题下的电子邮件
- PagerDuty
- Pub/Sub
- Slack
- Webhook
您可以通过包含链接来添加指向文档内容的链接 您的提醒政策的 Documentation 字段中。例如，以下文档列出了客户手册的网址：
### Troubleshooting and Debug References
Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}
文档内容中的 Markdown
您可以使用 Markdown 设置文档内容的格式。文档内容支持以下 Markdown 标记子集：
- 标题，以井号字符开头。
- 无序列表，以加号、减号或星号字符开头。
- 有序列表，以数字后跟英文句点开头。
- 斜体文本，由短语两边的单下划线或单星号表示。
- 粗体文本，由短语两边的双下划线或双星号表示。
- 链接，以
[link text](url)语法表示。不过，我们建议您使用Link对象，用于为您的内容配置链接。
如需详细了解此标记，请参阅任意 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 |
指标标签 如果变量 迁移 Prometheus 提醒规则后，提醒政策文档配置中的 Prometheus 提醒字段模板 您还可以在 Google Cloud 中创建 PromQL 查询时使用 |
metric_or_resource.labels |
此变量会将所有指标和资源标签值呈现为 当您迁移 Prometheus 提醒规则时，Prometheus 提醒字段模板为 |
metric_or_resource.label.KEY |
迁移 Prometheus 提醒规则后，Prometheus 提醒字段模板 |
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如需查找与受监控的资源类型关联的标签，请参阅 资源列表。 |
1 例如，${resource.label.zone} 被替换为 zone 标签的值。这些变量的值会进行分组；如需了解详情，请参阅 null 值。
2 如需检索提醒政策中的受监控资源上的 project_id 标签值，请使用 ${resource.project}。
3 您无法通过以下方式访问用户定义的资源元数据标签：
使用 resource.label.KEY. 使用 metadata.user_label.KEY
。
使用说明
- 只有上表中的变量受支持。您无法将它们组合成更复杂的表达式，如
${varname1 + varname2}。 - 要将字面量字符串
${包含在您的文档中，请再使用一个$符号对$符号进行转义，即$${将在您的文档中呈现为${。 - 只有在通过通知渠道发送的通知中，这些变量才会被它们的值替换。在 Google Cloud 控制台中显示文档时，您看到的是变量，而不是值。控制台中的示例包括创建提醒政策时的突发事件说明和文档预览。
- 确保条件的汇总设置不会消除标签。如果移除标签，则通知中标签的值为
null。如需了解详情，请参阅指标标签的变量为 null。
null 个值
metric.*、resource.* 和 metadata.* 变量的值是根据时间序列得出的。如果时间序列查询未返回任何值，则其值可以为 null。
resource.label.KEY和metric.label.KEY变量可以有null值（如果您的提醒政策使用跨系列汇总） 例如计算每个时间段的总和， 与过滤条件匹配的时间序列。使用跨序列聚合时，没有用于分组的所有标签都会被舍弃，因此当变量被其值替换时，它们将呈现为null。所有标签 则会保留。 如需更多信息 请参阅指标标签的变量为 null。只有在条件的过滤条件或用于跨序列聚合的分组中明确包含标签时，才可以使用
metadata.*变量的值。也就是说，您必须在过滤条件或分组中引用元数据标签，才能让模板具有值。
可变分辨率
文档模板中的变量仅在通知中解析 使用以下通知渠道发送：
- 电子邮件
- Google Chat
- Slack
- Pub/Sub，JSON 架构版本 1.2
- 网络钩子，JSON 架构版本 1.2
- PagerDuty，JSON 架构版本 1.2
渠道控件
文档字段中的文本还可以包含通知渠道本身用来控制格式和通知的特殊字符。
例如，Slack 使用 @ 表示提及。您可以使用 @ 将
向特定用户 ID 发出通知提及的内容中不能包含姓名。
假设您在文档字段中包含了这样一个字符串：
<@backendoncall> Incident created based on policy ${policy.display_name}
当相关 Slack 频道收到文档字段时
上一个字符串会导致 Slack 将
向用户 ID 发送额外消息
backendoncall。Slack 发送给用户的消息
可能包含通知中的相关信息；例如
“基于政策高 CPU 变化率创建的突发事件”。
这些附加选项是特定于渠道的。如需详细了解可用选项，请参考渠道供应商提供的文档。
示例
以下示例展示了 Google Cloud 控制台和 Cloud Monitoring API 的 CPU 利用率提醒政策的模板文档。 以下示例使用电子邮件作为通知渠道类型。 文档模板包含多个变量，用于总结相应事件并引用提醒政策和条件 REST 资源。
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 5% for over 60 seconds.\n\n#### Additional resource information\n\nCondition resource name: ${condition.name} \nAlerting policy resource name: ${policy.name}",
"mimeType": "text/markdown",
"subject": "Alert: ${metric.display_name} exceeded",
"links": [
{
"displayName": "Playbook",
"url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
},
{
"displayName": "Repository with debug scripts",
"url": "https://altostrat.com"
},
{
"displayName": "Google Cloud dashboard",
"url": "https://example.com"
}
]
}
下图显示了此模板在电子邮件通知中的显示方式：
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 5% for over 60 seconds.
#### Additional resource information
Condition resource name: ${condition.name}
Alerting policy resource name: ${policy.name}
#### Troubleshooting and Debug References
Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}
Repository with debug scripts: https://altostrat.com
${resource.type} dashboard: https://example.com
下图显示了此模板在电子邮件中的显示方式 通知：
