本頁面由 Cloud Translation API 翻譯而成。

建立以 PromQL 為基礎的快訊政策 (API)

本頁面說明如何使用 Cloud Monitoring API，建立以 PromQL 為基礎的快訊政策。您可以在警報政策中使用 PromQL 查詢，透過比率、動態閾值和指標評估等功能建立複雜條件。

如果您在 Cloud Monitoring 以外的 Prometheus 環境中工作，且有 Prometheus 快訊規則，則可以使用 Google Cloud CLI 將這些規則遷移至 Monitoring 中以 PromQL 為基礎的快訊政策。詳情請參閱「從 Prometheus 遷移快訊規則和接收者」。

使用 PromQL 查詢建立快訊政策

您可以使用 alertPolicies.create 方法，以程式輔助方式建立快訊政策。

建立以 PromQL 為基礎的警告政策與其他警告政策的唯一差異，在於Condition 類型必須為 PrometheusQueryLanguageCondition。您可以使用 PromQL 定義快訊政策。

以下顯示警告政策條件的 PromQL 查詢，該條件使用 kube-state 匯出工具的指標，找出容器在過去 30 分鐘內重新啟動的次數：

rate(kube_pod_container_status_restarts[30m]) * 1800 > 1

建構快訊政策

如要建立以 PromQL 為基礎的快訊政策，請使用AlertPolicy 條件類型 PrometheusQueryLanguageCondition。 PrometheusQueryLanguageCondition 的結構如下：

{
  "query": string,
  "duration": string,
  "evaluationInterval": string,
  "labels": {string: string},
  "ruleGroup": string,
  "alertRule": string
}

PrometheusQueryLanguageCondition 欄位的定義如下：

query：要評估的 PromQL 運算式。相當於標準 Prometheus 快訊規則中的 expr 欄位。
duration：指定查詢每次評估必須產生 true 值，才能符合快訊政策條件的時間長度。值必須是以秒為單位的分鐘數，例如 600s 代表 10 分鐘。詳情請參閱「以指標為基礎的快訊政策行為」。
evaluationInterval：PromQL 評估查詢的時間間隔 (以秒為單位)。預設值為 30 秒。如果 PrometheusQueryLanguageCondition 是透過遷移 Prometheus 警報規則建立，則這個值來自包含 Prometheus 警報規則的 Prometheus 規則群組。

注意： 由 PromQL 快訊政策建立的事件不會遵循快訊政策的自動關閉時間。而是會在最後一次符合條件後，經過一段設定時間後自動關閉事件。這個時間是 270 秒與條件評估間隔的兩倍，取兩者中較大的值。
labels：在 PromQL 運算式結果中新增或覆寫標籤的選用方式。
ruleGroup：如果警報政策是從 Prometheus 設定檔遷移而來，這個欄位會包含 Prometheus 設定檔中規則群組的 name 欄位值。在 Cloud Monitoring API 中建立 PromQL 快訊政策時，這個欄位為選填。
alertRule：如果警報政策是從 Prometheus 設定檔遷移而來，這個欄位會包含 Prometheus 設定檔中警報規則的 alert 欄位值。在 Cloud Monitoring API 中建立 PromQL 快訊政策時，這個欄位為選填。

舉例來說，下列條件會使用 PromQL 查詢，找出容器在過去 30 分鐘內重新啟動的次數：

"conditionPrometheusQueryLanguage": {
  "query": "rate(kube_pod_container_status_restarts[30m]) * 1800 > 1",
  "duration": "600s",
  evaluationInterval: "60s",
  "alertRule": "ContainerRestartCount",
  "labels": {
    "action_required":"true",
    "severity":"critical/warning/info"}
}

在條件中，將這個結構做為 conditionPrometheusQueryLanguage 欄位的值，而條件會嵌入警報政策結構中。如要進一步瞭解這些結構，請參閱 AlertPolicy。

以下顯示完整的政策，其中包含 JSON 格式的PrometheusQueryLanguageCondition條件：

