使用 Grafana 进行查询

部署 Google Cloud Managed Service for Prometheus 后，您可以查询发送到代管式服务的数据，并将结果显示在图表和信息中心中。

本文档介绍了用于确定可以查询的数据的指标范围，以及如何使用 Grafana 检索和使用收集的数据。

Managed Service for Prometheus 的所有查询接口都配置为使用 Cloud Monitoring API 从 Monarch 中检索数据。通过查询 Monarch，而不是从本地 Prometheus 服务器查询数据，您可以大规模进行全球监控。

准备工作

如果您尚未部署托管式服务，请设置托管式集合或自部署集合。 如果您只希望使用 PromQL 查询 Cloud Monitoring 指标，则可以跳过此步骤。

配置您的环境

为避免重复输入您的项目 ID 或集群名称，请执行以下配置：

• 按如下方式配置命令行工具：

  • 配置 gcloud CLI 以引用您的 Google Cloud 项目的 ID：

    gcloud config set project PROJECT_ID
    

  • 配置 kubectl CLI 以使用集群：

    kubectl config set-cluster CLUSTER_NAME
    

  如需详细了解这些工具，请参阅以下内容：

  • gcloud CLI 概览
  • kubectl 命令

设置命名空间

为您在示例应用中创建的资源创建 NAMESPACE_NAME Kubernetes 命名空间：

kubectl create ns NAMESPACE_NAME

验证服务账号凭据

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

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

如果您不在 GKE 上运行，请参阅明确提供凭据。

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

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

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

• 创建专用 Google Cloud 服务账号 gmp-test-sa。
• 将 Google Cloud 服务账号绑定到测试命名空间 NAMESPACE_NAME 中的默认 Kubernetes 服务账号。
• 为 Google Cloud 服务账号授予必要的权限。

创建和绑定服务账号

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

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

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

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

向服务账号授权

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

以下命令会向 Google Cloud 服务账号 gmp-test-sa 授予读取指标数据所需的 Monitoring API 角色。

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

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.viewer \
&& \
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.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

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

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

查询和指标范围

您可以查询的数据取决于 Cloud Monitoring 构造指标范围，无论您用于查询数据的方法如何。例如，如果您使用 Grafana 查询 Managed Service for Prometheus 数据，则必须将每个指标范围配置为单独的数据源。

Monitoring 指标范围是一种只读结构，可让您查询属于多个 Google Cloud 项目的指标数据。每个指标范围都由指定的 Google Cloud 项目托管，称为范围项目。

默认情况下，项目是其自身指标范围的范围限定项目，而指标范围包含该项目的指标和配置。限定范围的项目可以在其指标范围内包含多个受监控的项目，并且指标范围内所有受监控项目的指标和配置对限定范围的项目可见。一个受监控的项目还可以属于多个指标范围。

查询范围项目中的指标时，如果该项目托管多项目指标范围，则可以从多个项目中检索数据。如果指标范围包含所有项目，则查询和规则将进行全局评估。

如需详细了解如何限定项目和指标范围，请参阅指标范围。如需了解如何配置多项目指标范围，请参阅查看多个项目的指标。

Cloud Monitoring 中的 Managed Service for Prometheus 数据

如需验证 Prometheus 数据被导出，最简单的方法是使用 Google Cloud 控制台中的 Cloud Monitoring Metrics Explorer 页面，它支持 PromQL。如需查看相关说明，请参阅在 Cloud Monitoring 中使用 PromQL 进行查询。

您还可以将 Grafana 信息中心导入 Cloud Monitoring。 这样，您就可以继续使用社区创建的或个人的 Grafana 信息中心，而无需配置或部署 Grafana 实例。

Grafana

Managed Service for Prometheus 使用 Grafana 的内置 Prometheus 数据源，这意味着您可以继续使用任何由社区创建的或个人的 Grafana 信息中心，而无需进行任何更改。

