Grafana を使用したクエリ

Google Cloud Managed Service for Prometheus をデプロイすると、マネージド サービスに送信されたデータをクエリして、結果をグラフやダッシュボードに表示できます。

このドキュメントでは、クエリできるデータを決める指標スコープと、収集したデータを Grafana で取得して使用する方法について説明します。

Managed Service for Prometheus のクエリ インターフェースはすべて、Cloud Monitoring API を使用して Monarch からデータを取得するように構成されています。ローカルの Prometheus サーバーからデータをクエリする代わりに Monarch をクエリすることにより、グローバルなモニタリングを大規模に実施できます。

始める前に

マネージド サービスをまだデプロイしていない場合は、マネージド コレクションまたはセルフデプロイ コレクションを設定します。PromQL を使用した Cloud Monitoring 指標のクエリのみに関心がある場合は、これをスキップできます。

環境を構成する

プロジェクト ID またはクラスタ名を繰り返し入力しないようにするには、次の構成を行います。

  • コマンドライン ツールを次のように構成します。

    • Google Cloud プロジェクトの ID を参照するように gcloud CLI を構成します。

      gcloud config set project PROJECT_ID

    • クラスタを使用するように kubectl CLI を構成します。

      kubectl config set-cluster CLUSTER_NAME

    これらのツールの詳細については、以下をご覧ください。

名前空間を設定する

サンプル アプリケーションの一部として作成するリソースに NAMESPACE_NAME Kubernetes Namespace を作成します。

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 サービス アカウントにバインドし、Monitoring API を使用するために必要なすべての権限を Google Cloud サービス アカウントに付与しています。

本番環境では、各コンポーネントのサービス アカウントを最小権限で使用し、よりきめ細かいアプローチを使用する必要があります。Workload Identity 管理のサービス アカウントを構成する方法については、Workload Identity の使用をご覧ください。

クエリと指標のスコープ

クエリの対象となるデータは、データのクエリに使用する方法に関係なく、Cloud Monitoring 構成の指標スコープによって決まります。たとえば、Grafana を使用して Managed Service for Prometheus のデータをクエリする場合は、各指標スコープを個別のデータソースとして構成する必要があります。

Monitoring の指標スコープは読み取り専用の構成です。これを使用すると、複数の Google Cloud プロジェクトに属している指標データをクエリできます。すべての指標スコープは、スコープ対象プロジェクトと呼ばれる専用の Google Cloud プロジェクトでホストされます。

デフォルトでは、プロジェクトは独自の指標スコープのスコープ対象プロジェクトであり、指標スコープにはそのプロジェクトの指標と構成が含まれます。スコープ対象プロジェクトは、指標スコープ内に複数のモニタリング対象プロジェクトを持つことができます。指標スコープ内のすべてのモニタリング対象プロジェクトの指標と構成は、そのスコープ対象プロジェクトに表示されます。1 つのモニタリング対象プロジェクトが複数の指標スコープに属している場合もあります。

スコープ対象プロジェクト内の指標をクエリし、そのスコープ対象プロジェクトがマルチプロジェクトの指標スコープをホストしている場合は、複数のプロジェクトからデータを取得できます。指標スコープにすべてのプロジェクトが含まれている場合、クエリとルールはグローバルに評価されます。

スコープ対象プロジェクトと指標スコープの詳細については、指標スコープをご覧ください。マルチプロジェクトの指標スコープを構成する方法については、複数のプロジェクトの指標を表示するをご覧ください。

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 Deployment がない場合は、一時的なテスト Deployment を作成してテストできます。

エフェメラル Grafana Deployment を作成するには、クラスタに 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

    このコマンドは何も返さず、実行中に URL へのアクセスが報告されます。

    Grafana には、ブラウザで URL http://localhost:3000 から username:password admin:admin でアクセスできます。

次の手順で新しい Prometheus データソースを Grafana に追加します。

  1. たとえば、URL http://localhost:3000 を参照して Grafana のスタートページに移動して、Grafana Deployment に移動します。

  2. Grafana のメインメニューから [Connections] を選択し、[Data Sources] を選択します。

    Grafana にデータソースを追加する。

  3. [Add data source] を選択し、時系列データベースとして Prometheus を選択します。

    Prometheus データソースを追加します。

  4. データソースに名前を付け、URL フィールドを http://localhost:9090 に設定し、[Save & Test] を選択します。データソースが正しく構成されていないというエラーは無視できます。

  5. デプロイのローカル サービスの URL をコピーします。URL は次のようになります。

    http://grafana.NAMESPACE_NAME.svc:3000

Grafana データソースの構成と認証

Google Cloud APIs はすべて OAuth2 を使用した認証が必要です。ただし、Grafana では、Prometheus データソースの OAuth2 認証はサポートされていません。Grafana と Managed Service for Prometheus を使用するには、データソース同期ツールを使用して OAuth2 認証情報を生成し、Grafana データソース API を使用して Grafana と同期します。

