JSON でのサンプル ポリシー

このドキュメントでは、アラート ポリシーのサンプルについて説明します。サンプルは JSON で記述され、モニタリング フィルタを使用します。モニタリング フィルタまたは Monitoring Query Language(MQL)を使用してポリシーを定義するかどうかにかかわらず、JSON または YAML のいずれかでポリシーを作成できます。Google Cloud CLI では JSON と YAML の両方の読み取り、書き込みが可能ですが、REST API では JSON の読み取りができます。

MQL を使用するアラート ポリシーのサンプルについては、次のドキュメントをご覧ください。

アラート ポリシー フィールドの構成方法については、次をご覧ください。

既存のポリシーの YAML を生成する

既存のアラート ポリシーの YAML 表現を生成するには、gcloud alpha monitoring policies list コマンドを使用してポリシーを一覧表示し、gcloud alpha monitoring policies describe コマンドを使用してポリシーを印刷します。

既存の通知チャネルの YAML 表現を生成するには、gcloud alpha monitoring channels list コマンドを使用してチャネルを一覧表示し、gcloud alpha monitoring channels describe コマンドを入力して、チャネル構成を印刷します。

Google Cloud CLI コマンドに --format フラグを含めない場合、両方の gcloud ... describe コマンドでデフォルトで YAML 形式が使用されます。

たとえば、次の gcloud alpha monitoring policies describe コマンドは、projects/a-gcp-project/alertPolicies/12669073143329903307 という名前の単一のポリシーを取得し、リダイレクト(>)が出力を test-policy.yaml ファイルにコピーします。

gcloud alpha monitoring policies describe projects/a-gcp-project/alertPolicies/12669073143329903307 > test-policy.yaml

既存のポリシー用の JSON を生成する

既存のアラート ポリシーと通知チャネルを JSON 形式で作成するには、次のいずれかを行います。

  • 既存のポリシー用の YAML の生成で説明されている gcloud CLI コマンドに --format="json" フラグを追加します。たとえば、ポリシーを一覧表示するには、次のコマンドを実行します。

    gcloud alpha monitoring policies list --format=json

  • 各 API メソッドのリファレンス ページで API Explorer ウィジェットを使用する。

    詳細については、API Explorer をご覧ください。

ポリシーのサンプル

バックアップ/リストアの例に示すように、保存されたポリシーを使用して、ポリシーの新しいコピーを作成できます。

また、あるプロジェクトに保存されたポリシーを使用して、別のプロジェクトで新規または類似のポリシーを作成できます。ただし、保存したポリシーのコピーでは、最初に次の変更を行う必要があります。

  • 通知チャネルから次のフィールドを削除します。
    • name
    • verificationStatus
  • アラート ポリシーでチャネルを参照する前に通知チャネルを作成します(新しいチャネル ID が必要です)。
  • 再作成するアラート ポリシーから次のフィールドを削除します。
    • name
    • condition.name
    • creationRecord
    • mutationRecord

このドキュメントのポリシーは、Google Cloud Console で「変化率ポリシー」などのモニタリングで使用されているのと同じ用語を使用して編成され、2 種類の条件があります。

  • しきい値条件。UI で言及されているほぼすべてのポリシータイプがしきい値条件のバリアントです
  • 不在条件

以下のサンプルでは、これらの条件は conditionThresholdconditionAbsent に対応しています。詳細については、Condition のリファレンス ページをご覧ください。

これらのポリシーの多くは、Google Cloud Console を使用して手動で作成できますが、一部はMonitoring API を使用しないと作成できないものもあります。詳細については、アラートポリシーの作成またはポリシーの作成(API) をご覧ください。

指標しきい値ポリシー

指標しきい値ポリシーは、ある値が所定の境界を超えたことを検出するポリシーです。しきい値ポリシーによっていずれかの条件が重要なポイントに近づいていることが通知されるため、必要な対策を講じることができます。たとえば、使用可能なディスク領域が合計ディスク領域の 10 パーセント未満になると、システムのディスク領域が不足する可能性があります。

次のポリシーは、VM のグループの正常性の指標として平均 CPU 使用率を使用します。プロジェクト内の VM の平均 CPU 使用率が 60 秒間隔で測定され、15 分(900 秒)にわたって 90 パーセントの使用率のしきい値を超えた場合にアラートが作成されます。

