您可以使用 Cloud Monitoring API 和 Google Cloud CLI,透過 JSON 或 YAML 檔案或用戶端程式庫建立警告政策。每個 AlertPolicy 物件都會定義指標式或記錄式條件,指出系統可能處於不良狀態,以及通知管道和警告策略。
使用 Monitoring API 時,您必須使用使用者憑證進行驗證,而非 API 金鑰。例如,您可以為使用者或服務帳戶提供 OAuth 2.0 權杖。詳情請參閱「使用 OAuth 2.0 存取 Google API」和「 Google Cloud API 和服務的驗證」。
這項功能僅支援 Google Cloud 專案。如要設定 App Hub,請選取 App Hub 主專案或管理專案。
警告政策的結構
AlertPolicy 結構定義了警告政策的元件。建立政策時,請指定下列 AlertPolicy 欄位的值:
displayName:政策的說明標籤。documentation:建議您使用這個欄位提供資訊,協助快訊應變人員。詳情請參閱「使用使用者定義的文件為通知加上註解」。userLabels:附加至政策的使用者定義標籤。警告政策、警告和通知會顯示這些標籤。如要瞭解如何搭配使用標籤和警告,請參閱「使用標籤為警告加上註解」。conditions[]:Condition結構的陣列。combiner:邏輯運算子,決定如何處理多個條件。notificationChannels[]:資源名稱陣列,每個名稱都代表一個NotificationChannel。alertStrategy:指定下列項目:- Monitoring 在資料停止傳入後,關閉快訊的速度。
- 如果是以指標為準的警告政策,Monitoring 是否會在警告關閉時傳送通知。
- 如果是以指標為依據的警告政策,則會顯示是否啟用重複通知,以及通知之間的間隔。詳情請參閱「設定指標警告政策的重複通知」。
使用 Cloud Monitoring API 和 Google Cloud 控制台時,您也可以指定 severity 欄位。這個欄位可讓您定義快訊的嚴重性等級。如未指定嚴重性,Cloud Monitoring 會將警告政策嚴重性設為 No Severity。
視您建立的條件而定,您可能還會用到其他欄位。
如果警告政策包含一項條件,系統會在符合該條件時傳送通知。如要瞭解警告政策包含多個條件時的通知,請參閱「具有多個條件的政策」和「Monitoring 傳送通知和建立警告的時機」。
建立或修改警告政策時,Monitoring 也會設定其他欄位,包括 name 欄位。name 欄位的值是警告政策的資源名稱,用於識別政策。資源名稱格式如下:
projects/PROJECT_ID/alertPolicies/POLICY_ID
在上述運算式中:
- PROJECT_ID:專案 ID。如要設定 App Hub,請選取 App Hub 主專案或管理專案。
- POLICY_ID:警告政策的 ID
API 中的條件類型
Cloud Monitoring API 支援 Condition 結構中的多種條件類型。指標型警告政策有多種條件類型,記錄型警告政策則只有一種。以下各節說明可用的條件類型。
以指標為準的警告政策條件
如要建立警告政策來監控指標資料 (包括記錄指標),可以使用下列條件類型:
以篩選器為基礎的指標條件
MetricAbsence 和 MetricThreshold 條件會使用監控篩選器,選取要監控的時間序列資料。條件結構中的其他欄位則指定如何篩選、分組及匯總資料。如要進一步瞭解這些概念,請參閱「篩選和匯總:操控時間序列」。
如果使用 MetricAbsence 條件類型,則可建立只有在所有時間序列都不存在時,才符合的條件。這項條件會使用 aggregations 參數,將多個時間序列匯總為單一時間序列。詳情請參閱 API 說明文件中的 MetricAbsence 參考資料。
指標缺失警告政策要求先前已寫入部分資料。詳情請參閱「建立指標缺失警告政策」。
如要根據預測值接收通知,請將警告政策設為使用 MetricThreshold 條件類型,並設定 forecastOptions 欄位。如果未設定這個欄位,系統會將測量資料與門檻進行比較。不過,如果設定這個欄位,系統會將預測資料與門檻進行比較。詳情請參閱「建立預測指標值警告政策」。
以 PromQL 為基礎的指標條件
PrometheusQueryLanguageCondition 條件會使用 Prometheus 查詢語言 (PromQL) 查詢,選取及操控要監控的時間序列資料。條件可以計算指標比率、評估指標比較結果等。
如果使用 PrometheusQueryLanguageCondition 條件,則該條件必須是警告政策中的唯一條件。詳情請參閱「使用 PromQL 的警告政策」。
比率警告觸發條件
您可以建立指標門檻警告政策,監控兩項指標的比率。您可以使用 MetricThreshold 或 PrometheusQueryLanguageCondition 條件類型建立這些政策。您也可以直接在 Google Cloud 控制台中使用 PromQL。您無法使用建立門檻條件的圖形介面,建立或管理比率條件。
建議您使用 PromQL 建立以比率為基礎的警告政策。相較於使用 MetricTheshold 條件類型和 Monitoring 篩選器,PromQL 可讓您建構更強大、更靈活的查詢。例如,使用 PrometheusQueryLanguageCondition 條件,您可以計算測量指標與差異指標的比率。
如果使用 MetricThreshold 條件,比率的分子和分母必須具有相同的 MetricKind。如需指標及其屬性的清單,請參閱「指標清單」。
一般來說,最好使用標籤值,根據為單一指標類型收集的時間序列來計算比率。由於取樣週期和對齊時間範圍不同,因此根據兩種不同指標類型計算的比率可能會出現異常。
舉例來說,假設您有兩種不同的指標類型:RPC 總數和 RPC 錯誤數,而您想計算錯誤數 RPC 與總 RPC 的比率。不成功的 RPC 會計入這兩種指標類型的時間序列。因此,在對齊時間序列時,失敗的 RPC 可能不會出現在兩個時間序列的相同對齊時間間隔中。造成這種差異的原因有很多,包括:
- 由於有兩個不同的時間序列記錄同一個事件,因此有兩個基礎計數器值實作收集,且不會以原子方式更新。
- 取樣率可能不同。如果時間序列對齊至共同週期,則單一事件的計數可能會出現在不同指標時間序列的相鄰對齊間隔中。
對應對齊間隔中的值數量差異,可能會導致無意義的 error/total 比率值,例如 1/0 或 2/1。
較大數字的比率較不可能產生無意義的值。您可以透過匯總取得較大的數字,方法是使用比取樣週期更長的對齊視窗,或將特定標籤的資料分組。這些技術可盡量減少特定區間內點數微小差異的影響。也就是說,如果一個區間內的預期點數為 3,則兩點的差距會比預期點數為 300 時更顯著。
如果您使用的是內建指標類型,則可能必須計算指標類型的比率,才能取得所需的值。
如果您設計的自訂指標可能會在兩個不同的指標中計算相同的事物 (例如傳回錯誤狀態的 RPC),請考慮改用單一指標,其中每個計數只包含一次。舉例來說,假設您要計算 RPC 數量,並追蹤失敗 RPC 與所有 RPC 的比率。為解決這個問題,請建立單一指標類型來計算 RPC,並使用標籤記錄叫用狀態,包括「OK」狀態。接著,系統會更新該案例的單一計數器,記錄每個狀態值、錯誤或「OK」。
記錄警告政策的條件
如要建立記錄式警告政策,在記錄項目中出現符合篩選條件的訊息時通知您,請使用 LogMatch 條件類型。如果使用 LogMatch 條件,則警告政策中只能有這項條件。
請勿嘗試將 LogMatch 條件類型與記錄指標搭配使用。監控記錄指標的警告政策是以指標為基礎的政策。如要進一步瞭解如何選擇監控記錄指標或記錄項目的警告政策,請參閱「監控記錄」。
「透過 API 管理警告政策」文件範例中使用的警告政策是以指標為基礎,但原則與以記錄為基礎的警告政策相同。如要瞭解記錄警告政策,請參閱 Cloud Logging 說明文件中的「使用 Monitoring API 建立記錄警告政策」。
如何將警告政策與 App Hub 應用程式建立關聯
Google Cloud 會生成資訊主頁,協助您監控 App Hub 應用程式。這些資訊主頁會顯示應用程式的記錄和指標資料,以及應用程式中的服務和工作負載等資訊。如果警告政策與應用程式的服務或工作負載相關聯,這些資訊主頁也會顯示警告政策和相關警告。如要進一步瞭解 Application Monitoring,請參閱「查看應用程式遙測資料」。
如要將警告政策與 App Hub 應用程式建立關聯,請在政策中附加含有下列鍵的標籤:
apphub_application_locationapphub_application_idapphub_service_id或apphub_workload_id
userLabels 區段可能如下所示:
"userLabels": {
"apphub_service_id": "my-service-id",
"apphub_application_location": "my-app-location",
"apphub_application_id": "my-app"
},
事前準備
在針對 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 遷移警告規則和接收器」。
每項警告政策都屬於指標範圍的限定範圍專案。每個專案最多可包含 2,000 項政策。如果是 API 呼叫,您必須提供「專案 ID」,並使用指標範圍的範圍專案 ID 做為值。在這些範例中,指標範圍的範圍專案 ID 為 a-gcp-project。
下列範例說明如何建立警告政策,但不會說明如何建立描述警告政策的 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 範例都不包含這些欄位,但如果在利用這些欄位建立政策之後擷取政策,這些欄位會顯示出來。
設定指標警告政策的重複通知
根據預設,以指標為準的警告政策會在警告觸發時,向每個通知管道傳送一則通知。不過,您可以變更預設行為,並設定警告政策,將通知重新傳送至警告政策的所有或部分通知管道。系統會針對狀態為「已開啟」或「已確認」的警告,重複傳送通知。這些通知之間的間隔必須至少為 30 分鐘,且不得超過 24 小時 (以秒為單位)。
如要設定重複通知,請在警告政策的設定中,新增包含至少一個 NotificationChannelStrategy 物件的 AlertStrategy 物件。NotificationChannelStrategy 物件有兩個欄位:
renotifyInterval:重複通知之間的間隔時間,以秒為單位。如果在警告政策的警告開啟時變更
renotifyInterval欄位的值,會發生下列情況:- 警告政策會針對警告傳送另一則通知。
- 警告政策會重新計算間隔時間。
notificationChannelNames:通知管道資源名稱的陣列,格式為projects/PROJECT_ID/notificationChannels/CHANNEL_ID的字串,其中 CHANNEL_ID 是數值。如要瞭解如何擷取頻道 ID,請參閱「列出專案中的通知管道」。
舉例來說,下列 JSON 範例顯示的警告策略,設定為每 1800 秒 (30 分鐘) 向一個通知管道傳送重複通知:
"alertStrategy": {
"notificationChannelStrategy": [
{
"notificationChannelNames": [
"projects/PROJECT_ID/notificationChannels/CHANNEL_ID"
],
"renotifyInterval": "1800s"
}
]
}
如要暫時停止重複通知,請建立延後。如要避免重複通知,請使用 API 編輯警告政策,並移除 NotificationChannelStrategy 物件。