Cloud Monitoring 中的 PromQL

本文档介绍了如何配置 Grafana 以从 Cloud Monitoring 中读取指标数据。然后，您可以使用 PromQL 直观呈现数据并绘制数据图表。Grafana 和 Cloud Monitoring 通过一个名为数据源同步器的进程关联在一起，该进程可实现 Grafana 数据源与 Cloud Monitoring 之间的通信。数据源同步器会执行以下操作：

  • 将配置值发送到 Grafana 数据源。
  • 维护可从 Cloud Monitoring 读取指标数据的 Trusted Cloud by S3NS 服务账号的身份验证凭证。

本文档介绍了如何设置数据源同步器，并提供了有关在 Cloud Monitoring 中使用 PromQL 的具体信息。本文档假定您已熟悉 Grafana。

授权 Grafana 读取指标数据

本部分介绍了如何使用数据源同步器生成和同步凭证，以在 Cloud Monitoring 和 Grafana 之间设置授权。

使用数据源同步器进行授权

Trusted Cloud by S3NS API 都需要使用 OAuth2 进行身份验证；但是，Grafana 不支持对与 Prometheus 数据源搭配使用的服务账号使用 OAuth2 身份验证。 如需将 Grafana 与 Cloud Monitoring 搭配使用，请使用数据源同步器为您的服务账号生成 OAuth2 凭证，并通过 Grafana 数据源 API 将凭证同步到 Grafana。

您必须使用数据源同步器配置并授权 Grafana 全局查询数据。如果您未执行这些步骤，Grafana 仅会对本地 Prometheus 服务器中的数据执行查询。

数据源同步器是一个命令行界面工具，它会将配置值远程发送到给定的 Grafana Prometheus 数据源。这可确保 Grafana 数据源正确配置以下内容：

  • 身份验证，通过定期刷新 OAuth2 访问令牌来完成
  • Prometheus 服务器网址设置为 Cloud Monitoring API
  • HTTP 方法设置为 GET
  • Prometheus 类型和版本设置为 2.40.x 或更高版本
  • HTTP 和查询超时值设置为 2 分钟

数据源同步器必须反复运行。由于Trusted Cloud by S3NS API 访问令牌的生命周期为一小时，因此每 10 分钟运行一次数据源同步器可确保 Grafana 与 Cloud Monitoring API 之间一直维持经过身份验证的连接。

配置 Grafana 数据源并进行身份验证

您可以使用 Grafana 查询 Google Kubernetes Engine 服务或其他环境中的 Cloud Monitoring 指标数据。以下说明使用可修改的变量来创建可运行的命令。我们强烈建议使用代码示例中嵌入的可修改变量和可点击的复制粘贴图标。

GKE

如需在 Kubernetes 集群中部署并运行数据源同步器，请执行以下操作：

  1. 选择要在其中部署数据源同步器的项目、集群和命名空间。

    接下来，确保正确配置数据源同步程序并向其授权：

  2. 确定 Grafana 实例的网址，例如对于 Grafana Cloud 部署，此网址是 https://yourcompanyname.grafana.net；对于使用测试部署 YAML 配置的本地实例，此网址是 http://grafana.NAMESPACE_NAME.svc:3000。

    如果您在本地部署 Grafana，并且集群配置为使用 TLS 保护集群内所有流量，则需要在网址中使用 https:// 并使用支持的 TLS 身份验证选项之一进行身份验证。

  3. 选择要用于 Cloud Monitoring 的 Grafana Prometheus 数据源，这可以是新的数据源，也可以是已存在的数据源，然后找到并记下数据源 UID。浏览或配置数据源时，您可以在网址的最后一部分找到数据源 UID，例如 https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID. 请勿复制整个数据源网址。仅复制网址中的唯一标识符。

  4. 设置 Grafana 服务账号，方法是创建服务账号并为该账号生成要使用的令牌：

    1. 在 Grafana 导航边栏中，点击管理>用户和访问权限>服务账号。

    2. 如需创建服务账号，请点击添加服务账号，为其命名，并在 Grafana 中为其授予“Admin”角色。 如果您使用的 Grafana 版本允许使用更精细的权限，则可以使用数据源 > 写入者角色。

    3. 点击添加服务账号令牌。

    4. 将令牌失效时间设置为“无失效时间”，然后点击生成令牌，接着将生成的令牌复制到剪贴板，以在下一步中用作 GRAFANA_SERVICE_ACCOUNT_TOKEN。

  5. 使用前面步骤的结果设置以下环境变量：

    # These values are required.