{
    "displayName": "Very high CPU usage",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "CPU usage is extremely high",
            "conditionThreshold": {
                "aggregations": [
                    {
                        "alignmentPeriod": "60s",
                        "crossSeriesReducer": "REDUCE_MEAN",
                        "groupByFields": [
                            "project"
                        ],
                        "perSeriesAligner": "ALIGN_MAX"
                    }
                ],
                "comparison": "COMPARISON_GT",
                "duration": "900s",
                "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
                          AND resource.type=\"gce_instance\"",
                "thresholdValue": 0.9,
                "trigger": {
                    "count": 1
                }
            }
        }
    ],
}

指標の不在ポリシー

指標の不在ポリシーは、指定した期間に、指標にデータが書き込まれないとトリガーされます。

これを検証する方法として、カスタム指標を作成する方法があります。

以下はカスタム指標の記述子の例です(この指標は API Explorer を使用して作成できます)。

{
  "description": "Number of times the pipeline has run",
  "displayName": "Pipeline runs",
  "metricKind": "GAUGE",
  "type": "custom.googleapis.com/pipeline_runs",
  "labels": [
    {
      "description": "The name of the pipeline",
      "key": "pipeline_name",
      "valueType": "STRING"
    },
  ],
  "unit": "1",
  "valueType": "INT64"
}

詳しくは、ユーザー定義の指標の概要をご覧ください。

この指標へのデータの書き込みが約 1 時間停止すると、次のアラート ポリシーがトリガーされます。つまり、1 時間ごとのパイプラインが実行できなかったということです。ここで使用される条件は conditionAbsent です。

{
    "displayName": "Data ingestion functioning",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "Hourly pipeline is up",
            "conditionAbsent": {
                "duration": "3900s",
                "filter": "resource.type=\"global\"
                          AND metric.type=\"custom.googleapis.com/pipeline_runs\"
                          AND metric.label.pipeline_name=\"hourly\"",
            }
        }
    ],
}

予測ポリシー

予測条件は、期間内で時系列に対して行われたすべての予測が同じである場合にトリガーされ、時系列に違反すると予測ホライズン内のしきい値を予測します。

予測条件は、予測を使用するように構成された指標しきい値の条件です。次のサンプルに示すように、これらの条件には、予測を有効にし、予測ホライズンを指定する forecastOptions フィールドが含まれています。次のサンプルでは、予測ホライズンが最小値である 1 時間に設定されています。

{
    "displayName": "NFS free bytes alert",
    "combiner": "OR",
    "conditions": [
      {
        "displayName": "Filestore Instance - Free disk space percent",
        "conditionThreshold": {
          "aggregations": [
            {
              "alignmentPeriod": "300s",
              "perSeriesAligner": "ALIGN_MEAN"
            }
          ],
          "comparison": "COMPARISON_LT",
          "duration": "900s",
          "filter": "resource.type = \"filestore_instance\" AND metric.type = \"file.googleapis.com/nfs/server/free_bytes_percent\"",
          "forecastOptions": {
            "forecastHorizon": "3600s"
          },
          "thresholdValue": 20,
          "trigger": {
            "count": 1
          }
        }
      }
    ],
}

変化率ポリシー

変化率条件は、時系列の値がしきい値で指定された割合以上増加または減少するとトリガーされます。このタイプの条件を作成すると、しきい値との比較する前に、変化率の計算が時系列に適用されます。

この条件では、過去 10 分間の指標の値の平均が、期間時間枠の直前に測定された 10 分間の平均値と比較されます。「指標の変化率」条件で使用される 10 分間のルックバック時間枠は固定値であり、変更できません。ただし、条件を作成するときに期間時間枠を指定できます。

このポリシーは、CPU 使用率が急上昇するとアラートをトリガーします。

{
  "displayName": "High CPU rate of change",
  "combiner": "OR",
  "conditions": [
    {
      "displayName": "CPU usage is increasing at a high rate",
      "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
         }
      }
    }
  ],
}

グループ集計ポリシー

このポリシーは、Google Kubernetes Engine クラスタ全体の平均 CPU 使用率がしきい値を超えるとアラートをトリガーします。

{
    "displayName": "CPU utilization across GKE cluster exceeds 10 percent",
    "combiner": "OR",
    "conditions": [
         {
            "displayName": "Group Aggregate Threshold across All Instances in Group GKE cluster",
            "conditionThreshold": {
                "filter": "group.id=\"3691870619975147604\" AND metric.type=\"compute.googleapis.com/instance/cpu/utilization\" AND resource.type=\"gce_instance\"",
                "comparison": "COMPARISON_GT",
                "thresholdValue": 0.1,
                "duration": "300s",
                "trigger": {
                    "count": 1
                },
                "aggregations": [
                    {
                        "alignmentPeriod": "60s",
                        "perSeriesAligner": "ALIGN_MEAN",
                        "crossSeriesReducer": "REDUCE_MEAN",
                        "groupByFields": [
                              "project"
                        ]
                    },
                    {
                        "alignmentPeriod": "60s",
                        "perSeriesAligner": "ALIGN_SUM",
                        "crossSeriesReducer": "REDUCE_MEAN"
                    }
                ]
            },
        }
    ],
}

