通过 Monitoring API 使用 MQL

本页面介绍如何向 Cloud Monitoring API 提供 Monitoring Query Language (MQL) 查询。

本页面不介绍如何创建 MQL 查询。如需查看一组示例查询，请参阅示例。MQL 参考提供了语言的全面参考。

如需简要了解基于 MQL 的提醒政策，请参阅使用 MQL 的提醒政策。

通过 API 使用 MQL

您可以在 Monitoring API 中的以下位置提供 MQL 查询：

要使用 MQL 选择和处理时间序列数据，请调用 timeSeries.query 方法。如需查看示例，请参阅使用 timeSeries.query。
如需选择和操作图表的时间序列数据，请在调用 dashboards.create 方法时将查询提供给 TimeSeriesQuery 规范。如需查看示例，请参阅构建图表。
要在提醒政策中创建基于 MQL 的条件，请在调用 alertPolicies.create 时使用 MonitoringQueryLanguageCondition 条件类型描述提醒政策的条件。如需查看示例，请参阅创建提醒政策的条件。

使用 `timeSeries.query` 检索数据

要使用 MQL 查询从 API 中检索时间序列数据，请使用 timeSeries.query 方法。

timeSeries.query 方法采用最小结构，如下所示（在 JSON 中）：

{
  "query": string
}

对于 query 字段的值，请在 MQL 中指定一个字符串，如以下简单查询所示：

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m"
}

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | for 1h"
}

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/usage_time | sum | next_older 10m | every 10m"
}

如果您的查询会创建一个未对齐的输出表，则必须在直接调用 API 时使用 within 表操作来提供时长。Metrics Explorer 等图表工具提供默认查询时长。以下 JSON 代码段中的查询适用于 Metrics Explorer 中的 MQL 代码编辑器，但在直接提供给 API 时会失败：

{
   "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10)"
}

通过在上述查询中添加 within 表操作，可以将前一个示例直接提供给 API：

{
   "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10) | within 1h"
}

如需试用 API，您可以使用 timeSeries.query 参考页面上的 API Explorer 工具。如需了解 API Explorer 工具，请参阅 API Explorer。

另一种尝试 API 的方法是将查询放入文本文件中，然后使用 curl 执行查询。以下示例将文件 query.json 中的查询传递给 timeSeries.query 方法：

curl -d @query.json -H "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" -X POST \
https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries:query

如需详细了解如何使用 curl，请参阅调用 curl。

如果成功，查询将返回包含请求的时间序列的表。该表格分为两个部分：

timeSeriesDescriptor 描述了表中的标签键、标签值和数据点。它不包含任何数据；它仅描述数据。
timeSeriesData 包含时间序列描述符中描述的数据。此数据显示为一个对数组。
- 对中的第一项 labelValues 记录时间序列描述符中列出的标签的一组值。
- 第二项 pointData 是值/时间戳对的嵌入式数组，表示使用指定标签值集收集的数据。

响应略微调整了格式，如下所示：