PROJECT_ID=SCOPING_PROJECT_ID # The value from Step 1.
GRAFANA_API_ENDPOINT=GRAFANA_INSTANCE_URL # The value from step 2. This is a URL.
DATASOURCE_UIDS=GRAFANA_DATASOURCE_UID # The value from step 3. This is not a URL.
GRAFANA_API_TOKEN=GRAFANA_SERVICE_ACCOUNT_TOKEN # The value from step 4.
GCM_ENDPOINT_OVERRIDE=--gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"

  6. 运行以下命令创建一个 CronJob，它会在初始化时刷新数据源，然后每 10 分钟刷新一次。如果您使用的是 Workload Identity Federation for GKE，则 NAMESPACE_NAME 的值应与您之前绑定到服务账号的命名空间相同。

    curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/cmd/datasource-syncer/datasource-syncer.yaml \
| sed 's|$DATASOURCE_UIDS|'"$DATASOURCE_UIDS"'|; s|$GRAFANA_API_ENDPOINT|'"$GRAFANA_API_ENDPOINT"'|; s|$GRAFANA_API_TOKEN|'"$GRAFANA_API_TOKEN"'|; s|$PROJECT_ID|'"$PROJECT_ID"'|;' s|$GCM_ENDPOINT_OVERRIDE|'"$GCM_ENDPOINT_OVERRIDE"'|; \
| kubectl -n NAMESPACE_NAME apply -f -

  7. 转到新配置的 Grafana 数据源，并验证 Prometheus 服务器网址值以 https://monitoring.s3nsapis.fr 开头。您可能需要刷新页面。验证后，在页面底部选择保存并测试。您至少需要选择此按钮一次，以确保 Grafana 中的标签自动补全功能正常运行。

验证服务账号凭据

如果您的 Kubernetes 集群已启用 Workload Identity Federation for GKE，则可以跳过此部分。

在 GKE 上运行时，Cloud Monitoring 会自动根据 Compute Engine 默认服务账号从环境中检索凭证。默认情况下，默认服务账号具有必要的权限 monitoring.metricWriter 和 monitoring.viewer。如果您未使用 Workload Identity Federation for GKE，并且之前从默认节点服务账号中移除了任一角色，则必须重新添加这些缺少的权限，然后才能继续。

为 Workload Identity Federation for GKE 配置服务账号

如果您的 Kubernetes 集群未启用 Workload Identity Federation for GKE，则可以跳过此部分。

Cloud Monitoring 使用 Cloud Monitoring API 捕获指标数据。如果您的集群使用的是 Workload Identity Federation for GKE，则必须向您的 Kubernetes 服务账号授予 Monitoring API 权限。本节介绍以下内容：

创建和绑定服务账号

此步骤显示在 Cloud Monitoring 文档中的多个位置。如果您在执行先前的任务时已经执行此步骤，则无需重复执行。请直接跳到向服务账号授权。

以下命令序列会创建 SERVICE_ACCT_NAME 服务账号并将其绑定到 NAMESPACE_NAME 命名空间中的默认 Kubernetes 服务账号：

gcloud config set project PROJECT_ID \
&&
gcloud iam service-accounts create SERVICE_ACCT_NAME \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \
  SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com

如果您使用的是其他 GKE 命名空间或服务账号，请适当调整命令。

向服务账号授权

相关权限组已收集到多个角色中，您可以将这些角色授予主账号（在此示例中为 Trusted Cloud服务账号）。如需详细了解 Monitoring 角色，请参阅访问权限控制。

以下命令会向 Trusted Cloud 服务账号 SERVICE_ACCT_NAME 授予读取指标数据所需的 Monitoring API 角色。

如果您在执行先前的任务时已经为 Trusted Cloud 服务账号授予了特定角色，则无需再次执行此操作。

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
  --role=roles/monitoring.viewer \
&& \
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator

调试 Workload Identity Federation for GKE 配置

如果您在使 Workload Identity Federation for GKE 正常工作时遇到问题，请参阅验证 Workload Identity Federation for GKE 设置的文档和 Workload Identity Federation for GKE 故障排除指南。

