使用 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

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

设置命名空间

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

kubectl create ns NAMESPACE_NAME

验证服务账号凭据

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

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

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

为 Workload Identity 配置服务账号

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

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

创建和绑定服务账号

此步骤显示在 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 配置

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

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

生产环境中的 Workload Identity

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

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

查询和指标范围

您可以查询的数据取决于 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 服务转发到本地机器。以下示例会将服务转发到端口 3000：

  1. 应用 grafana.yaml 清单：

    kubectl -n NAMESPACE_NAME apply -f  https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/6ebc1afa8e609febe8d687bb7fa6bd2375e46db1/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 主菜单中选择连接，然后选择数据源。

    在 Grafana 中添加数据源。

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

    添加 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 服务器中的数据执行查询。

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

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

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

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

  1. 选择要部署数据源同步程序的项目、集群和命名空间。我们建议在属于多项目指标范围的范围项目的集群中部署数据源同步程序。 数据源同步程序使用已配置的 Google Cloud 项目作为范围项目。

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

    然后，确定您是否必须进一步授权数据源同步程序进行多项目查询：

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

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

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

    在 Grafana 中找到数据源 UID。

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

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

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

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

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

      在 Grafana 中生成并保存服务账号令牌。

  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.

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

    curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/main/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"'|;' \
| kubectl -n NAMESPACE_NAME apply -f -

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

使用 Grafana 运行查询

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

Managed Service for Prometheus up 指标的 Grafana 图表。

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

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

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

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

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

    gcloud config set project PROJECT_ID

  2. 创建服务账号：

    gcloud iam service-accounts create gmp-test-sa

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

  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 支持使用指标范围进行多项目监控。如果本地项目是范围项目，并且本地项目遵循了关于验证或配置服务账号的说明，则多项目查询应该已经生效，你无需进一步配置。

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

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

如需向服务账号授予访问不同 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 环境变量的值传入。

检查 CronJob

如需检查 CronJob 并确保所有变量均已正确设置，请运行以下命令：

kubectl describe cronjob datasource-syncer

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

kubectl logs job.batch/datasource-syncer-init

删除

如需停用数据源同步器 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 参考文档。

如需了解 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 请求。

后续步骤