根据需要部署 Grafana

如果您的集群中没有正在运行的 Grafana 部署，则可以创建临时测试部署进行实验。

如需创建临时 Grafana 部署，请将 Managed Service for Prometheus grafana.yaml 清单应用到集群，并将 grafana 服务转发到本地机器。 由于 CORS 限制，您无法使用 Cloud Shell 访问 Grafana 部署。

1. 应用 grafana.yaml 清单：

   kubectl -n NAMESPACE_NAME apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.13.0/examples/grafana.yaml
   

2. 将 grafana 服务通过端口转发到您的本地机器。以下示例会将该服务转发到端口 3000：

   kubectl -n NAMESPACE_NAME port-forward svc/grafana 3000
   

   此命令不会返回，并且在运行时会报告对该网址的访问权限。

   您可以在浏览器中通过网址 http://localhost:3000 使用用户名:密码 admin:admin 访问 Grafana。

然后，向 Grafana 添加新的 Prometheus 数据源，具体操作如下：

1. 转到 Grafana 部署（例如，通过浏览到网址 http://localhost:3000 来访问 Grafana 欢迎页面）。

2. 从 Grafana 主菜单中选择连接，然后选择数据源。

   

3. 选择添加数据源，然后选择 Prometheus 作为时序数据库。

   

4. 为数据源命名，将 URL 字段设置为 http://localhost:9090，然后选择保存并测试。您可以忽略任何显示数据源配置有误的错误。

5. 复制部署的本地服务网址，格式如下：

   http://grafana.NAMESPACE_NAME.svc:3000
   

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

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

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

数据源同步器是一个命令行界面，它使用 Cron 作业将配置值远程同步到给定的 Grafana Prometheus 数据源。这可确保 Grafana 数据源正确配置以下内容：

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

数据源同步器会使用 Google Cloud 服务账号定期生成具有必要 IAM 权限的 Google Cloud API 访问令牌，以查询 Cloud Monitoring 数据。由于 Google Cloud API 访问令牌的生命周期为一小时，因此数据源同步器每 30 分钟运行一次，以确保 Grafana 与 Cloud Monitoring API 之间一直维持经过身份验证的连接。

您可以选择使用 Kubernetes CronJob 或 Cloud Run 和 Cloud Scheduler 运行数据源同步器，以获得完全无服务器体验。如果您在本地部署 Grafana（例如使用开源 Grafana 或 Grafana Enterprise），我们建议在运行 Grafana 的同一集群中运行数据源同步器。如果您使用的是 Grafana Cloud，我们建议您选择完全无服务器选项。

使用 Grafana 运行查询

现在您可以使用配置好的数据源创建 Grafana 信息中心并运行查询。以下屏幕截图中的 Grafana 图表显示了 up 指标：

如需了解如何使用 PromQL 查询 Google Cloud 系统指标，请参阅 PromQL for Cloud Monitoring 指标。

在 GKE 之外运行数据源同步器

如果您在 Google Kubernetes Engine 集群中运行数据源同步器，或者您使用的是无服务器选项，则可以跳过此部分。如果您在 GKE 上遇到身份验证问题，请参阅验证服务账号凭据。

在 GKE 上运行时，数据源同步器会根据节点的服务账号或 Workload Identity Federation for GKE 设置自动从环境中检索凭据。在非 GKE Kubernetes 集群中，必须使用 GOOGLE_APPLICATION_CREDENTIALS 环境变量将凭据明确提供给数据源同步器。

1. 将上下文设置为目标项目：

   gcloud config set project PROJECT_ID
   

2. 创建服务账号：

   gcloud iam service-accounts create gmp-test-sa
   

   此步骤会创建您可能已在 Workload Identity Federation for GKE 说明中创建的服务账号。

3. 向服务账号授予所需权限：

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

4. 创建并下载服务账号的密钥：

   gcloud iam service-accounts keys create gmp-test-sa-key.json \
     --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com
   

