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

本頁說明如何設定快訊政策文件，讓通知提供事件應變人員資源和額外資訊，協助解決事件。

說明文件結構

快訊政策的說明文件包含主旨、內容和連結。您可以在 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} 形式的變數。如果文件是隨通知一併傳送，系統會從對應的 Google Cloud 資源中提取值，並取代 ${varname} 字串，如下表所述。

¹ 例如，${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
• Webhook，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