使用者定義的說明文件註解通知

本頁說明如何設定警示政策文件，讓事件回應人員在收到通知時，能取得事件解決所需的資源和其他資訊。

說明文件結構

快訊政策的說明文件包含主旨、內容和連結。您可以在 Google Cloud 控制台、Cloud Monitoring API 和 Google Cloud CLI 中設定說明文件。

主體

說明文件的主旨會顯示在與警示政策相關事件的通知主旨中。通知接收者可以管理通知並依主題排序。

主旨行的長度上限為 255 個半形字元。如果您未在說明文件中定義主旨，Cloud Monitoring 會決定主旨行。主旨可支援純文字和變數。

內容

說明文件的內容會顯示在下列通知類型中：

• 電子郵件，位於「政策說明文件」部分
• PagerDuty
• Pub/Sub
• Slack
• Webhook

建議您設定內容，讓事件回應人員可以在與警示政策相關的通知中，查看因應步驟和事件資訊。舉例來說，您可以設定說明文件，讓其包含事件摘要和相關資源的資訊。

說明文件內容支援下列功能：

• 純文字
• 變數
• 管道專屬控制項

• Markdown

連結

您可以為說明文件新增連結，讓事件回應者能夠透過通知存取指南、存放區和 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 個值

metric.*、resource.* 和 metadata.* 變數的值會從時間序列衍生而來。如果時間序列查詢未傳回任何值，則其值可以是 null。

• 如果警示政策使用跨系列匯總 (縮減)，resource.label.KEY 和 metric.label.KEY 變數可以有 null 值，例如在符合篩選條件的每個時間序列中計算總和。使用跨系列匯總時，系統會捨棄「未」用於分組的任何標籤，因此當變數替換為其值時，這些標籤會顯示為 null。在沒有跨序列匯總的情況下，系統會保留所有標籤。詳情請參閱「指標標籤的變數為空值」。

• 只有在條件的篩選器或分組中明確加入標籤，以便跨系列匯總時，才能使用 metadata.* 變數的值。也就是說，您必須在篩選器或分組中參照中繼資料標籤，才能為範本提供值。

可變解析度

說明文件範本中的變數只會在使用下列通知管道傳送的通知中解析：

• 電子郵件
• Google Chat
• Slack
• Pub/Sub，JSON 結構定義版本 1.2
• Webhooks，JSON 結構定義版本 1.2
• PagerDuty，JSON 結構定義版本 1.2

管道控制選項

說明文件欄位中的文字也可以包含通知管道本身使用的特殊字元，以控制格式設定與通知。

舉例來說，Slack 會使用 @ 來提及使用者。您可以使用 @ 將通知連結至特定使用者 ID。提及不得包含姓名。假設您在說明文件欄位中加入以下字串：

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

當相關 Slack 頻道收到說明欄位做為通知的一部分時，前述字串會導致 Slack 傳送額外訊息至使用者 ID backendoncall。Slack 傳送給使用者的訊息可能會包含通知中的相關資訊，例如「根據政策『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