适用于 Cloud Monitoring 的 PromQL

本文档介绍了如何在 Cloud Monitoring 中使用 Prometheus Query Language (PromQL)。PromQL 为创建图表和信息中心提供了一种替代 Metrics Explorer 菜单驱动界面的方法。

您可以使用 PromQL 对来自以下来源的 Cloud Monitoring 数据进行查询和绘制图表：

Google Cloud 服务（例如 Google Kubernetes Engine 或 Compute Engine），这些服务会写入 Cloud Monitoring 系统指标列表中所述的指标。
用户定义的指标，例如基于日志的指标和 Cloud Monitoring 用户定义的指标。
Google Cloud Managed Service for Prometheus 是来自Google Cloud的一项 Prometheus 全托管式多云解决方案。如需了解此托管式服务（包括 PromQL 提供的支持），请参阅 Google Cloud Managed Service for Prometheus。

您还可以使用 Grafana 等工具对注入到 Cloud Monitoring 的指标数据绘制图表。可用指标包括来自 Managed Service for Prometheus 的指标和指标列表中记录的 Cloud Monitoring 指标。如需了解如何设置 Grafana 和其他基于 Prometheus API 的工具，请参阅 Managed Service for Prometheus 文档中的 Grafana。

您还可以将 Grafana 信息中心导入 Cloud Monitoring。

使用 PromQL 查询 Cloud Monitoring 指标

可以使用 PromQL 的 UTF-8 规范查询 Cloud Monitoring 指标。UTF-8 指标名称必须用引号括起来，并移到大括号内。如果标签名称包含与旧版不兼容的字符，也必须使用英文引号。对于 Cloud Monitoring 指标 kubernetes.io/container/cpu/limit_utilization，以下查询是等效的：

{"kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}
{__name__="kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}。
{"__name__"="kubernetes.io/container/cpu/limit_utilization", "pod_name"="foo"}。

您可以像查询 Prometheus 直方图一样查询 Cloud Monitoring 分布值指标，并将 _count、_sum 或 _bucket 后缀附加到指标名称。

您可以像使用任何其他标签一样在 PromQL 中使用元数据标签，但与指标名称一样，元数据标签也需要与 PromQL 兼容。引用元数据系统标签 version 的语法为 metadata_system_version，元数据用户标签 version 的语法为 metadata_user_version。使用元数据标签的格式正确的 PromQL 查询可能如下所示：

{"compute.googleapis.com/instance/cpu/utilization", monitored_resource="gce_instance",metadata_user_env="prod"}
sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_system_region)
sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_user_env)
{"compute.googleapis.com/instance/uptime_total", "metadata_user_i-love.special/chars"="yes"}
sum("compute.googleapis.com/instance/uptime_total") by ("metadata_user_i-love.special/chars")

