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

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

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

說明文件結構

警告政策的說明文件包含主旨、內容和連結。您可以在 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 資訊主頁等資源。

您可以使用 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} 形式的變數。如果文件是隨通知一併傳送，系統會從對應的 Google Cloud 資源中提取值，並取代 ${varname} 字串，如下表所述。

變數	值
`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}` 的值不是以數字、字母、正斜線 (`/`) 或等號 (`=`) 開頭，監控服務會在通知中省略標籤。遷移 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。

如果警告政策使用跨序列匯總 (縮減)，例如計算符合篩選條件的每個時間序列總和，則 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` 個值