本頁面由 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 與 Google Cloud」。

叫用 `curl`

每個 curl 叫用都包含一組引數，後面接著 API 資源的網址。常見的引數包括 Google Cloud 專案 ID 和驗證權杖。這些值會以 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....
```