このポリシーでは、次のグループの存在を前提としています。

    {
        "name": "projects/a-gcp-project/groups/3691870619975147604",
        "displayName": "GKE cluster",
        "filter": "resource.metadata.name=starts_with(\"gke-kuber-cluster-default-pool-6fe301a0-\")"
    }

ユーザーのグループと同等のフィールドを識別するには、project.groups.list のリファレンス ページのAPI Explorer を使用してグループの詳細を一覧表示します。

稼働時間チェック ポリシー

Monitoring Overview ページに稼働時間チェックのステータスが表示されます。稼働時間のチェックに失敗した場合はアラート ポリシーを使用して直接通知を受け取ることができます。

たとえば、次の JSON は、Google Cloud サイトでの HTTPS 稼働時間チェックを記述します。5 分ごとに稼働状況をチェックします。

稼働時間チェックは Google Cloud Console で作成されたものです。この JSON 表現は、Monitoring API を使用してプロジェクトの稼働時間チェックの一覧を取得して作成されました(uptimeCheckConfigs.list を参照)。Monitoring API を使用して稼働時間チェックを作成することもできます。

{
    "name": "projects/a-gcp-project/uptimeCheckConfigs/uptime-check-for-google-cloud-site",
    "displayName": "Uptime check for Google Cloud site",
    "monitoredResource": {
        "type": "uptime_url",
        "labels": {
            "host": "cloud.google.com"
      }
    },
    "httpCheck": {
        "path": "/index.html",
        "useSsl": true,
        "port": 443,
        "authInfo": {}
    },
    "period": "300s",
    "timeout": "10s",
    "contentMatchers": [
        {}
    ]
}

稼働時間チェックのアラート ポリシーを作成するには、その UPTIME_CHECK_ID ごとの稼働時間チェックを確認してください。この ID は、チェックが作成されるときに設定されます。name フィールドの最後のコンポーネントとして表示され、設定サマリーの Check ID として UI でも確認できます。Monitoring API を使用している場合は、uptimeCheckConfigs.create メソッドによって ID が返されます。

この ID は displayName から派生します。この場合は、UI に設定されたものです。稼働時間のチェックを一覧表示して name 値を調べることで、検証できます。

前述の稼働時間チェックの ID は uptime-check-for-google-cloud-site です。

稼働時間チェックが失敗した場合や、Google Cloud サイトの SSL 証明書が 15 日以内に失効する場合は、下記のアラートポリシーがトリガーされます。いずれかの条件が発生した場合、アラート ポリシーは指定された通知チャネルに通知を送信します。

{
    "displayName": "Google Cloud site uptime failure",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "Failure of uptime check_id uptime-check-for-google-cloud-site",
            "conditionThreshold": {
                "aggregations": [
                    {
                        "alignmentPeriod": "1200s",
                        "perSeriesAligner": "ALIGN_NEXT_OLDER",
                        "crossSeriesReducer": "REDUCE_COUNT_FALSE",
                        "groupByFields": [ "resource.label.*" ]
                    }
                ],
                "comparison": "COMPARISON_GT",
                "duration": "600s",
                "filter": "metric.type=\"monitoring.googleapis.com/uptime_check/check_passed\"
                          AND metric.label.check_id=\"uptime-check-for-google-cloud-site\"
                          AND resource.type=\"uptime_url\"",
                "thresholdValue": 1,
                "trigger": {
                    "count": 1
                }
            }
        },
        {
            "displayName": "SSL Certificate for google-cloud-site expiring soon",
            "conditionThreshold": {
                "aggregations": [
                    {
                        "alignmentPeriod": "1200s",
                        "perSeriesAligner": "ALIGN_NEXT_OLDER",
                        "crossSeriesReducer": "REDUCE_MEAN",
                        "groupByFields": [ "resource.label.*" ]
                    }
                ],
                "comparison": "COMPARISON_LT",
                "duration": "600s",
                "filter": "metric.type=\"monitoring.googleapis.com/uptime_check/time_until_ssl_cert_expires\"
                          AND metric.label.check_id=\"uptime-check-for-google-cloud-site\"
                          AND resource.type=\"uptime_url\"",
                "thresholdValue": 15,
                "trigger": {
                    "count": 1
                }
            }
        }
    ],
}

