使用 MQL 的代码编辑器

本部分介绍了适用于 Monitoring Query Language (MQL)。编辑器支持 并提供建议、错误检测和其他 对创建有效 MQL 查询的支持。

本页面未介绍 MQL 语言；如需查看一组示例并详细了解语言，请参阅示例和关于 MQL 语言。MQL 参考提供了语言的全面参考。

访问代码编辑器

如需在使用 Metrics Explorer 时访问代码编辑器，请执行以下操作： 执行以下操作：

  1. 在 Google Cloud 控制台中，转到 Metrics Explorer 页面：

    进入 Metrics Explorer

    如果您使用搜索栏查找此页面，请选择子标题为监控的结果。

  2. 在查询构建器窗格的工具栏中，选择名为  MQL 或  PromQL 的按钮。
  3. 验证已在语言切换开关中选择 MQL。语言切换开关位于同一工具栏中，用于设置查询的格式。

在 信息中心。

使用代码编辑器

如需使用代码编辑器，请在查询编辑器中输入查询，然后 点击运行查询：

代码编辑器中的 MQL 查询。

自动补全

在您输入查询时，编辑器会显示一个在语法上有效的补全列表。您可以通过按 Control+Space 手动打开自动补全菜单，也可以按 Escape 将其关闭。

要浏览选项列表，请使用箭头键。按 Enter 插入所选选项。

要插入所有可用选项通用的前缀，请按 Tab。

错误消息

错误消息会显示在编辑器窗格的底部。

如果查询中存在会干扰自动补全建议的错误，系统会在您输入时显示错误消息。否则，执行查询时会显示错误消息。

代码折叠

编辑器提供代码折叠功能（可以收起查询细分），以便您暂时隐藏它们。

编辑器会在行号旁边通过插入符号指示查询的可折叠部分，如以下屏幕截图所示：

代码编辑器中使用脱字符号指示可折叠代码。

查找和替换

编辑器支持查找和替换功能。如需查找并选择行替换查询中的字词，请按 Control+F（或在 Mac 上按 Command+F）。以下屏幕截图展示了该功能：

代码编辑器支持查找和替换功能。

编辑器控件

编辑器有两个控件，用于确定与查询的互动方式。

默认情况下，只有在点击执行查询后才会执行查询。您可以将代码编辑器设置为以 但该选项默认处于停用状态。

如需启用自动运行选项，请使用 Auto-run 切换开关。 启用此选项后，编辑器的工作方式如下：

  • 不显示执行查询按钮。
  • 系统会在您输入时持续显示错误消息。

  • 如果您的光标位于不完整但没有错误的查询的末尾，编辑器会在控制栏中显示一个黄色三角形。如果有空间，还会显示 Incomplete query 字样。

    代码编辑器不会尝试评估不完整的查询。

代码编辑器和图表区域之间还有一个拖动条。 使用此条可更改两个区域的相对大小。

保存图表

来自 Metrics Explorer

在 Metrics Explorer 的代码编辑器中，您可以选择 信息中心要保存图表，请执行以下操作：

  1. 如果未启用“自动执行”选项，请运行 点击运行查询，然后保存图表。如果您不运行查询 首先，代码编辑器会保存您上次运行的查询。

  2. 点击 Save Chart。 对话框会告诉您，保存图表会将查询替换为严格表单。如需了解详情，请参阅严格形式查询。

  3. 要继续保存图表，请执行以下操作：

    1. 为图表指定一个说明性标题。
    2. 选择新图表的信息中心。
    3. 点击对话框中的保存。

来自信息中心

要保存要添加到信息中心的图表，请执行以下操作：

  1. 为图表指定一个说明性标题。

  2. 如果未启用“自动执行”选项，请运行 点击运行查询，然后保存图表。如果您不运行查询 首先，代码编辑器会保存您上次运行的查询。

  3. 点击保存。 对话框会告诉您，保存图表会将查询替换为严格表单。如需了解详情，请参阅严格形式查询。

  4. 点击对话框中的保存以保存图表并返回信息中心。

退出代码编辑器

要退出代码编辑器而不保存图表或条件，请执行以下操作： 点击 “返回查询选择器 widget”。编辑器中的任何查询文本都会被舍弃，但您可以选择将其保存到剪贴板。

以严格形式查看查询

如需在使用代码编辑器时以严格形式查看查询，请执行以下操作： 点击 更多选项 然后选择查看严格形式。

如需了解详情，请参阅严格形式查询。

时间范围、图表和代码编辑器

除了提醒政策条件中使用的 MQL 查询外， 代码编辑器中的 MQL 查询必须包含时间范围。 时间范围指定要作为 数据的一部分返回的数据子集 查询。时间范围可使用图表的 时间范围选择器或 MQL 查询文本中明确显示。

默认情况下，时间范围选择器设置为 1 小时。

要更改图表的时间范围，请使用时间范围选择器。对于 例如，如果您想查看过去一周的数据 时间范围选择器中的过去 1 周。你还可以指定 开始和结束时间，或指定查看前后的时间。

如需了解如何使用代码编辑器创建提醒政策， 请参阅创建 MQL 提醒政策。

使用图表设置选择时间

您可以使用图表的时间选择器为查询设置时间段。此选择器是设置时间段的默认方式。要更改时间段，请在图表上选择其他时间选项。例如，如果选择一周，查询将返回当前到一周之前的数据。

MQL 可以使用图表指定的时间。

使用此默认机制时，您无需在查询文本中指定显式时间范围。系统会隐式使用图表上的值。

使用 within 选择时间