Grafana を構成して、グローバルにデータのクエリを実行するには、データソース同期ツールを使用する必要があります。この操作を行わない場合、Grafana はローカル Prometheus サーバーのデータに対してのみクエリを実行します。

データソース同期ツールは、Kubernetes CronJob を使用して特定の Grafana Prometheus データソースにリモートで構成値を同期するコマンドライン インターフェース ツールです。これにより、Grafana データソースで以下が正しく構成されていることが保証されます。

  • 認証。OAuth2 アクセス トークンを定期的に更新します。
  • Prometheus サーバー URL として設定された Cloud Monitoring API
  • GET に設定された HTTP メソッド
  • Prometheus のタイプとバージョンが 2.40.x 以上に設定されていること
  • HTTP とクエリのタイムアウト値が 2 分に設定されていること

データソース同期ツールは、クラスタのローカル サービス アカウントを使用して、Cloud Monitoring データのクエリに必要な IAM 権限を持つ Google Cloud API アクセス トークンを定期的に生成します。Google Cloud API アクセス トークンの有効期間は 1 時間であるため、データソース同期ツールは 30 分ごとに実行され、Grafana と Cloud Monitoring API 間の認証済み接続が中断していないことを確認します。

データソース同期ツールをデプロイして実行するには、次の操作を行います。

  1. データソース同期ツールをデプロイするプロジェクト、クラスタ、Namespace を選択します。データソース同期ツールは、マルチプロジェクトの指標スコープのスコープ対象プロジェクトに属するクラスタにデプロイすることをおすすめします。データソース同期ツールは、構成された Google Cloud プロジェクトをスコープ対象プロジェクトとして使用します。

    次に、データソース同期ツールを適切に構成して認可していることを確認します。

    次に、マルチプロジェクト クエリ用にデータソース同期ツールを認可する必要があるかどうかを判断します。

  2. Grafana インスタンスの URL を確認します。たとえば、Grafana Cloud デプロイの場合は https://yourcompanyname.grafana.net、テストデプロイ YAML を使用して構成されたローカル インスタンスの場合は http://grafana.NAMESPACE_NAME.svc:3000 です。

    Grafana をローカルにデプロイし、TLS を使用してクラスタ内のすべてのトラフィックを保護するようにクラスタが構成されている場合は、URL で https:// を使用し、サポートされている TLS 認証オプションのいずれかを使用して認証を行う必要があります。

  3. Managed Service for Prometheus に使用する Grafana Prometheus データソース（新規または既存のデータソース）を選択し、データソース UID を探して書き留めます。データソースの UID は、データソースを探索または構成するときに URL の最後の部分に表示されます（例: https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID.）。

  4. Grafana サービス アカウントを設定し、管理者ロールを付与して、サービス アカウント トークンを生成します。トークンの有効期限が「有効期限なし」に設定されていることを確認します。

  5. 前の手順の結果を使用して、次の環境変数を設定します。

    # These values are required.
PROJECT_ID=SCOPING_PROJECT_ID
GRAFANA_API_ENDPOINT=GRAFANA_INSTANCE_URL
DATASOURCE_UIDS=GRAFANA_DATASOURCE_UID
GRAFANA_API_TOKEN=GRAFANA_SERVICE_ACCOUNT_TOKEN

  6. 次のコマンドを実行して、初期化時と 30 分ごとにデータソースを更新する CronJob を作成します。Workload Identity を使用している場合、NAMESPACE_NAME の値は、以前にサービス アカウントにバインドした Namespace と同じにする必要があります。

    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 サーバー URL の値が https://monitoring.googleapis.com で始まっていることを確認します。ページの更新が必要になることもあります。確認したら、ページの下部に移動し、[Save & test] を選択します。Grafana のラベルのオートコンプリートが機能するように、このボタンを少なくとも 1 回選択する必要があります。

Grafana を使用してクエリを実行する

これで、Grafana ダッシュボードを作成し、構成されたデータソースを使用してクエリを実行できるようになりました。次のスクリーンショットは、up 指標を表示する Grafana チャートを示しています。

Managed Service for Prometheus の「up」指標を表す Grafana チャート。

PromQL を使用して Google Cloud システムの指標をクエリする方法については、Cloud Monitoring 指標向け PromQL をご覧ください。

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 の互換性

次の Prometheus HTTP API エンドポイントは、接頭辞が https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/ の URL で Managed Service for Prometheus によってサポートされます。

詳細については、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 リクエストではサポートされません。データソース同期ツールまたはフロントエンド プロキシを使用する場合、この制限は自動的に管理されます。GET リクエストのみを発行するように、Grafana で Prometheus のデータソースを構成することもできます。

次のステップ