アラート ポリシーのフィルタは、タイプとラベルでモニタリング対象の指標を指定します。指標のタイプは monitoring.googleapis.com/uptime_check/check_passedmonitoring.googleapis.com/uptime_check/time_until_ssl_cert_expires です。指標のラベルは、モニタリング対象の特定の稼働時間チェックを表します。 この例では、ラベル フィールド check_id に稼働時間チェック ID が含まれています。

AND metric.label.check_id=\"uptime-check-for-google-cloud-site\"

詳細については、モニタリング フィルタをご覧ください。

プロセスの状態ポリシー

プロセスの状態ポリシーは、パターンと一致するプロセス数がしきい値を超えると、通知を送信します。これは、たとえば、プロセスの実行が停止したことを伝えるのに使用できます。

このポリシーは、ユーザー www として実行している文字列 nginx に一致するプロセスが 5 分以上使用できなかった場合に、指定された通知チャネルに通知を送信します。

{
    "displayName": "Server health",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "Process 'nginx' is not running",
            "conditionThreshold": {
                "filter": "select_process_count(\"has_substring(\\\"nginx\\\")\", \"www\") AND resource.type=\"gce_instance\"",
                "comparison": "COMPARISON_LT",
                "thresholdValue": 1,
                "duration": "300s"
            }
        }
    ],
}

詳細については、プロセスの状態をご覧ください。

指標率

Monitoring Query Language(MQL)を使用して比率ベースのアラート ポリシーを作成することをおすすめします。Cloud Monitoring API は一部のフィルタベースの比率の構成をサポートしていますが、MQL ではより柔軟で堅牢なソリューションが提供されています。

このセクションでは、フィルタベースの比率について説明します。API を使用すると、2 つの関連する指標の比率を計算し、その比率がしきい値を超えると起動するポリシーを作成して表示できます。関連する指標は同じ MetricKind である必要があります。たとえば、両方の指標がゲージ指標である場合、比率ベースのアラート ポリシーを作成できます。 指標タイプの MetricKind を確認するには、指標リストをご覧ください。

比率条件は単純なしきい値条件のバリアントです。比率ポリシーの条件では通常、比率の分子として機能する filter と、比率の分母として機能する denominatorFilter という 2 つのフィルタが使用されます。

両方のフィルタからの時系列は、値の比率の計算が意味を持つものになるように、同じ方法で集計する必要があります。アラート ポリシーは、指定された期間、2 つのフィルタの比率がしきい値を超えた場合にトリガーされます。

次のセクションでは、すべての HTTP レスポンスに対する HTTP エラー応答の割合を監視する際のアラート ポリシーについて、その設定方法を説明します。

HTTP エラーの比率

次のポリシーは、HTTP エラー レスポンスの数とすべての HTTP 応答の数の比率に基づいたしきい値条件を作成します。

{
    "displayName": "HTTP error count exceeds 50 percent for App Engine apps",
    "combiner": "OR",
    "conditions": [
        {
            "displayName": "Ratio: HTTP 500s error-response counts / All HTTP response counts",
            "conditionThreshold": {
                 "filter": "metric.label.response_code>=\"500\" AND
                            metric.label.response_code<\"600\" AND
                            metric.type=\"appengine.googleapis.com/http/server/response_count\" AND
                            project=\"a-gcp-project\" AND
                            resource.type=\"gae_app\"",
                 "aggregations": [
                    {
                        "alignmentPeriod": "300s",
                        "crossSeriesReducer": "REDUCE_SUM",
                        "groupByFields": [
                          "project",
                          "resource.label.module_id",
                          "resource.label.version_id"
                        ],
                        "perSeriesAligner": "ALIGN_DELTA"
                    }
                ],
                "denominatorFilter": "metric.type=\"appengine.googleapis.com/http/server/response_count\" AND
                                      project=\"a-gcp-project\" AND
                                      resource.type=\"gae_app\"",
                "denominatorAggregations": [
                   {
                      "alignmentPeriod": "300s",
                      "crossSeriesReducer": "REDUCE_SUM",
                      "groupByFields": [
                        "project",
                        "resource.label.module_id",
                        "resource.label.version_id"
                       ],
                      "perSeriesAligner": "ALIGN_DELTA",
                    }
                ],
                "comparison": "COMPARISON_GT",
                "thresholdValue": 0.5,
                "duration": "0s",
                "trigger": {
                    "count": 1
                }
            }
        }
    ]
}

指標とリソースタイプ