您可以使用 within 操作在查询中明确指定查询的时间范围。此操作会确定返回数据的范围。如果查询包含 within 操作，则图表上的时间选项将被停用，并使用查询中指定的时间范围。

如果您从查询中移除显式 within 操作，则系统会自动重新启用图表选项，以确保查询始终包含时间段。

如果要使用 API 方法 timeSeries.query 发出查询，则必须使用显式时间选择。如需了解详情，请参阅通过 Monitoring API 使用 MQL。

时间设置和已保存的图表

如果您使用 MQL 来创建图表，然后将图表保存到信息中心，则查询会发生以下两种情况：

  1. 您在编辑器中提供的查询将转换为规范形式或严格形式。该转换不会更改查询的含义，但会显式执行查询中假设的内容，例如完整的列名称或校准操作。如需了解详情，请参阅严格形式查询。

  2. 查询中的时间范围选择会被移除。信息中心上的图表共享一个时间选择器，并且对该选择器所做的更改会应用到信息中心上的所有图表。因此，不再需要原始查询的时间范围选择器。

如需了解如何管理信息中心和修改图表，请参阅管理自定义信息中心。

查询、校准和显示时间段

MQL 具有许多指定时间段的操作，它们可能会混淆。以下操作与查询范围相关：

  • within：指定查询输出窗口。此操作会决定返回的数据量。例如，如果指定 within 1h，则查询仅会生成时间戳在过去一小时内的数据点，因此此操作会替换图表的时间选择器选项。

  • 以下操作与其输出表的校准时间段相关。两者都需要将校准表作为输入，否则提供默认值：

    • every：指定校准表输出的时间段。

    • window：指定校准操作的窗口。

    在这两种情况下，如果为 align 操作提供了明确的校准窗口，则它必须与为 window 操作指定的时间段（如果提供）匹配。对于 delta 校准函数，校准窗口和时间段必须相同；如果提供了明确的校准窗口，则 every 操作（如果指定）必须保持一致。在所有情况下，校准窗口必须至少与校准时间段一样长，否则输入数据会被忽略。

MQL 还具有 graph_period 操作，用于指定图表的输出点的时间段。此操作对于向由第三方软件绘制其输出的 API 提供的查询很有用。Monitoring 图表绘制软件会忽略查询中的 graph_period 操作，并根据输出图表的时间宽度设置数据点的时间段。

在 Monitoring 图表中，图表时间段是根据 图表时间范围选择器的值以及数据点的最大数量 图表可显示的内容例如，如果您选择一周，图表时间段可能是一小时。对于信息中心上的图表 在图表期内，点击 查询统计信息。

查询校准时间段与图表时间段之间的关系可以更改图表的外观。以下部分介绍这一关系。

最小/最大条带

当查询校准时间段接近图表时间段时，图表用一条折线表示每个绘制的时间序列。如果查询校准时间段少于图表时间段的一半，则图表会在每条折线周围添加阴影区域。此区域称为“最小/最大条带”，它显示产生平均值的值范围。

例如，假设存在以下 MQL 查询：

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by [zone], mean(val())
| every 1h

此查询按可用区返回虚拟机的平均 CPU 利用率， 一小时校准时间段。

如果图表的时间选择器设置为一周，则图表的时间段为 1 小时，这一时间在芯片上显示。对于该示例查询，图表时间段和校准时间段是相等的。运行查询会生成如下所示的图表：

具有相等的校准和图表时间段的折线图仅显示折线。

例如，如果您更改传递给 every 的校准时间段， 操作从 1h 到 1m，则该查询会生成一个 包含最小值/最大值范围的图表：

校准时间段少于图表时间段一半的折线图显示折线和最小/最大条带。

图表折线是根据图表选择的一周绘制的，因此折线与上一个示例中的折线一样。但是，查询每分钟生成一个数据点，因此最小/最大条带显示在每个一小时图表点范围内的来自查询的一分钟值的范围。

如果省略 every 操作，则默认查询校准时间段为校准窗口的值或一分钟（如果未指定校准窗口）。

基于 MQL 的提醒政策

您也可以使用 MQL 和代码编辑器创建查询 在提醒政策中使用。

如需通过 Google Cloud 控制台创建基于 MQL 的提醒政策， 您可以按照创建政策的常规步骤进行操作， 管理提醒政策，但在创建条件时创建 对于提醒政策，您可以使用代码编辑器，而不是基于表单的 指标选择器。

如需了解详情，请参阅创建 MQL 提醒政策。

查询转换

您可以在图表或 Metrics Explorer 中使用指标选择器 来创建查询，然后将该查询转换为 MQL。 相应的 MQL 查询显示在编辑器中。

在使用 Metrics Explorer，请执行以下操作：

  1. 在查询构建器窗格的工具栏中，选择名为  MQL 或  PromQL 的按钮。
  2. 验证已在语言切换开关中选择 MQL。语言切换开关位于同一工具栏中，用于设置查询的格式。

当您在 上查看图表时，将基于表单的查询转换为 MQL 点击 MQL。

考虑一个非常简单的请求，例如“从我的 Compute Engine 虚拟机实例获取 CPU 用量”。此查询涉及 gce_instance 受监控的资源类型和 compute.googleapis.com/instance/cpu/usage_time 指标类型。

以下屏幕截图显示了基于表单的指标选择器中的此查询：

在指标选择器中选择指标和资源类型。

指标和受监控的资源类型是手动输入的。所有其他 字段都有默认值。

以下屏幕截图显示了将基于表单的 转换为 MQL 查询：

编辑器显示将表单值转换为 MQL 的结果。

此 MQL 查询将为指定的指标和资源类型提取时间序列，并以 1 分钟为间隔执行速率校准。转换后的查询采用严格格式。