如果元数据标签键包含 _ 字符以外的特殊字符，则您必须根据 PromQL 的 UTF-8 规范将标签键用双引号 (") 括起来。您仍然需要将字符串 metadata_user_ 用作元数据标签的前缀。

在实现 UTF-8 兼容性之前创建的图表和信息中心会通过将 Cloud Monitoring 指标名称转换为旧版 PromQL 兼容的等效名称来查询这些指标。如需详细了解旧版 PromQL 转换规则，请参阅将 Cloud Monitoring 指标映射到旧版 PromQL。

在 Cloud Monitoring 中访问 PromQL

您可以通过 Google Cloud 控制台的以下页面上的代码标签页使用 PromQL：

Metrics Explorer
创建自定义信息中心时添加图表

如需了解如何访问和使用编辑器，请参阅使用 PromQL 编辑器。

PromQL 规则和提醒

您可以使用 PromQL 为 Cloud Monitoring 中的任何指标创建提醒政策。如需了解详情，请参阅基于 PromQL 的提醒政策。

您还可以通过在 Cloud Monitoring 中使用 Prometheus 样式的集群内提醒，为 Cloud Monitoring 中的任何指标创建记录和提醒规则。如需了解详情，请参阅托管式规则评估和提醒或自部署的规则评估和提醒。

学习 PromQL

要了解使用 PromQL 的基础知识，建议您查阅开源文档。以下资源可帮助您开始使用：

指定受监控的资源类型

如果 Cloud Monitoring 指标仅与单个 Cloud Monitoring 受监控的资源类型相关联，则 PromQL 查询无需手动指定资源类型即可运行。但是，Cloud Monitoring 中的某些指标（包括一些系统指标以及由基于日志的指标所生成的许多指标）会映射到多个资源类型。如果您使用这些指标之一（尤其是基于日志的指标），则必须明确指定资源类型。

您可以通过执行以下任一操作来查看哪些受监控的资源类型映射到指标：

对于 Google 精选的指标，您可以查看可用指标列表，包括 Google Cloud指标和 Kubernetes 指标。文档中的每个条目都会在该类型下每个条目的第一列中列出关联的受监控资源类型。如果未列出任何受监控的资源类型，则指标可以与任何类型关联。
在 Metrics Explorer 中，您可以执行以下操作：
1. 在选择指标字段中输入指标名称，然后浏览菜单以选择指标。资源菜单会列出该指标的有效资源类型，例如“虚拟机实例”。
2. 在查询构建器窗格的工具栏中，选择名为 < > PromQL 的按钮。
  
  显示的 PromQL 查询会将资源类型显示为 monitored_resource 字段的值。具体而言，此方法适用于可与许多受监控的资源类型关联的指标，例如基于日志的指标、自定义指标或任何用户定义的指标。

如果一个指标与多个资源类型相关联，您必须在 PromQL 查询中指定资源类型。您可以使用特殊标签 monitored_resource 来选择资源类型。

受监控的资源类型在大多数情况下是短字符串，如 gce_instance，但偶尔显示为完整 URI，如 monitoring.googleapis.com/MetricIngestionAttribution。格式正确的 PromQL 查询可能如下所示：

logging_googleapis_com:byte_count{monitored_resource="k8s_container"}
custom_googleapis_com:opencensus_opencensus_io_http_server_request_count_by_method{monitored_resource="global"}
loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

monitored_resource 标签的 "" 值是特殊值，指的是用于 Cloud Monitoring 指标的默认 prometheus_target 资源类型。

如果您在需要时不使用 monitored_resource 标签，则会收到以下错误：

metric is configured to be used with more than one monitored resource type; series selector must specify a label matcher on monitored resource name

解决标签冲突

在 Cloud Monitoring 中，标签可以属于指标或资源。如果指标标签与资源标签具有相同的键名称，您可以通过将前缀 metric_ 添加到查询中的标签键名称来专门引用指标标签。

例如，假设您在指标 example.googleapis.com/user/widget_count 中同时有名为 pod_name 的资源标签和指标标签。

如需按资源标签的值进行过滤，
请使用 example_googleapis_com:user_widget_count{pod_name="RESOURCE_LABEL_VALUE"}
如需按指标标签的值进行过滤，
请使用 example_googleapis_com:user_widget_count{metric_pod_name="METRIC_LABEL_VALUE"}

将 Cloud Monitoring 指标名称映射到旧版 PromQL

Cloud Monitoring 指标名称包括两个组成部分：网域（例如 compute.googleapis.com/）和路径（例如 instance/disk/max_read_ops_count）。由于旧版 PromQL 仅支持特殊字符 : 和 _，因此您必须应用以下规则，使 Monitoring 指标名称与旧版 PromQL 兼容：

将第一个 / 替换为 :。
将所有其他特殊字符（包括 . 和其他 / 字符）替换为 _。

下表列出了一些指标名称及其旧版 PromQL 等效名称：

Cloud Monitoring 指标名称	旧版 PromQL 指标名称
`kubernetes.io/container/cpu/limit_cores`	`kubernetes_io:container_cpu_limit_cores`
`compute.googleapis.com/instance/cpu/utilization`	`compute_googleapis_com:instance_cpu_utilization`
`logging.googleapis.com/log_entry_count`	`logging_googleapis_com:log_entry_count`
`custom.googleapis.com/opencensus/opencensus.io/ http/server/request_count_by_method`	`custom_googleapis_com:opencensus_opencensus_io_ http_server_request_count_by_method`
`agent.googleapis.com/disk/io_time`	`agent_googleapis_com:disk_io_time`

您可以像查询 Prometheus 直方图一样查询 Cloud Monitoring 分布值指标，并将 _count、_sum 或 _bucket 后缀附加到指标名称：

Cloud Monitoring 指标名称	旧版 PromQL 指标名称
`networking.googleapis.com/vm_flow/rtt`	`networking_googleapis_com:vm_flow_rtt_sum` `networking_googleapis_com:vm_flow_rtt_count` `networking_googleapis_com:vm_flow_rtt_bucket`

PromQL 兼容性

PromQL for Cloud Monitoring 的功能可能与上游 PromQL 略有不同。

Cloud Monitoring 中的 PromQL 查询在 Monarch 后端使用内部查询语言进行部分评估，并且查询结果存在一些已知差异。除了本部分中列出的差异之外，Cloud Monitoring 中的 PromQL 与 Prometheus 2.44 版中提供的 PromQL 相当。

可能不支持在 Prometheus 2.44 版之后添加的 PromQL 函数。

UTF-8 支持

适用于 Cloud Monitoring 的 PromQL 支持 UTF-8 查询。

如果您的 Prometheus 指标名称仅包含字母数字字符以及 _ 或 : 字符，并且您的标签键仅包含字母数字字符以及 _ 字符，那么您可以使用传统的 PromQL 语法进行查询。例如，有效查询可能如下所示：job:my_metric:sum{label_key="label_value"}。

不过，如果您的 Prometheus 指标名称使用了 _ 或 : 字符以外的任何特殊字符，或者您的标签键使用了 _ 字符以外的任何特殊字符，则您必须根据 PromQL 的 UTF-8 规范来构建查询。

UTF-8 指标名称必须用引号括起来，并移到花括号中。如果标签名称包含与旧版不兼容的字符，也必须使用英文引号。以下示例中的有效查询均等效：

{"my.domain.com/metric/name_bucket", "label.key"="label.value"}
{__name__="my.domain.com/metric/name_bucket", "label.key"="label.value"}
{"__name__"="my.domain.com/metric/name_bucket", "label.key"="label.value"}

匹配指标名称

仅支持与指标名称完全匹配。您必须在查询中包含与指标名称完全匹配的内容。

对于在 __name__ 标签上使用正则表达式匹配器的常见场景，我们建议采用以下解决方法：

Prometheus 适配器配置通常使用 =~ 运算符来匹配多个指标名称。如需解决此用法问题，请展开配置，以便为每个指标使用单独的政策，并明确命名每个指标。这还可以防止您意外地针对意外指标进行自动扩缩。
正则表达式通常用于在同一图表中绘制多个非维度指标。例如，如果您有一个 cpu_servicename_usage 这样的指标，则可以使用通配符将所有服务一起绘制到图表中。在 Cloud Monitoring 中，使用此类非维度指标是一种明确的错误做法，这种做法会导致查询性能极差。如需解决此使用问题，请将所有维度移至指标标签中，而不是将维度嵌入指标名称中。
查询多个指标通常用于查看可查询的指标。我们建议您改用 /labels/__name__/values 调用来发现指标。您还可以使用 Cloud Monitoring 界面发现指标。
匹配多个指标有助于了解系统对每个指标爬取、注入和收取费用的样本数量。Cloud Monitoring 会在指标管理页面上向您提供此信息。您还可以使用“注入的样本数”指标或“由归因 ID 写入的样本数”指标，以指标数据的形式访问此信息。

过时

Monarch 后端不支持过时。

`irate` 的计算

当 irate 函数的回溯期小于步长时，我们会将回溯期增加到步长。Monarch 需要此更改，以确保输出中不会完全忽略任何输入数据。这种差异也适用于 rate 计算。

`rate` 和 `increase` 的计算

当 rate 函数的回溯期小于步长时，我们会将回溯期增加到步长。Monarch 需要此更改，以确保输出中不会完全忽略任何输入数据。这种差异也适用于 irate 计算。

内插和外推计算有所不同。Monarch 使用的插值算法与 Prometheus 不同，并且这种差异可能会导致结果有所差异。例如，存储 Monarch 计数器样本的时间范围与 Prometheus 使用的单个时间戳无关。因此，可以将 Monarch 中的计数器样本包括在费率计算中，即使 Prometheus 时间戳会排除这些计数器样本。这通常可以生成更准确的费率结果，尤其是在底层时序的开始或结束进行查询时。

`histogram_quantile` 的计算

针对无样本的直方图进行 PromQL histogram_quantile 计算会生成 NaN 值。内部查询语言的计算不会生成任何值；而是会丢弃时间戳处的点。

费率计算差异可能还会影响 histogram_quantile 查询的输入。

不同类型的指标上的特定于类型的函数

虽然上游 Prometheus 是弱类型，但 Monarch 是强类型。这意味着，对不同类型的指标运行单个类型特有的函数（例如，对 GAUGE 指标运行 rate() 或对 COUNTER 或无类型指标运行 histogram_quantile()）在 Cloud Monitoring 中不起作用，即使这些函数在上游 Prometheus 中有效。

适用于 Cloud Monitoring 的 PromQL 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。