本页面介绍了如何配置提醒政策文档,以自定义通知的正文和主题行。文档字段支持纯文本、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 |
指标标签 当变量 当您迁移 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。
示例
以下示例展示了 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" }
通知中的格式
null
个值
metric.*
、resource.*
和 metadata.*
变量的值是根据时序得出的。如果时序查询未返回任何值,则其值可以为 null
。
如果您的提醒政策使用跨系列聚合(缩减),例如计算与过滤条件匹配的每个时间序列的 SUM,则
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 向用户发送的消息可能包含通知中的相关信息;例如“基于政策高 CPU 变化率创建的事件”。
这些附加选项是特定于渠道的。如需详细了解可用选项,请参考渠道供应商提供的文档。