JSON 格式的示例政策

本文档提供了提醒政策示例。这些示例采用 JSON 编写，并使用 Monitoring 过滤器。无论您是使用 Monitoring 过滤条件还是 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 表示，请执行以下任一操作：

政策示例

如备份/还原示例中所示，您可以使用已保存的政策来创建这些政策的新副本。

您可以使用保存在一个项目中的政策，在另一个项目中创建新政策或类似政策。但是，您必须首先在已保存政策的副本中进行以下更改：

  • 从任何通知渠道中移除以下字段：
    • name
    • verificationStatus
  • 在引用提醒政策中的通知渠道之前先创建通知渠道（您需要新的渠道标识符）。
  • 从您正在重新创建的任何提醒政策中移除以下字段：
    • name
    • condition.name
    • creationRecord
    • mutationRecord

本文档中的政策按照 Google Cloud 控制台中的 Monitoring 所用的术语整理，例如“变化率政策”，并且有两种类型的条件：

  • 阈值条件；界面中提到的几乎所有的政策类型都是阈值条件的变体
  • 缺失条件

在以下示例中，这些条件对应于 conditionThreshold 和 conditionAbsent。如需了解详情，请参阅 Condition 参考页面。

您可以使用 Google Cloud 控制台手动创建许多这些政策，但某些政策只能通过 Monitoring API 创建。如需了解详情，请参阅创建提醒政策（界面）或使用 API 创建提醒政策。

指标阈值政策

指标阈值政策用于检测某个值超越预定边界的情况。阈值政策可通知您某些方面已临近关键点，以便您采取行动。例如，当可用磁盘空间低于总磁盘空间的 10% 时，指标阈值政策的条件就会满足。

以下提醒政策使用平均 CPU 使用率作为一组虚拟机运行状况的指示因素。当项目中虚拟机的平均 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 字段定义的时间范围内没有数据写入指标，则满足指标缺失条件。

如需演示这种政策，可采用的一种方法是创建自定义指标。

以下是自定义指标的示例描述符。您可以使用 APIs 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"
}

如需了解详情，请参阅用户定义的指标概览。

如果在大约一个小时内数据停止写入此指标，则系统会满足以下提醒政策中的条件：换句话说，您的每小时流水线未能运行。请注意，这里使用的条件是 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。如果您使用的是 Monitoring API，则 uptimeCheckConfigs.create 方法会返回该 ID。

ID 来源于 displayName，在本示例中，它是在界面中设置的。 可以通过列出正常运行时间检查并查看 name 值来验证 ID。

上述正常运行时间检查的 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\"

如需了解详情，请参阅监控过滤条件。

进程运行状况政策

如果与某一模式匹配的进程数量超过阈值，则进程运行状况政策会向您发出通知。这可通知您关于进程的一些情况，例如某个进程已停止运行。

当与字符串 nginx 匹配的进程（以用户 www 的身份运行）在超过 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，您可以创建一项政策来计算两个相关指标的比率，并在该比率超过阈值时触发。您还可以查看政策。相关指标必须具有相同的 MetricKind。例如，如果两个指标都是增量指标，您可以创建基于比率的提醒政策。要确定指标类型的 MetricKind，请参阅指标列表。

比率条件是指标阈值条件的变体，比率政策中的条件使用两种过滤条件：常规 filter（作为比率的分子）和 denominatorFilter（作为比率的分母）。

两个过滤条件中的时间序列必须以相同的方式聚合，这样计算值的比率才是有意义的。如果过滤条件的比率违反了 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，它有两个标签：

  • response_code 是一个 64 位整数，表示请求的 HTTP 状态代码。此政策根据此标签过滤时间序列数据，因此它可以确定以下各项：
    • 收到的响应数量。
    • 收到的错误响应数量。
    • 错误响应与所有响应的比率。
  • loading 是一个布尔值，用于表明请求是否在加载。loading 标签与此提醒政策无关。

提醒政策会评估来自 App Engine 应用的响应数据，即来自受监控的资源类型为 gae_app 的数据。此受监控的资源有三个标签：

  • 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，即需要违反条件以导致突发事件的时序的数量。对于包含单一服务的 App Engine 应用，trigger 计数为 1 即可。如果您有一个包含 20 项服务的应用，并且您希望在有 3 个或更多服务违反条件时触发突发事件，请使用 3 个 trigger 计数。

设置比率

分子和分母过滤条件完全相同，不同的是，分子中的条件过滤条件与错误范围内的响应代码匹配，分母中的条件过滤条件与所有响应代码匹配。以下子句仅出现在分子条件中：

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

除此之外，分子过滤条件和分母过滤条件是相同的。

每个过滤条件选择的时间序列必须以相同的方式聚合，这样计算的比率才是有意义的。每个过滤条件可能会收集多个时间序列，因为标签的每个值组合都对应一个不同的时间序列。此政策根据指定的资源标签对这组时序进行分组，将这些时序划分成若干组。每个组中的某些时间序列与分子过滤条件匹配；其余的时间序列则与分母过滤条件匹配。

要计算比率，必须将匹配每个过滤条件的一组时间序列聚合为一个时间序列。这样，每个组将剩下两个时序，一个用于分子，一个用于分母。接下来，可以计算每组中分子和分母时间序列中各点的比率。

在此政策中，两个过滤条件的时间序列聚合如下：

  • 每个过滤条件都会创建多个以 5 分钟为间隔进行校准的时序，其中值表示对该 5 分钟校准时间段内的值进行 ALIGN_DELTA 计算的结果。此校准器会将该校准周期内的匹配响应数作为 64 位整数返回。

  • 此外，每个过滤条件中的时间序列还会按模块和版本的资源标签值进行分组，因此每个组都包含两组校准的时间序列，即与分子过滤条件匹配的时间序列以及与分母过滤条件匹配的时间序列。

  • 通过使用 REDUCER_SUM 跨序列缩减器对各时间序列中的值求和，将每个组中与分子或分母过滤条件匹配的时间序列聚合为一个时间序列。这样会得到分子的一个时序和分母的一个时序，每个时序都会报告校准期中所有匹配时序的响应数。

然后，该政策针对代表每个组的分子和分母时间序列计算值的比率。当该比率超过 50% 时，提醒政策的条件就满足了。