您可以使用 Cloud Monitoring API、Google Cloud CLI 或用戶端程式庫,建立、查看、列出、編輯及刪除以指標為依據的警告政策。您也可以將這些政策匯出為 JSON 或 YAML 檔案,以便備份及還原設定。 這項內容不適用於以記錄檔為準的警告政策。如要瞭解記錄警告政策,請參閱「監控記錄」。
如要在 Google Cloud 控制台建立及管理警告政策,請參閱「建立指標門檻警告政策」和「管理警告政策」。
這項功能僅支援 Google Cloud 專案。如要設定 App Hub,請選取 App Hub 主專案或管理專案。
關於警告政策
警告政策由 AlertPolicy 物件表示,該物件描述一組條件,指出系統可能處於不健康狀態。警告政策會參照通知管道,讓您指定警告政策觸發時的通知方式。
每項警告政策都屬於指標範圍的限定範圍專案。每個專案最多可包含 2,000 項政策。如果是 API 呼叫,您必須提供「專案 ID」,並使用指標範圍的範圍專案 ID 做為值。在這些範例中,指標範圍的範圍專案 ID 為 a-gcp-project。
AlertPolicy 資源支援五種作業:
- 建立新政策
- 刪除現有政策
- 擷取特定政策
- 擷取所有政策
- 修改現有政策
警告政策可以 JSON 或 YAML 格式表示,因此您可以在檔案中記錄政策,並使用檔案備份及還原政策。使用 Google Cloud CLI 時,您可以透過任一格式的檔案建立政策。您可以使用 REST API,透過 JSON 檔案建立政策。如需 JSON 格式的警告政策,請參閱「政策範例」。
以下範例使用 gcloud 介面和 API 說明這些基本用途。API 範例摘錄自範例程式,該程式使用 API 實作警告政策的備份和還原系統。如需更完整的範例,請參閱「範例:備份和還原」。
事前準備
在針對 API 編寫程式碼之前,您應該先:
- 熟悉警告政策的一般概念和術語;詳情請參閱「警告總覽」。
- 確認已啟用 Cloud Monitoring API。詳情請參閱「啟用 API」。
- 如果您打算使用用戶端程式庫,請安裝要使用的語言程式庫,詳情請參閱「用戶端程式庫」。API 支援快訊功能,但僅限 C#、Go、Java、Node.js 和 Python。
如果打算使用 Google Cloud CLI,請先安裝。不過,如果您使用 Cloud Shell,則 Google Cloud CLI 已安裝。
這裡也提供使用
gcloud介面的範例。請注意,gcloud範例都假設目前專案已設為目標 (gcloud config set project [PROJECT_ID]),因此叫用時會省略明確的--project旗標。範例中目前專案的 ID 為a-gcp-project。如要設定 App Hub,請選取 App Hub 主專案或管理專案。
-
如要取得使用 Cloud Monitoring API 建立及修改警告政策所需的權限,請要求管理員授予您專案的 Monitoring AlertPolicy 編輯者 (
roles/monitoring.alertPolicyEditor) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。如要進一步瞭解 Monitoring 的 IAM 角色,請參閱「使用 Identity and Access Management 控管存取權」。
設計應用程式時,請使用單一執行緒 Cloud Monitoring API 呼叫,修改Google Cloud 專案中警告政策的狀態。例如建立、更新或刪除警告政策的單一執行緒 API 呼叫。
建立警告政策
如要在專案中建立警告政策,請使用 alertPolicies.create 方法。如要瞭解如何叫用這個方法、其參數和回應資料,請參閱參考頁面 alertPolicies.create。
您可以透過 JSON 或 YAML 檔案建立政策。Google Cloud CLI 接受這些檔案做為引數,您可以使用 alertPolicies.create 方法,以程式輔助方式讀取 JSON 檔案、將其轉換為 AlertPolicy 物件,並從中建立政策。如果您有包含警告規則的 Prometheus JSON 或 YAML 設定檔,gcloud CLI 可以將其遷移至具有 PromQL 條件的 Cloud Monitoring 警告政策。詳情請參閱「[從 Prometheus 遷移警告規則和接收器][promql-alerts-migrate]」。
下列範例說明如何建立警告政策,但不會說明如何建立描述警告政策的 JSON 或 YAML 檔案。而是假設 JSON 格式的檔案存在,並說明如何發出 API 呼叫。如需 JSON 檔案範例,請參閱「政策範例」。如要瞭解監控指標比率的一般資訊,請參閱「指標比率」。
gcloud
如要在專案中建立警告政策,請使用 gcloud monitoring
policies create 指令。以下範例會從 rising-cpu-usage.json 檔案在 a-gcp-project 中建立警告政策:
gcloud monitoring policies create --policy-from-file="rising-cpu-usage.json"
如果成功,這個指令會傳回新政策的名稱,例如:
Created alert policy [projects/a-gcp-project/alertPolicies/12669073143329903307].
rising-cpu-usage.json 檔案包含政策的 JSON,顯示名稱為「High CPU rate of change」。如要進一步瞭解這項政策,請參閱「變化率政策」。
詳情請參閱 gcloud monitoring policies create 參考資料。
C#
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Go
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Java
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Node.js
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
PHP
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
建立的 AlertPolicy 物件會有額外欄位。政策本身會有 name、creationRecord 和 mutationRecord 欄位。此外,政策中的每個條件也會獲得 name。這些欄位無法從外部修改,因此建立政策時不需設定。用於建立政策的所有 JSON 範例都不包含這些欄位,但如果在利用這些欄位建立政策之後擷取政策,這些欄位會顯示出來。
列出及取得警告政策
如要擷取專案中的政策清單,請使用 alertPolicies.list 方法。您可以使用這個方法擷取政策,並對每項政策套用某些動作,例如備份。這個方法也支援 filter 和 orderBy 選項,可用於限制及排序結果,詳情請參閱「排序和篩選」。
如果您要尋找特定政策,且知道政策名稱,可以使用 alertPolicies.get 方法,只擷取該政策。政策名稱是 AlertPolicy 物件中 name 欄位的值,而非 displayName。政策名稱的格式為 projects/[PROJECT_ID]/alertPolicies/[POLICY_ID],例如:
projects/a-gcp-project/alertPolicies/12669073143329903307
gcloud
如要列出專案中的所有警告政策,請使用 gcloud monitoring
policies list 指令:
gcloud monitoring policies list
如果成功,list 指令會以 YAML 格式列出指定專案中的所有政策。舉例來說,專案 a-gcp-project 中顯示名稱為「High CPU rate of change」的政策會與其他政策一起列出,如下所示:
---
combiner: OR
conditions:
- conditionThreshold:
aggregations:
- alignmentPeriod: 900s
perSeriesAligner: ALIGN_PERCENT_CHANGE
comparison: COMPARISON_GT
duration: 180s
filter: metric.type="compute.googleapis.com/instance/cpu/utilization" AND resource.type="gce_instance"
thresholdValue: 0.5
trigger:
count: 1
displayName: CPU usage is increasing at a high rate
name: projects/a-gcp-project/alertPolicies/12669073143329903307/conditions/12669073143329903008
creationRecord:
mutateTime: '2018-03-26T18:52:39.363601689Z'
mutatedBy: [USER@DOMAIN]
displayName: High CPU rate of change
enabled: true
mutationRecord:
mutateTime: '2018-03-26T18:52:39.363601689Z'
mutatedBy: [USER@DOMAIN]
name: projects/a-gcp-project/alertPolicies/12669073143329903307
---
如要列出單一警告政策,請改用 gcloud monitoring policies
describe 並指定政策名稱。例如,這個指令只會傳回上方的清單:
gcloud monitoring policies describe projects/a-gcp-project/alertPolicies/12669073143329903307
詳情請參閱 gcloud monitoring policies list 和 describe 參考資料。describe 指令對應 API 中的 alertPolicies.get 方法。
C#
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Go
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Java
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Node.js
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
PHP
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
刪除警告政策
如要從專案中刪除政策,請使用 alertPolicies.delete 方法,並提供要刪除的警告政策名稱。
gcloud
如要刪除警告政策,請使用 gcloud monitoring policies
delete,並指定要刪除的政策名稱。舉例來說,下列指令會刪除顯示名稱為「High CPU rate of change」的政策:
gcloud monitoring policies delete projects/a-gcp-project/alertPolicies/12669073143329903307
詳情請參閱 gcloud monitoring policies delete 參考資料。
修改警告政策
如要修改警告政策,請使用 alertPolicies.patch 方法 (在 REST API 中)。其他 API 實作和 gcloud 介面會呼叫這個 update,而非 patch。
更新作業可以完全取代現有政策,也可以修改欄位子集。更新作業會採用新的 AlertPolicy 物件和選用的欄位遮罩。
如果指定欄位遮罩,則列在欄位遮罩中的任何欄位,都會更新為所提供政策中的值。如果提供的政策不包含欄位遮罩中提及的欄位,則會清除該欄位並將其設定為預設值。未列在遮罩中的任何欄位會保留之前的值。
如未指定欄位遮罩,現有政策會由提供的政策取代,但名稱 (projects/[PROJECT_ID]/alertPolicies/[POLICY_ID]) 會重複使用。新政策中任何條件的 name 值若包含 CONDITION_ID,則會保留這些名稱。若非如此,則會建立新條件與政策名稱。
使用 gcloud 指令列更新政策時,請使用指令列旗標 (而非欄位遮罩) 指定要更新的欄位。詳情請參閱 gcloud monitoring policies update。
您可以使用標籤,將警告政策與 App Hub 應用程式建立關聯。詳情請參閱「如何將警告政策與 App Hub 應用程式建立關聯」。
啟用或停用警告政策
如要啟用或停用政策,請變更 AlertPolicy 物件中布林值 enabled 欄位的值。請注意,在您啟用政策之後,仍可透過停用時收集的資料觸發。
gcloud
如要停用警告政策,請使用 gcloud monitoring policies update 指令並提供 --no-enabled 旗標。下列指令會停用專案 a-gcp-project 中的「High CPU rate of change」警告政策:
gcloud monitoring policies update projects/a-gcp-project/alertPolicies/12669073143329903307 --no-enabled
如要啟用政策,請使用相同指令並提供 --enabled 旗標。詳情請參閱 gcloud monitoring policies update 參考資料。update 指令對應 REST API 中的 alertPolicies.patch 方法。
C#
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Go
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Java
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Node.js
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
PHP
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
更新警告政策中的通知管道
您也可以更新警告政策參照的通知管道。警告政策會依名稱參照通知管道。管道必須存在,才能用於警告政策。
您可以使用 NotificationChannel 和 NotificationChannelDescriptors 資源,透過程式輔助方式建立及管理通知管道。本節的範例均假設這些管道已經存在,並在程式範例中顯示這些 API 的使用情況。
如要進一步瞭解通知管道物件,請參閱「透過 API 建立及管理通知管道」。
gcloud
如要修改警告政策中的通知管道,請使用 gcloud monitoring policies update 指令。有多個與通知管道相關的標記,可讓您移除通知管道、取代通知管道,及新增通知管道。
例如,a-gcp-project 專案中顯示名稱為「High CPU rate of change」的政策,在建立時並沒有使用通知管道。
如要將通知管道新增至這項政策,請使用 gcloud monitoring
policies update 指令,並以 --add-notification-channels 旗標指定要新增的管道:
gcloud monitoring policies update projects/a-gcp-project/alertPolicies/12669073143329903307 \
--add-notification-channels="projects/a-gcp-project/notificationChannels/1355376463305411567"
詳情請參閱 gcloud monitoring policies update 參考資料。update 指令對應 REST API 中的 alertPolicies.patch 方法。
這裡新增的通知管道必須已存在。詳情請參閱「建立通知管道」。
C#
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Go
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Java
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Node.js
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
PHP
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
修改警告政策中的說明文件
政策可以包含文件,這些文件會隨附於與政策相關聯的警告和通知。使用這個欄位說明資訊,以協助回應者瞭解及處理快訊政策所指出的問題。說明文件包含在允許使用該說明文件的電子郵件通知與通知類型中;其他管道類型可能會省略說明文件。
gcloud
如要為政策新增說明文件,或取代現有說明文件,請使用gcloud monitoring policies update 指令,並提供 --documentation-format="text/markdown" 旗標 (唯一支援的格式),以及 --documentation 旗標 (從指令列輸入值) 或 --documentation-from-file 旗標 (從檔案讀取值)。
舉例來說,a-gcp-project 專案中顯示名稱為「High CPU rate of change」(高 CPU 變更頻率) 的政策建立時並沒有說明文件。
下列指令會將指定政策中的 documentation 欄位設為 cpu-usage-doc.md 檔案的內容:
gcloud monitoring policies update projects/a-gcp-project/alertPolicies/12669073143329903307 \
--documentation-format="text/markdown" \
--documentation-from-file="cpu-usage-doc.md"
詳情請參閱 gcloud monitoring policies update 參考資料。update 指令對應 REST API 中的 alertPolicies.patch 方法。
在資訊主頁新增警告政策
如要在自訂資訊主頁上顯示單一條件警告政策的摘要,請在資訊主頁中新增 AlertChart 小工具。如果是新的資訊主頁,請使用 dashboards.create 方法;如果是現有的資訊主頁,請使用 dashboards.patch 方法。
如果指定多條件警告政策,AlertChart 小工具就不會顯示資料。
如要進一步瞭解如何使用這些 API 方法,請參閱「使用 API 建立及管理資訊主頁」。
範例:備份與還原
顯示的所有 API 範例均提取自較大的應用程式,進而可將專案中的警告政策備份到檔案中,並在可能的情況下,將政策還原至其他專案。如果用於備份與還原的專案不同,應用程式可在專案之間有效匯出及匯入政策。
本節會將適用於備份與還原的程式碼顯示在背景資訊中,而不是顯示為一組小型的獨立摘錄。
備份政策
備份作業非常簡單。系統會收集各專案中的警告政策和通知管道,並以 JSON 格式儲存至外部儲存空間。
C#
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Go
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Java
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Node.js
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
PHP
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
還原備份政策
還原程序比原始備份更複雜。您可以還原至最初備份的專案,您也可以還原至其他專案,有效提供警告政策匯入功能。
如果您還原至相同專案,任何現有管道或政策都會更新 (若其仍然存在)。如果沒有,則會重新建立。在重新建立政策和通知之前,還原程序會清除備份政策中的唯讀欄位,例如建立和變更記錄。
您可以利用儲存在某個專案中的政策,在另一個專案中建立全新或類似的政策。但是,您必須在儲存政策的副本中先進行下列變更:
- 從任何通知管道中移除下列欄位:
nameverificationStatus
- 建立通知管道,然後在快訊政策中參照這些通知管道 (您需要新的管道 ID)。
- 從您重新建立的任何警告政策中移除下列欄位:
namecondition.namecreationRecordmutationRecord
此外,如果要在新專案中重新建立政策,備份政策中任何條件的名稱也要與建立和異動記錄一併清除。
此外,在其他專案中重新建立通知管道時,系統會指派不同的名稱,因此還原程序必須將備份警告政策中的管道名稱對應至新名稱,並以新名稱取代舊名稱。
除了通知管道的名稱之外,建立或更新管道時也無法設定 verificationStatus 欄位的值,因此會使用標記值 unspecified。在將管道還原至新專案之後,必須對其明確驗證。
C#
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Go
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Java
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Node.js
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
PHP
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
如要向 Monitoring 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
警告和 Google Cloud CLI
在 Google Cloud CLI 中,用於管理警告政策和通知管道的指令群組為 monitoring。這些指令的開頭都是:
gcloud monitoring
如要確認是否已安裝 Google Cloud CLI,請執行下列指令:
gcloud --version
如果尚未安裝 Google Cloud CLI,請參閱「安裝 Google Cloud CLI」。
如要檢查 monitoring 群組,請執行下列指令:
gcloud monitoring --help
如果未包含 monitoring 群組,Google Cloud CLI 會提示您新增:
You do not currently have this command group installed.
[...]
Do you want to continue (Y/n)? y