Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

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

您可以在警告政策中新增自訂文件，Cloud Monitoring 會將這些文件納入通知。這份使用者定義的文件可包含疑難排解資訊和連結，協助應變人員解決警告。您可以使用 Markdown 設定這份文件的格式，並新增變數。Monitoring 會在傳送通知時，將變數替換為警告政策和監控資料的詳細資料。

說明文件結構

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

主體

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

主旨行長度不得超過 255 個半形字元。如未在說明文件中定義主旨，Cloud Monitoring 會決定主旨行。主旨支援純文字和變數。

Cloud Monitoring API

使用警告政策 documentation 的 subject 欄位，設定通知主旨行。

Google Cloud 控制台

在「建立警告政策」頁面的「通知與名稱」部分，使用「通知主旨」欄位設定通知主旨。

內容

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

電子郵件地址 (位於「政策文件」部分)
PagerDuty
Pub/Sub
Slack
Webhook

建議您設定內容，讓警告應變人員在與警告政策相關的通知中，查看修復步驟和警告資訊。舉例來說，您可以設定說明文件，加入警告摘要和相關資源的資訊。

說明文件內容支援下列項目：

Cloud Monitoring API

使用警告政策 documentation 的 content 欄位，設定說明文件內容。

Google Cloud 控制台

在「建立警告政策」頁面的「通知和名稱」部分，使用「說明文件」欄位設定說明文件內容。

連結

您可以新增說明文件連結，讓警告回應者能從通知存取 Google Cloud 資訊主頁、playbook 和存放區等資源。

Cloud Monitoring API 可讓您定義物件，其中包含與應變人員最相關的連結。雖然 Google Cloud 控制台沒有專門用於連結的欄位，但您可以在說明文件內文中新增連結專區。

Cloud Monitoring API

您可以在警告政策 documentation 的 links 欄位中定義一或多個 Link 物件，藉此新增說明文件連結。每個 Link 物件都包含 display_name 和 url。說明文件最多可包含三個連結。

下列設定顯示 links 欄位，其中包含一個 Link 物件，代表快訊劇本的網址。網址包含變數，因此通知收件者可以根據發生快訊的受監控資源，存取正確的劇本：

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

使用 Link 欄位新增的文件連結會顯示在下列通知類型中：

「快速連結」專區中的電子郵件
PagerDuty
Pub/Sub
Webhook

Google Cloud 控制台

您可以在警告政策的「Documentation」(說明文件) 欄位中加入說明文件內容的連結。舉例來說，下列說明文件列出客戶劇本的網址：

### Troubleshooting and Debug References

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

使用 Google Cloud 控制台新增的文件連結會與其他文件內容一起顯示在下列通知類型中：

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

說明文件內容中的 Markdown

您可以使用 Markdown 設定文件內容的格式。文件內容支援下列 Markdown 標記子集：

標題，以開頭的井號字元表示。
未排序的清單，以開頭的加號、減號或星號表示。
已排序的清單，以開頭數字後接句號表示。
斜體文字，以單一下底線或星號括住詞組表示。
粗體文字，以雙底線或星號括住詞組表示。
連結，以 [link text](url) 語法表示。如要在通知中加入連結，建議使用 Cloud Monitoring API 並設定 Link 物件。

如要進一步瞭解這類標記，請參閱任何 Markdown 參考資料，例如 Markdown 指南。

說明文件中的變數

如要自訂文件中的文字，可以使用 ${varname} 形式的變數。當說明文件與通知一起傳送時，字串 ${varname} 會替換為從對應 Google Cloud 資源中提取的值，如下表所示。

