使用 MQL 的代码编辑器

本部分介绍 Monitoring Query Language (MQL) 代码编辑器的功能。Google Cloud 控制台中提供该编辑器，为创建有效的 MQL 查询提供建议、错误检测和其他支持。

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

访问代码编辑器

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

  1. 在 Google Cloud 控制台的导航面板中，选择 Monitoring，然后选择  Metrics Explorer：

    进入 Metrics Explorer

  2. 在查询构建器窗格的工具栏中，选择名称为  MQL 或  PromQL 的按钮。
  3. 确认在语言切换开关中选择了 MQL。语言切换开关与用于设置查询格式的工具栏中相同

在信息中心内创建图表时，您可以使用类似的步骤来访问代码编辑器。

使用代码编辑器

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

代码编辑器中的 MQL 查询。

自动补全

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

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

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

错误消息

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

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

代码折叠

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

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

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

查找和替换

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

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

编辑器控件

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

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

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

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

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

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

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

保存图表

来自 Metrics Explorer

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

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

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

  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 利用率，校准时间段为一小时。

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

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

例如，如果在上一查询中将传递给 every 操作的校准时间段从 1h 更改为 1m，则查询会生成包含最小/最大条带的图表：

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

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

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

基于 MQL 的提醒政策

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

如需从 Google Cloud 控制台创建基于 MQL 的提醒政策，请按照管理提醒政策中描述的常规步骤创建政策，但在为提醒政策创建条件时，您需要使用代码编辑器，而不是基于表单的指标选择器。

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

查询转换

您可以使用图表的指标选择器或在 Metrics Explorer 中来创建查询，然后将该查询转换为 MQL。相应的 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 分钟为间隔执行速率校准。转换后的查询采用严格格式。