使用 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。如果您未為 GKE 使用 Workload Identity Federation，且先前已從預設節點服務帳戶移除其中任一角色，則必須重新加入缺少的權限，才能繼續操作。

設定 Workload Identity Federation for GKE 的服務帳戶

如果 Kubernetes 叢集未啟用 Workload Identity Federation for GKE，您可以略過本節。

Managed Service for Prometheus 會使用 Cloud Monitoring API 擷取指標資料。如果叢集使用 GKE 適用的工作負載身分聯盟，您必須將 Monitoring API 的權限授予 Kubernetes 服務帳戶。本節說明下列事項：

• 建立專屬的 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服務帳戶。如要進一步瞭解監控角色，請參閱「存取權控管」。

下列指令會授予 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

對 GKE 適用的工作負載身分聯盟設定進行偵錯

如果您無法順利使用 Workload Identity Federation for GKE，請參閱相關文件，瞭解如何驗證 Workload Identity Federation for GKE 設定，以及Workload Identity Federation for GKE 疑難排解指南。

由於輸入錯誤和部分複製貼上作業是設定 GKE 工作負載身分識別聯邦的常見錯誤來源，因此我們強烈建議您使用這些操作說明中程式碼範例中內嵌的可編輯變數和可點選的複製貼上圖示。

在實際工作環境中使用 Workload Identity Federation for GKE

本文所述範例會將 Google Cloud 服務帳戶繫結至預設 Kubernetes 服務帳戶，並授予 Google Cloud服務帳戶使用 Monitoring API 所需的所有權限。

在正式環境中，您可能會想採用更精細的方法，為每個元件建立服務帳戶，並為每個服務帳戶授予最基本的權限。如要進一步瞭解如何設定服務帳戶以管理工作負載身分，請參閱「使用 GKE 適用的工作負載身分聯盟」。

查詢和指標範圍

無論您使用哪種方法查詢資料，Cloud Monitoring 建構的指標範圍都會決定您可以查詢的資料。舉例來說，如果您使用 Grafana 查詢 Managed Service for Prometheus 資料，則必須將每個指標範圍設為獨立的資料來源。

監控指標範圍是僅限讀取時間的建構元件，可讓您查詢屬於多個 Google Cloud 專案的指標資料。每個指標範圍都由指定的 Google Cloud 專案代管，稱為範圍專案。

根據預設，專案會是其指標範圍的限定範圍專案，而指標範圍包含該專案的指標和設定。限定範圍專案的指標範圍中，可能包含多個受監控專案，而限定範圍專案可查看指標範圍中所有受監控專案的指標和設定。監控專案也可以屬於多個指標範圍。

當您在限定範圍專案中查詢指標時，如果該限定範圍專案代管多專案指標範圍，您就能從多項專案擷取資料。如果指標範圍包含所有專案，查詢和規則會在全球範圍內評估。

如要進一步瞭解專案範圍和指標範圍，請參閱「指標範圍」。如要瞭解如何設定多專案指標範圍，請參閱「查看多項專案的指標」。

Cloud Monitoring 中的 Managed Service for Prometheus 資料

如要確認 Prometheus 資料是否已匯出，最簡單的方法就是使用支援 PromQL 的 Google Cloud 主控台中的 Cloud Monitoring Metrics Explorer 頁面。如需操作說明，請參閱「在 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.15.3/examples/grafana.yaml
   

2. 將 grafana 服務轉送至本機電腦。以下範例會將服務轉送至通訊埠 3000：

   kubectl -n NAMESPACE_NAME port-forward svc/grafana 3000
   

   這個指令不會傳回，並在執行期間回報對網址的存取情形。

   您可以在瀏覽器中透過網址 http://localhost:3000 存取 Grafana，並使用使用者名稱:密碼 admin:admin。

接著，請按照下列步驟，在 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 伺服器中的資料執行查詢。

資料來源同步器是一種指令列介面工具，可遠端傳送設定值至特定 Grafana Prometheus 資料來源。這可確保 Grafana 資料來源正確設定下列項目：

• 驗證：定期重新整理 OAuth2 存取權杖
• 設定為 Prometheus 伺服器網址的 Cloud Monitoring API
• HTTP 方法設為 GET
• Prometheus 類型和版本設為至少 2.40.x
• HTTP 和查詢逾時值設為 2 分鐘

資料來源同步器必須重複執行。由於 Google Cloud API 存取權權杖的有效期限為一小時，因此每隔 10 分鐘執行資料來源同步器，可確保 Grafana 和 Cloud Monitoring API 之間的連線保持連線狀態。

您可以選擇使用 Kubernetes CronJob 或 Cloud Run 和 Cloud Scheduler 來執行資料來源同步器，以便享有完全無伺服器的體驗。如果您在本機部署 Grafana (例如使用開源 Grafana 或 Grafana Enterprise)，建議您在 Grafana 執行的同一叢集中執行資料來源同步器。如果您使用 Grafana Cloud，建議選擇完全無伺服器的選項。

使用 Grafana 執行查詢

您現在可以建立 Grafana 資訊主頁，並使用已設定的資料來源執行查詢。以下螢幕截圖顯示 Grafana 圖表，其中顯示 up 指標：

如要瞭解如何使用 PromQL 查詢 Google Cloud 系統指標，請參閱「Cloud Monitoring 指標的 PromQL」。

在 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 上部署資料來源同步器的使用者，如果本機專案是您的限定範圍專案，且您已按照本機專案的服務帳戶驗證或設定操作說明操作，則多專案查詢應可正常運作，無須進一步設定。

如果本機專案不是範圍專案，您必須授權本機專案的預設 Compute Engine 服務帳戶或GKE 服務帳戶的 Workload Identity Federation，才能讓 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/v0.15.3/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 語言專屬用戶端程式庫中不支援 Prometheus HTTP 端點。

如要瞭解 PromQL 相容性，請參閱「PromQL 支援」。

• 系統全面支援下列端點：

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

• 只有在使用 __name__ 標籤做為 <label_name> 值，或使用系列選取器完全比對 __name__ 標籤時，/api/v1/label/<label_name>/values 端點才會運作。舉例來說，系統完全支援下列呼叫：

  • /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 要求。使用資料來源同步器或前端 Proxy 時，系統會為您管理這項限制。您也可以在 Grafana 中設定 Prometheus 資料來源，只發出 GET 要求。match[] 參數不支援 __name__ 標籤上的規則運算式比對。

後續步驟

• 使用 Cloud Monitoring 中的 PromQL 快訊。
• 設定受管理的規則評估。
• 設定常用的匯出工具。