このポリシーの指標タイプは appengine.googleapis.com/http/server/response_count であり、次の 2 つのラベルがあります。

  • response_code。リクエストの HTTP ステータス コードを表す 64 ビットの整数。このポリシーは、このラベルの時系列データをフィルタリングします。これにより、次を判別することができます。
    • 受信したレスポンスの数。
    • 受信したエラー レスポンスの数。
    • すべてのレスポンスに対するエラー レスポンスの割合。
  • loading。リクエストがロードされたかどうかを示すブール値。loading ラベルはこのアラート ポリシーには関係ありません。

アラート ポリシーは、App Engine アプリからのレスポンス データ、つまりモニタリング対象リソースタイプ gae_app からのデータに関連しています。このモニタリング対象リソースには、次の 3 つのラベルがあります。

  • project_id。Google Cloud プロジェクトの ID。
  • module_id。アプリ内のサービスまたはモジュールの名前。
  • version_id。アプリのバージョン。

これらの指標とモニタリング対象リソースのタイプについては、指標リストの App Engine の指標とモニタリング対象リソースリストの gae_app エントリをご覧ください。

このポリシーの機能

このポリシーは、すべてのレスポンスに対するエラー レスポンスの割合を計算します。ポリシーは、5 分間のアライメント期間を超えて、比率が 50%を超えると(つまり、比率が 0.5 よりも大きくなると)、アラート通知をトリガーします。

このポリシーは、各フィルタの時系列をそれらのラベルの値でグループ化して、条件に違反するアプリのモジュールとバージョンを取得します。

  • 条件内のフィルタは、App Engine アプリからの HTTP レスポンスを調べ、エラー範囲 5xx 内のレスポンスを選択します。これは比率の分子です。
  • 条件内の分母フィルタは、App Engine アプリからのすべての HTTP レスポンスを調べます。

ポリシーは即時にアラート通知をトリガーします。条件に対する許容期間は 0 秒です。このポリシーはトリガー カウント 1 を使用します。これは、アラート通知をトリガーする条件に違反する必要のある時系列の数です。サービスが 1 個の App Engine アプリの場合、トリガーは 1 が適しています。20 個のサービスを持つアプリの場合に、3 個以上のサービスが条件に違反するとアラートがトリガーされるようにするには、トリガー カウント 3 を使用します。

比率を設定する

分子と分母のフィルタは、分子の条件フィルタが誤差範囲のレスポンス コードと一致し、分母の条件フィルタがすべてのレスポンス コードと一致する点を除いてまったく同じです。次の句は、分子条件にのみ表示されます。

      metric.label.response_code>=\"500\" AND
      metric.label.response_code<\"600\"

それ以外は、分子フィルタと分母フィルタは同じです。

各フィルタで選択された時系列は、比率の計算が有効になるように、同じ方法で集計する必要があります。ラベルの値の組み合わせごとに時系列が異なるため、フィルタによって複数の時系列が収集されることがあります。このポリシーは指定されたリソースラベルで時系列のセットをグループ化し、時系列のセットをグループのセットに分割します。各グループの時系列の一部は分子フィルタに一致します。残りは分母フィルタに一致します。

比率を計算するには、各フィルタに一致する時系列のセットをそれぞれ 1 つの時系列に集計する必要があります。これにより、各グループには分子用と分母用の 2 つの時系列が残ります。次に、各グループの分子と分母の時系列の点の割合を計算できます。

このポリシーでは、両方のフィルタの時系列が次のように集計されます。

  • 各フィルタにより、5 分の間隔で配列された複数の時系列が作成されます。その 5 分の配列間隔で値に対して ALIGN_DELTA を計算して示された値が使用されます。この配置指定子によって、その間隔で一致するレスポンスの数が 64 ビット整数として返されます。

  • 各フィルタ内の時系列は、モジュールとバージョンのリソースラベルの値によってもグループ化されます。したがって、各グループには分子フィルタに一致する時系列と分母フィルタに一致する時系列という整列された 2 セットの時系列が含まれるようになります。

  • 分子フィルタまたは分母フィルタに一致する各グループ内の時系列は、REDUCER_SUM クロス系列削減指定子を使用して個々の時系列に値を合計することで単一の時刻に集計されます。この結果、分子と分母にそれぞれ 1 つの時系列が残り、各時系列によって配置間隔ですべての一致する時系列にわたり、レスポンスの数がレポートされます。

次にポリシーは、各グループを表す分子と分母の時系列に対して、値の比を計算します。比率を得られるようになると、このポリシーは単純な指標しきい値ポリシーになります。