變數	值
`condition.name`	條件的 REST 資源名稱，例如 `projects/foo/alertPolicies/1234/conditions/5678`。
`condition.display_name`	條件的顯示名稱，例如 `CPU usage increasing rapidly`。如果是使用 Logs Explorer 建立的記錄警告政策，這個欄位的值為 `"Log match condition"`。如要自訂這個欄位的值，請使用 Cloud Monitoring API。
`log.extracted_label.KEY`	從記錄項目擷取的標籤 `KEY` 值。僅適用於記錄警告政策；詳情請參閱「使用 Monitoring API 建立記錄警告政策」。
`metadata.system_label.KEY`	系統提供的資源中繼資料標籤值 `KEY`.¹
`metadata.user_label.KEY`	使用者定義的資源中繼資料標籤 `KEY` 的值。^1,3
`metric.type`	指標類型，例如 `compute.googleapis.com/instance/cpu/utilization`。
`metric.display_name`	指標類型的顯示名稱，例如 `CPU utilization`。
`metric.label.KEY`	指標標籤 `KEY` 的值。¹ 如要找出與指標類型相關聯的標籤，請參閱指標清單。如果變數 `${metric.label.KEY}` 的值開頭不是數字、字母、正斜線 (`/`) 或等號 (`=`)，Monitoring 會在通知中省略標籤。遷移 Prometheus 警告規則時，Prometheus 警告欄位範本 `{{$value}}` 和 `{{humanize $value}}` 會顯示為警告政策說明文件設定中的 `${metric.label.value}`。在這種情況下，`${metric.label.value}` 會保留 Prometheus 警告規則的觸發值。您也可以在 Google Cloud中建立 PromQL 查詢時使用 `${metric.label.value}`。
`metric.label.metadata_system_VALUE`	參照 PromQL 中繼資料系統標籤，其中 `VALUE` 是特定標籤名稱，例如 `region` 或 `version`。使用範例：`${metric.label.metadata_system_version}`。
`metric.label.metadata_user_VALUE`	參照 PromQL 中繼資料使用者標籤，其中 `VALUE` 是特定標籤名稱，例如 `region` 或 `name`。使用範例：`${metric.label.metadata_user_name}`。
`metric_or_resource.labels`	這個變數會將所有指標和資源標籤值，轉譯為已排序的 `key-value` 組合清單。如果指標標籤和資源標籤的名稱相同，系統只會顯示指標標籤。遷移 Prometheus 警告規則時，Prometheus 警告欄位範本 `{{$labels}}` 和 `{{humanize $labels}}` 會在警告政策說明文件設定中顯示為 `${metric_or_resource.labels}`。
`metric_or_resource.label.KEY`	如果 `KEY` 是有效標籤，這個變數就會在通知中顯示為 `${metric.label.KEY}` 的值。如果 `KEY` 是有效資源，這個變數就會在通知中顯示為 `${resource.label.KEY}` 的值。如果 `KEY` 不是有效的標籤或資源，這個變數在通知中會顯示為空字串。遷移 Prometheus 警告規則時，Prometheus 警告欄位範本 `{{$labels.KEY}}` 和 `{{humanize $labels.KEY}}` 會顯示為警告政策說明文件設定中的 `${metric_or_resource.labels.KEY}`。
`policy.name`	政策的 REST 資源名稱，例如 `projects/foo/alertPolicies/1234`。
`policy.display_name`	政策的顯示名稱，例如 `High CPU rate of change`。
`policy.user_label.KEY`	使用者標籤 `KEY` 的值。¹ 鍵的開頭須為小寫英文字母。鍵和值只能包含小寫字母、數字、底線和破折號。
`project`	指標範圍的範圍專案 ID，例如 `a-gcp-project`。
`resource.type`	受監控資源類型，例如 `gce_instance`。
`resource.project`	警告政策受監控資源的專案 ID。
`resource.label.KEY`	資源標籤 `KEY` 的值。^1,2,3 如要查看與受監控資源類型相關聯的標籤，請參閱資源清單。

¹ 舉例來說，${resource.label.zone} 會替換為 zone 標籤的值。這些變數的值會分組，詳情請參閱「null 值」。
² 如要擷取警告政策中受監控資源的 project_id 標籤值，請使用 ${resource.project}。
³ 您無法使用 resource.label.KEY. 存取使用者定義的資源中繼資料標籤，請改用 metadata.user_label.KEY。

使用須知

系統僅支援表格中的變數。您無法將這些運算子組合成更複雜的運算式，例如 ${varname1 + varname2}。
如要在說明文件中加入常值字串 ${，請使用第二個 $ 符號逸出 $ 符號，$${ 會在說明文件中顯示為 ${。
警告政策一律會顯示 ${varname} 等變數字串。
對於部分通知管道，Cloud Monitoring 會將 ${varname} 等變數字串替換為對應值。詳情請參閱「變數解析」。
Google Cloud 控制台顯示快訊的詳細資料檢視畫面時，通常會將 ${varname} 等變數字串替換為對應的值。
確認條件的匯總設定不會排除標籤。如果標籤遭到刪除，通知中的標籤值會是 null。詳情請參閱「指標標籤的變數為空值」。

`null` 個值

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

如果警告政策使用跨序列匯總 (縮減)，例如計算符合篩選條件的每個時間序列的 SUM，則 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 版
控制台快訊詳細資料檢視畫面。 Google Cloud

管道控制選項

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

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

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

當相關 Slack 頻道收到文件欄位做為通知的一部分時，先前的字串會導致 Slack 向使用者 ID backendoncall 傳送額外訊息。Slack 傳送給使用者的訊息可能包含通知中的相關資訊，例如「根據『CPU 變化率偏高』政策建立快訊」。

這些額外選項是管道特有的選項；如要進一步瞭解可能提供的選項，請參閱管道廠商提供的說明文件。

範例

以下範例顯示 CPU 使用率警告政策的範本說明文件，包括 Google Cloud 控制台和 Cloud Monitoring API 版本。這些範例使用電子郵件做為通知管道類型。說明文件範本包含多個變數，可彙整警告摘要，並參照警告政策和條件 REST 資源。

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

下圖顯示電子郵件通知中的範本：

通知中顯示說明文件的範例。連結會顯示在「快速連結」部分。

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

下圖顯示這個範本在電子郵件通知中的顯示方式：

範例：通知中顯示的文件。連結會顯示在「疑難排解和偵錯參考資料」標題下方。

使用者定義的說明文件註解通知 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

說明文件結構

主體

Cloud Monitoring API

Google Cloud 控制台

內容

Cloud Monitoring API

Google Cloud 控制台

連結

Cloud Monitoring API

Google Cloud 控制台

說明文件內容中的 Markdown

說明文件中的變數

使用須知

null 個值

可變解析度

管道控制選項

範例

Cloud Monitoring API

Google Cloud 控制台

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

`null` 個值