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

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

說明文件結構

快訊政策的說明文件包含主旨、內容和連結。您可以在 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 物件，代表事件劇本的網址。網址包含變數，因此通知收件者可以根據發生事件的受監控資源，存取正確的 Playbook：

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

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

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

Google Cloud 控制台

如要將連結加入說明文件內容，請在快訊政策的「說明文件」欄位中加入連結。舉例來說，下列說明文件列出客戶劇本的網址：

### 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`。
`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}。
如要在文件中加入常值字串 ${，請使用第二個 $ 符號逸出 $ 符號，這樣 $${ 在文件中就會顯示為 ${。
只有透過通知管道傳送的通知，才會將這些變數替換為值。在 Google Cloud 控制台中，顯示文件時會看到變數，而不是值。舉例來說，在控制台中建立快訊政策時，您會看到事件說明和文件預覽畫面。
確認條件的匯總設定不會排除標籤。如果標籤遭到淘汰，通知中的標籤值會是 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

頻道控制選項

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

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

<@backendoncall> Incident 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` 個值