[{
  "timeSeriesTable": {
    "timeSeriesDescriptor": {
      "labelDescriptors": [
        { "key": "resource.project_id" },
        { "key": "resource.zone" },
        { "key": "resource.instance_id" },
        { "key": "metric.instance_name" }
      ],
      "valueDescriptors": [
        {
          "key": "value.utilization",
          "valueType": "DOUBLE",
          "metricKind": "GAUGE"
        }
      ],
      "pointDescriptors": [
        {
          "key": "value.utilization",
          "valueType": "DOUBLE",
          "metricKind": "GAUGE"
        }
      ]
    },
    "timeSeriesData": [
      {
        "labelValues": [
          { "stringValue": "632526624816" },
          { "stringValue": "us-central1-a" },
          { "stringValue": "5106847938297466291" },
          { "stringValue": "gke-kuber-cluster-default-pool-6fe301a0-n8r9" }
        ],
        "pointData": [
          {
            "values": [
              {
                "doubleValue": 0.063896992710942874
              }
            ],
            "timeInterval": {
              "startTime": "1969-12-31T23:59:59.999999Z",
              "endTime": "2020-03-02T20:17:00Z"
            }
          },
          { ... additional value/timestamp pairs ...}
        ]
      },
      { ... additional labelValue/pointData pairs ...},
    ]
  }

构建图表

您可以使用 dashboards.create 方法以编程方式创建信息中心及其包含的图表。

创建基于 MQL 的图表与其他图表的唯一区别是用于填充图表数据集的 TimeSeriesQuery 查询类型。

构建基于 MQL 的图表

对于 MQL 查询，请使用查询作为图表的 DataSet 数组中 timeSeriesQueryLanguage 字符串字段的值。

以下是一个包含 MQL 的简单信息中心定义：

{
  "displayName": "Dashboard for MQL chart (API)",
  "gridLayout": {
    "widgets": [
      {
        "title": "Min/Max Compute Engine CPU utilization",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | within(1h) | { top 1, max(val()) ; bottom 1, min(val()) } | union"
              },
              "plotType": "LINE",
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

这将在您项目中创建一个信息中心，称为“ MQL 图表 (API) 的信息中心”。该信息中心包含一个名为“Compute Engine 最大/最小 CPU 使用率”的图表，其中显示了两条线，分别代表最高值和最低值。

图表会显示包含最高值和最低值的时序。

如需详细了解此示例查询，请参阅将所选内容与 union 结合。

创建图表

您可以将信息中心 JSON 放入文件中，然后将该文件传递给 gcloud beta monitoring dashboards create 或使用 curl 将其发布到 https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards。如需查看更多示例，请参阅创建信息中心。如需详细了解如何使用 curl，请参阅调用 curl。

如需了解如何创建图表和信息中心的一般信息，请参阅通过 API 管理信息中心。如需了解参考资料，请参阅 Dashboards。

创建提醒政策的条件

您可以使用 alertPolicies.create 方法以编程方式创建提醒政策。

创建基于 MQL 的提醒政策与其他提醒政策之间的唯一区别是您使用的 Condition 类型。否则，您可以像设置其他任何提醒政策一样创建这些政策。

下面显示了针对提醒政策条件进行的简单 MQL 查询，该查询测试 Compute Engine CPU 利用率是否超过 15%：

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by sliding(5m), mean(val())
| condition val() > 0.15 '10^2.%'

如需详细了解 MQL condition 提醒操作，请参阅使用 MQL 的提醒政策。

构建提醒政策

要根据 MQL 查询构建提醒政策，请使用 AlertPolicy 条件类型 MonitoringQueryLanguageCondition。MonitoringQueryLanguageCondition 具有以下结构：

{
  "query":    string,
  "duration": string,
  "trigger":  {
    object (Trigger)
  }
}

query 字段的值是简明或严格形式的 MQL 提醒查询字符串。本文档中的示例采用简明形式。如需详细了解严格形式，请参阅严格形式查询。

duration 字段用于指定在触发提醒政策之前，每次查询评估必须生成 true 值的时间长度。如需了解详情，请参阅基于指标的提醒政策的行为。该值必须是分钟数，以秒表示；例如，600s 表示 10 分钟时长。

trigger 字段用于指定 duration 时间段内必须满足条件的时序数（以计数或百分比表示）。默认值为计数 1。如需了解详情，请参阅 Trigger。

对于示例提醒查询（时长为 10 分钟，触发计数为 1），结构如下所示：

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'",
  "duration": "600s",
  "trigger" : {
     "count": 1
  }
}

使用此结构作为条件中 conditionMonitoringQueryLanguage 字段的值，而该条件又嵌入到提醒政策结构中。如需详细了解这些结构，请参阅 AlertPolicy。

下面显示了一个完整的最小政策，它具有 JSON 格式的 MonitoringQueryLanguageCondition 条件：

{
  "displayName":"Alert if CPU utilization exceeds 15% for 10 mins (MQL, API)",
  "combiner":"OR",
  "conditions":[
    {
      "displayName":"MQL-based utilization condition, API",

      "conditionMonitoringQueryLanguage":
      {
        "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'",
        "duration": "600s",
        "trigger" : {
           "count": 1
        },
     },
   }
  ],
}

创建提醒政策

要创建政策，您可以将提醒政策 JSON 放入文件中，然后将文件传递给 gcloud alpha monitoring policies create 或使用 curl 将其发布到 https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/alertPolicies。

如需详细了解用于提醒政策的 Monitoring API，请参阅使用 API 管理提醒政策。

如需详细了解如何使用 curl，请参阅调用 curl。

调用 `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....
```