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 で言及されているほぼすべてのポリシータイプがしきい値条件のバリアントです
  • 不在条件

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

これらのポリシーの多くは、Google Cloud Console を使用して手動で作成できますが、一部はMonitoring API を使用しないと作成できないものもあります。詳細については、アラートポリシーの作成（UI）または 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
                }
            }
        }
    ],
}

指標の不在ポリシー

指標の不在条件は、duration フィールドで定義された期間内に指標にデータが書き込まれない場合に満たされます。

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

以下はカスタム指標の記述子の例です（この指標は 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\"",
            }
        }
    ],
}

予測ポリシー

予測条件は、次の場合に満たされます。

  • 時系列のすべての予測が、duration フィールドで定義された期間内で同じである。
  • Cloud Monitoring は、時系列が予測ホライズン内でしきい値に違反すると予測します。

予測条件は、予測を使用するように構成された指標しきい値条件です。次のサンプルに示すように、これらの条件には、予測を有効にして予測ホライズンを指定する 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 を使用してグループの詳細を一覧表示します。

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

稼働時間チェックのステータスは [稼働時間チェック] ページに表示されますが、稼働時間チェックが失敗した場合に Cloud Monitoring から通知が送信されるようにアラート ポリシーを構成できます。

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

稼働時間チェックは Google Cloud コンソールで作成されたものです。この 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 日以内に失効する場合は、次のアラート ポリシーの条件が満たされます。いずれかの条件が満たされると、Monitoring は指定された通知チャネルに通知を送信します。

{
    "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_passed と monitoring.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 分以上使用できなかった場合に、Monitoring は指定された通知チャネルに通知を送信します。

{
    "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 つのフィルタが使用されます。

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

次のセクションでは、すべての 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 レスポンスを調べます。

条件が満たされると、Monitoring は新しいインシデントの通知をすぐに送信します。条件の duration フィールドの許容時間範囲は 0 秒です。この条件では、trigger カウントが 1 です。これは、インシデントを発生させるために条件に違反する必要がある時系列の数です。サービスが 1 個の App Engine アプリの場合、trigger のカウントが 1 で問題ありません。20 個のサービスを持つアプリで、3 個以上のサービスが条件に違反した場合にインシデントを発生させる場合は、trigger カウント 3 を使用します。

比率を設定する

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

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

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

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

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

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

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

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

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

次にポリシーは、各グループを表す分子と分母の時系列に対して、値の比を計算します。比率が 50% を超えると、アラート ポリシーの条件が満たされます。