由于拼写错误和部分复制粘贴是配置 Workload Identity Federation for GKE 时最常见的错误来源，因此我们强烈建议使用这些说明中代码示例中嵌入的可编辑变量和可点击复制粘贴图标。

生产环境中的 Workload Identity Federation for GKE

本文档中所述的示例将 Trusted Cloud 服务账号绑定到默认 Kubernetes 服务账号，并为 Trusted Cloud服务账号授予使用 Monitoring API 所需的所有权限。

在生产环境中，您可能需要使用更精细的方法，其中每个组件对应一个服务账号，并且每个服务账号都具有最小的权限。如需详细了解如何为工作负载身份管理配置服务账号，请参阅使用 Workload Identity Federation for GKE。

其他位置

如需在 Google Kubernetes Engine 以外的环境中部署并运行数据源同步器，请执行以下操作：

  1. 为要使用的数据源同步器设置服务账号：

    1. 为 gcloud 命令设置默认项目：

      gcloud config set project PROJECT_ID

    2. 为要使用的数据源同步器创建服务账号：

      gcloud iam service-accounts create DS_SYNCER_SVCACCT_NAME

    3. 向服务账号授予读取指标数据的权限：

       gcloud projects add-iam-policy-binding PROJECT_ID \
 --member=serviceAccount:DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
 --role=roles/monitoring.viewer \
 && \
 gcloud projects add-iam-policy-binding PROJECT_ID \
 --member=serviceAccount:DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
 --role=roles/iam.serviceAccountTokenCreator

    4. 为服务账号创建密钥：

      gcloud iam service-accounts keys create DS_SYNCER_SVCACCT_KEYFILE_NAME.json \
--iam-account DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com

      此目录的路径将在后续步骤中用于设置环境变量。如需获取该路径，请运行 pwd 命令并记录相应值：

      pwd
DS_SYNCER_SVCACCT_KEYFILE_DIR

  2. 确定 Grafana 实例的网址，例如对于 Grafana Cloud 部署，该网址是 https://yourcompanyname.grafana.net；对于本地测试实例，该网址是 https://localhost:3000。此值用于运行数据源同步器的命令。

    如果您在本地为 Kubernetes 集群部署 Grafana，并且该集群配置为使用 TLS 保护集群内所有流量，则需要在网址中使用 https://，并在下一步中使用支持的 TLS 身份验证选项之一进行身份验证。

  3. 在 Grafana 中，添加一个用于 Cloud Monitoring 的 Prometheus 数据源，并记录该数据源的 UID：

    1. 依次点击连接 > 数据源 > 添加新数据源。从时序数据库列表中选择 Prometheus。

    2. 在 Prometheus 服务器网址字段中，输入以下值：

      https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/

    3. 点击保存并测试

      浏览器中数据源页面的网址包含数据源界面，例如 https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID.

    4. 记录数据源 UID。此值用于运行数据源同步器的命令。请勿复制整个数据源网址。仅复制网址中的唯一标识符，其值类似于 ee0z3woqjah34e：

      GRAFANA_DATASOURCE_UID

  4. 设置 Grafana 服务账号，方法是创建服务账号并为该服务账号生成要使用的令牌：

    1. 在 Grafana 导航边栏中，点击管理 > 用户和访问权限 > 服务账号。

    2. 如需创建服务账号，请点击添加服务账号，为其命名，并在 Grafana 中为其授予“Admin”角色。

    3. 点击添加服务账号令牌。

    4. 将令牌失效时间设置为“无失效时间”，然后点击生成令牌，接着将生成的令牌复制到以下可修改的变量中。此值用于运行数据源同步器的命令。

      GRAFANA_SERVICE_ACCOUNT_TOKEN

  5. 运行数据源同步器。您可以使用 Docker 从预构建的容器映像运行同步器，也可以从源代码构建代码并手动运行。数据源同步器是一个 Go 应用，因此您需要安装 Go 才能从源代码构建同步器。

    Docker

    使用容器映像 gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0 从 Docker 运行数据源同步器。如需进行测试，您可以手动运行同步器。验证连接正常运行后，由于访问令牌的生命周期为一小时，您必须使用自动化机制（例如 cron 作业）每 10 分钟运行一次数据源同步器，以确保连接不中断。

    使用以下 Docker 命令运行数据源同步器：

    docker run --network container:grafana -v "DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json:/app/DS_SYNCER_SVCACCT_KEYFILE_NAME.json" gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0
