PromQL ベースのアラート ポリシーを作成する（API）

このページでは、Cloud Monitoring API を使用して PromQL ベースのアラート ポリシーを作成する方法について説明します。アラート ポリシーで PromQL クエリを使用すると、比率、動的しきい値、指標評価などの機能を設定した複雑な条件を作成できます。

一般的な情報については、PromQL ベースのアラートの概要をご覧ください。

Cloud Monitoring 外部の Prometheus 環境で作業しており、Prometheus アラートルールを設定している場合は、Google Cloud CLI を使用して、アラートルールを Monitoring の PromQL ベースのアラート ポリシーに移行できます。詳細については、Prometheus からアラートのルールとレシーバーを移行するをご覧ください。

PromQL クエリを使用してアラート ポリシーを作成する

alertPolicies.create メソッドを使用して、アラート ポリシーをプログラムで作成します。

PromQL ベースのアラート ポリシーの作成と他のアラート ポリシーの作成の唯一の違いは、Condition タイプが PrometheusQueryLanguageCondition でなければならないことです。この条件タイプを使用すると、アラート ポリシーを PromQL で定義できます。

kube-state エクスポータの指標を使用して、過去 30 分間にコンテナが再起動された回数を確認するアラート ポリシー条件に対する PromQL クエリを次に示します。

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 ルールグループから取得されます。

  • 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 にすでに存在することを確認します。ただし、指標が存在する前にアラート ポリシーを作成する必要がある場合は、この検証をオーバーライドできます。たとえば、自動化を使用して、事前定義されたアラート ポリシーの標準セットが付属する新しいプロジェクトを作成する場合は、この方法が適しています。検証を無効にしないと、基盤となる指標が作成されるまでアラート ポリシーの作成が失敗します。

指標の存在チェックを無効にするには、PrometheusQueryLanguageCondition に "disableMetricValidation": true フィールドを追加します。

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

アラート ポリシーの条件が存在しない指標を参照している場合、条件は評価間隔に従って実行されます。ただし、クエリ結果は常に空になります。基になる指標が存在すると、クエリはデータを返します。

Terraform を使用

以下を使用して PromQL ベースのアラート ポリシーを構成する手順については、 詳細については、google_monitoring_alert_policy Terraform レジストリのcondition_prometheus_query_language セクションをご覧ください。

Terraform で Google Cloud を使用する際の一般的な情報については、 Google Cloudで Terraform を使用するをご覧ください。

curl の呼び出し

各 curl 呼び出しには一連の引数が含まれ、API リソースの URL がそれに続きます。一般的な引数には、 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 に渡すことができます。

これらの変数を設定するには、次のことを行います。

  1. 指標スコープのスコープ プロジェクト ID を保持する環境変数を作成します。次の手順では、変数 PROJECT_ID を呼び出します。

    PROJECT_ID=a-sample-project

  2. Google Cloud CLI に対して認証を行います。

    gcloud auth login

  3. 省略可。各 gcloud コマンドでのプロジェクト ID の指定を不要にするには、gcloud CLI を使用してプロジェクト ID をデフォルトとして設定します。

    gcloud config set project ${PROJECT_ID}

  4. 認証トークンを作成し、環境変数にキャプチャします。次の手順では、変数 TOKEN を呼び出します。

    TOKEN=`gcloud auth print-access-token`

    アクセス トークンは定期的に更新する必要があります。動作していたコマンドに急に未認証と報告された場合は、このコマンドを再発行します。

  5. アクセス トークンがあることを確認するには、TOKEN 変数をエコーします。

    echo ${TOKEN}
ya29.GluiBj8o....