5. 使用 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置密钥文件路径。

授权数据源同步程序获取多项目监控

Managed Service for Prometheus 支持使用指标范围进行多项目监控。

对于使用无服务器选项的用户，如果您选择的项目是多项目指标范围的范围限定项目，则可以进行多项目查询。

对于在 Kubernetes 上部署数据源同步器的用户，如果本地项目是范围限定项目，并且已针对本地项目按照验证或配置服务账号的说明操作，则多项目查询应该无需进一步配置即可生效。

如果本地项目不是范围项目，则需要向本地项目的默认计算服务账号或 Workload Identity Federation for GKE 服务账号授予对范围项目的 monitoring.viewer 访问权限。然后，将范围项目的 ID 作为 PROJECT_ID 环境变量的值传入。

如果您使用 Compute Engine default 服务账号，则可以执行以下操作之一：

• 在属于范围项目的集群中部署数据源同步程序。

• 为集群启用 Workload Identity Federation for GKE，然后按照配置步骤操作。

• 提供显式服务账号密钥。

如需向服务账号授予访问不同 Google Cloud 项目所需的权限，请执行以下操作：

1. 向服务账号授予从要查询的目标项目读取数据的权限：

   gcloud projects add-iam-policy-binding SCOPING_PROJECT_ID \
     --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
     --role=roles/monitoring.viewer
   

2. 配置数据源同步器时，请将范围限定项目的 ID 作为 PROJECT_ID 环境变量的值传入。

检查 Kubernetes CronJob

如果您在 Kubernetes 上部署数据源同步器，则可以运行以下命令来检查 CronJob 并确保所有变量均已正确设置：

kubectl describe cronjob datasource-syncer

如需查看初始配置 Grafana 的作业的日志，请在应用 datasource-syncer.yaml 文件后立即运行以下命令：

kubectl logs job.batch/datasource-syncer-init

删除

如需在 Kubernetes 上停用数据源同步器 CronJob，请运行以下命令：

kubectl delete -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/main/cmd/datasource-syncer/datasource-syncer.yaml

停用数据源同步器会停止使用新的身份验证凭据更新关联的 Grafana，因此将无法再查询 Managed Service for Prometheus。

API 兼容性

Managed Service for Prometheus 支持以下 Prometheus HTTP API 端点（网址前缀为 https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/）。

如需查看完整文档，请参阅 Cloud Monitoring API 参考文档。 Cloud Monitoring 特定于语言的客户端库中不提供 Promethus HTTP 端点。

如需了解 PromQL 兼容性，请参阅 PromQL 支持。

• 以下端点完全受支持：

  • /api/v1/query
  • /api/v1/query_range
  • /api/v1/metadata
  • /api/v1/labels
  • /api/v1/query_exemplars

• /api/v1/label/<label_name>/values 端点只有在 __name__ 标签是通过将其用作 <label_name> 值或使用序列选择器对其进行完全匹配时才有效。例如，以下调用完全受支持：

  • /api/v1/label/__name__/values
  • /api/v1/label/__name__/values?match[]={__name__=~".*metricname.*"}
  • /api/v1/label/labelname/values?match[]={__name__="metricname"}

  此限制会导致 Grafana 中的 label_values($label) 变量查询失败。您可以改用 label_values($metric, $label)。建议您使用此类查询，以避免使用与给定信息中心无关的指标提取标签值。

• 系统支持 /api/v1/series 端点用于 GET 请求，而非 POST 请求。当您使用数据源同步器或前端代理时，此限制由系统为您代管。您也可以在 Grafana 中将 Prometheus 数据源配置为仅发出 GET 请求。 match[] 参数不支持对 __name__ 标签使用正则表达式匹配。

后续步骤

• 使用 Cloud Monitoring 中的 PromQL 提醒。
• 设置代管式规则评估。
• 设置常用的导出工具。