-datasource-uids=UID_OF_GRAFANA_DATASOURCE
-grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN
-grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE
-project-id=PROJECT_ID
-query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json
-gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"

    如需创建 cron 作业以运行数据源同步器，请执行以下操作：

    1. 修改 cron 表：

      cron -e

    2. 添加一个每 10 分钟运行一次上述命令的条目：

      */10 * * * * * docker run --network container:grafana -v "DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json:/app/<KEY_ID>" gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0 -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"

    如需详细了解运行数据源同步器时可用的命令行选项，请参阅 README 文档。

    源代码

    1. 如需自行构建数据源同步器，请执行以下操作：

      1. 创建一个包含代码的目录，然后切换到该目录：

        mkdir data-source-syncer-code

cd data-source-syncer-code

        此目录的路径将在后续步骤中用于设置环境变量。如需获取路径，请运行 pwd 命令，并将其记录在可修改的变量中：

        pwd
PATH_TO_LOCAL_REPO_COPY

      2. 从仓库的当前版本中克隆代码：

        git clone -b 'v0.15.3' --single-branch https://github.com/GoogleCloudPlatform/prometheus-engine

      3. 进入 datasource-syncer 目录并构建代码：

        cd prometheus-engine/cmd/datasource-syncer

go build main.go

    2. 运行数据源同步器。如需进行测试，您可以手动运行同步器。验证连接正常运行后，由于访问令牌的生命周期为一小时，您必须使用自动化机制（例如 cron 作业）每 10 分钟运行一次数据源同步器，以确保连接不中断。

      使用以下命令手动运行数据源同步器：

      main -datasource-uids=UID_OF_GRAFANA_DATASOURCE
-grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN
-grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE
-project-id=PROJECT_ID
-query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json
-gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"

      如需创建 cron 作业以运行数据源同步器，请执行以下操作：

      1. 修改 cron 表：

         cron -e

      2. 添加一个每 10 分钟运行一次上述命令的条目：

         */10 * * * * * main -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"

      如需详细了解运行数据源同步器时可用的命令行选项，请参阅 README 文档。

  6. 转到新配置的 Grafana 数据源，并验证 Prometheus 服务器网址值是否以 https://monitoring.s3nsapis.fr 开头。您可能需要刷新页面。验证后，在页面底部点击保存并测试。您至少需要点击此按钮一次，以确保 Grafana 中的标签自动补全功能正常运行。

在 Grafana 中查看指标

如需在 Grafana 中查看 Trusted Cloud 项目的指标，请执行以下操作：

  1. 点击导航面板或数据源页面中的探索。

  2. 在指标字段中，使用下拉菜单选择一个指标。您还可以选择 Metrics Explorer 来搜索特定指标。如果指标与多个受监控的资源相关联，您必须向查询中添加 monitored_resource 标签过滤条件，并选择资源类型。

  3. 添加其他标签过滤条件和操作来构建查询。

如需了解如何在 Grafana 中构建可视化图表和信息中心，请参阅面板和可视化图表。

命名规则

Prometheus 指标模型和命名惯例与 Cloud Monitoring 使用的不同。如需使用 PromQL 查询 Monitoring 指标数据，您必须将 Cloud Monitoring 名称转换为与 PromQL 兼容的等效名称。如需了解命名惯例，请参阅将 Cloud Monitoring 指标映射到 PromQL。

学习 PromQL

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

PromQL 差异

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

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

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

匹配指标名称

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

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

  • Prometheus 适配器配置通常使用 =~ 运算符来匹配多个指标名称。如需解决此用法问题，请展开配置，以便为每个指标使用单独的政策，并明确命名每个指标。这还可以防止您意外地针对意外指标进行自动扩缩。
  • 正则表达式通常用于在同一图表中绘制多个非维度指标。例如，如果您有一个 cpu_servicename_usage 这样的指标，则可以使用通配符将所有服务一起绘制到图表中。在 Cloud Monitoring 中，使用此类非维度指标是一种明确的错误做法，这种做法会导致查询性能极差。如需解决此使用问题，请将所有维度移至指标标签中，而不是将维度嵌入指标名称中。
  • 查询多个指标通常用于查看可查询的指标。我们建议您改用 /labels/__name__/values 调用来发现指标。

过时

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 中有效。