{
  "displayName": "Container Restarts",
  "documentation": {
    "content": "Pod ${resource.label.namespace_name}/${resource.label.pod_name} has restarted more than once during the last 30 minutes.",
    "mimeType": "text/markdown",
    "subject": "Container ${resource.label.container_name} in Pod ${resource.label.namespace_name}/${resource.label.pod_name} has restarted more than once during the last 30 minutes."
  },
  "userLabels": {},
  "conditions": [
    {
      "displayName": "Container has restarted",
      "conditionPrometheusQueryLanguage": {
        "query": "rate(kubernetes_io:container_restart_count[30m]) * 1800",
        "duration": "600s",
        evaluationInterval: "60s",
        "alertRule": "ContainerRestart",
        "labels": {
          "action_required":"true",
          "severity":"critical/warning/info"}
      }
    }
  ],
  "combiner": "OR",
  "enabled": true
}

建立快訊政策

如要建立快訊政策，請將快訊政策 JSON 放入名為 POLICY_NAME.json 的檔案，然後執行下列指令：

curl -d @POLICY_NAME.json -H "Authorization: Bearer $TOKEN"
-H 'Content-Type: application/json'
-X POST https://monitoring.googleapis.com/v3/projects/${PROJECT}/alertPolicies

如要進一步瞭解快訊政策的 Monitoring API，請參閱「由 API 管理快訊政策」一文。

如要進一步瞭解如何使用 curl，請參閱「叫用 curl」。

停用指標存在性檢查

建立以 PromQL 為基礎的快訊政策時， Google Cloud會執行驗證，確保條件中參照的指標已存在於 Monitoring 中。不過，如果需要在指標存在前建立快訊政策，可以覆寫這項驗證。舉例來說，您可能會使用自動化功能建立新專案，並搭配一組預先定義的標準快訊政策。如果未停用驗證，系統會等到建立基礎指標後，才會建立快訊政策。

如要停用指標存在性檢查，請將欄位 "disableMetricValidation": true 新增至 PrometheusQueryLanguageCondition：

{
  "query": string,
  "duration": string,
  "evaluationInterval": string,
  "labels": {string: string},
  "ruleGroup": string,
  "disableMetricValidation": true,
  "alertRule": string
}

如果快訊政策的條件參照不存在的指標，條件仍會依評估間隔執行。不過，查詢結果一律為空白。基礎指標存在後，查詢就會傳回資料。

使用 Terraform

如要瞭解如何使用 Terraform 設定以 PromQL 為基礎的快訊政策，請參閱 google_monitoring_alert_policy Terraform 登錄檔的 condition_prometheus_query_language 區段。

如要瞭解如何搭配使用 Google Cloud 與 Terraform，請參閱「Terraform with Google Cloud」。

叫用「`curl`」

每次叫用 curl 時，都會包含一組引數，後接 API 資源的網址。常見的引數包括專案 ID 和驗證權杖。 Google Cloud 這些值在此以 PROJECT_ID 和 TOKEN 環境變數表示。

您可能也必須指定其他引數，例如指定 HTTP 要求的類型 (例如 -X DELETE)。預設要求為 GET，因此範例不會指定這項引數。

每次呼叫 curl 時，一般結構如下：

curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

如要使用 curl，您必須指定專案 ID 和存取權杖。為減少輸入內容和錯誤，您可以將這些內容放入環境變數，然後以這種方式傳遞至 curl。

如要設定這些變數，請執行下列操作：

建立環境變數，用來保存指標範圍的範圍界定專案 ID。這些步驟會呼叫變數 PROJECT_ID：
```
PROJECT_ID=a-sample-project
```
驗證 Google Cloud CLI：
```
gcloud auth login
```
(選用步驟) 為避免每次執行 gcloud 指令時都必須指定專案 ID，請使用 gcloud CLI 將專案 ID 設為預設值：
```
gcloud config set project ${PROJECT_ID}
```
建立授權權杖，並擷取至環境變數中。這些步驟會呼叫變數 TOKEN：
```
TOKEN=`gcloud auth print-access-token`
```
您必須定期更新存取權杖。如果原本可用的指令突然回報您未通過驗證，請重新發出這個指令。
如要確認您已取得存取權杖，請回應 TOKEN 變數：
```
echo ${TOKEN}
ya29.GluiBj8o....
```