使用用户定义的文档为通知添加注解

本页介绍了如何配置提醒政策文档，以便通知为突发事件响应者提供资源和其他信息来帮助他们解决突发事件。

文档结构

提醒政策文档包含主题、内容和链接。您可以在 Google Cloud 控制台、Cloud Monitoring API 和 Google Cloud CLI 中配置文档。

主题

文档的主题会显示在与提醒政策相关的突发事件的通知主题中。通知接收人可以按主题管理和排序通知。

主题行的字符数上限为 255 个字符。如果您未在文档中定义主题，Cloud Monitoring 会确定主题行。主题行支持纯文本和变量。

内容

文档的内容会显示在以下通知类型中：

• 电子邮件（在政策文档部分）
• PagerDuty
• Pub/Sub
• Slack
• 网络钩子

我们建议您配置内容，以便突发事件响应人员能够在与提醒政策相关的通知中查看补救措施步骤和突发事件信息。例如，您可以将文档配置为包含相应事故的摘要和相关资源的信息。

文档内容支持以下内容：

• 纯文本
• 变量
• 频道专用控件

• Markdown

链接

您可以向文档中添加链接，以便突发事件响应人员通过通知访问 playbook、代码库和信息中心等资源。 Google Cloud

借助 Cloud Monitoring API，您可以定义一个对象，其中包含最相关的响应方链接。虽然 Google Cloud 控制台没有专门用于链接的字段，但您可以在文档正文中添加链接部分。

"links" [
  {
    "displayName": "Playbook",
    "url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
  }
]

### Troubleshooting and Debug References

Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}

文档内容中的 Markdown

您可以使用 Markdown 设置文档内容的格式。文档内容支持以下 Markdown 标记子集：

• 标题，以井号字符开头。
• 无序列表，以加号、减号或星号字符开头。
• 有序列表，以数字后跟英文句点开头。
• 斜体文本，由短语两边的单下划线或单星号表示。
• 粗体文本，由短语两边的双下划线或双星号表示。
• 链接，以 [link text](url) 语法表示。如需向通知添加链接，我们建议您使用 Cloud Monitoring API 并配置 Link 对象。

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

文档中的变量

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

¹ 例如，${resource.label.zone} 被替换为 zone 标签的值。这些变量的值会进行分组；如需了解详情，请参阅 null 值。
² 如需检索提醒政策中的受监控的资源上的 project_id 标签值，请使用 ${resource.project}。
³ 您无法使用 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
• Webhook，JSON 架构版本 1.2
• PagerDuty，JSON 架构版本 1.2

渠道控制选项

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

例如，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”（根据“High CPU rate of change”政策创建了问题）。

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

示例

以下示例展示了 CPU 利用率提醒政策的 Google Cloud 控制台和 Cloud Monitoring API 版本的模板文档。这些示例使用电子邮件作为通知渠道类型。文档模板包含多个变量，用于汇总突发事件并引用提醒政策和条件 REST 资源。

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

### 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