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

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

文档结构

提醒政策的文档包含主题、内容和链接。您可以在 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”（已根据“CPU 变化率过高”政策创建突发事件）。

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

示例

以下示例展示了 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