Prometheus API または UI を使用したクエリ

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

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

  • Prometheus HTTP API
  • Prometheus UI

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.metricWritermonitoring.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

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 を使用してクエリを実行するをご覧ください。

スタンドアロン Prometheus フロントエンド UI

スタンドアロン Prometheus フロントエンド UI を使用して、取り込まれたデータにアクセスし、可視化できます。この UI は、プロジェクトに関連付けられた指標スコープに応じて、Google Cloud プロジェクトのすべてのデータに対して PromQL クエリを実行します。

このフロントエンド UI は、取り込まれたデータにアクセスするための認証プロキシとしても機能します。この機能は、Grafana や prometheus-adapter ライブラリを使用した水平 Pod 自動スケーリングなど、サービス アカウントに対して OAuth2 をサポートしていないクライアント ツールで使用できます。

データソース同期ツールを使用して Managed Service for Prometheus のデータを可視化するように Grafana を構成することを強くおすすめします。スタンドアロン Prometheus フロントエンド UI を使用して Grafana を構成する手順は、以前にこの方法で Grafana を構成したことがあるユーザー向けの参考として記載しています。

フロントエンド UI をデプロイする

Managed Service for Prometheus 用のスタンドアロン Prometheus フロントエンド UI をデプロイするには、次のコマンドを実行します。

  1. frontend サービスをデプロイして、選択した指標スコープのスコープ対象プロジェクトをクエリするように構成します。

    curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.12.0/examples/frontend.yaml |
    sed 's/\$PROJECT_ID/PROJECT_ID/' |
    kubectl apply -n NAMESPACE_NAME -f -
    
  2. frontend サービスをローカルマシンにポート転送します。次の例では、サービスをポート 9090 に転送します。

    kubectl -n NAMESPACE_NAME port-forward svc/frontend 9090
    

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

kube-prometheus によってインストールされた Grafana Deployment を引き続き使用する場合は、代わりに monitoring Namespace にスタンドアロン Prometheus フロントエンド UI をデプロイします。

スタンドアロン Prometheus フロントエンド UI には、ブラウザで URL http://localhost:9090 からアクセスできます。この手順の実行に Cloud Shell を使用している場合は、[ウェブでプレビュー] ボタンを使用するとアクセスできます。

次のスクリーンショットは、up 指標を表示するスタンドアロン Prometheus フロントエンド UI のテーブルを示しています。

Prometheus インターフェースで指標を表示

Identity-Aware Proxy などを使用して、frontend サービスに対して適切な認証と認可を設定することもできます。サービスの公開方法については、サービスを使用したアプリケーションの公開をご覧ください。

クエリ対象のプロジェクトを変更してマルチプロジェクト モニタリングを利用する

frontend Deployment は、構成された Google Cloud プロジェクトをスコープ対象プロジェクトとして使用します。このプロジェクトがマルチプロジェクトの指標スコープのスコープ対象プロジェクトである場合、指標スコープ内のすべてのプロジェクトから指標を読み取ることができます。

マルチプロジェクトの指標スコープのプロジェクトを指定するには、--query.project-id フラグを使用します。

通常、スコープ対象プロジェクトとして専用プロジェクトを使用しますが、このプロジェクトは frontend Deployment が実行されるプロジェクトとは異なります。Deployment で別のターゲット プロジェクトを読み取るには、次の手順を行う必要があります。

  • ターゲット プロジェクトを frontend Deployment に指示します。
  • ターゲット プロジェクトの読み取り権限をサービス アカウントに付与します。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. 以前に作成した frontend Deployment を開きます。

    kubectl -n NAMESPACE_NAME edit deploy frontend
    
  3. --query.project-id フラグを使用してターゲット プロジェクトを指定します。

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      namespace: NAMESPACE_NAME
      name: frontend
    spec:
      template
        containers:
        - name: frontend
          args:
          - --query.project-id=SCOPING_PROJECT_ID
    ...
    

    ファイルを保存して、エディタを閉じます。変更が適用されると、フロントエンド Pod が再起動され、新しいスコープ対象プロジェクトにクエリが実行されます。

フロントエンド UI を認証する

frontend Deployment では、バージョン 0.5.0 以降の認証済みアクセスで基本アクセス認証がサポートされています。認証を有効にするには、AUTH_USERNAME 環境変数と AUTH_PASSWORD 環境変数を Deployment に追加します。

apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: NAMESPACE_NAME
  name: frontend
spec:
  template
    containers:
    - name: frontend
      env:
      - name: AUTH_USERNAME
        value: USERNAME
      - name: AUTH_PASSWORD
        value: PASSWORD
...

認証情報を明示的に提供する

Google Kubernetes Engine クラスタで frontend コンテナを実行している場合は、このセクションをスキップできます。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
    

  4. サービス アカウント キーを作成してダウンロードします。

    gcloud iam service-accounts keys create gmp-test-sa-key.json \
      --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com
    
  5. 鍵ファイルを Secret として GKE 以外のクラスタに追加します。

    kubectl -n NAMESPACE_NAME create secret generic gmp-test-sa \
      --from-file=key.json=gmp-test-sa-key.json
    

  6. 編集するフロントエンド Deployment リソースを開きます。

    kubectl -n NAMESPACE_NAME edit deploy frontend
    
    1. 太字で示されているテキストをリソースに追加します。

      apiVersion: apps/v1
      kind: Deployment
      metadata:
        namespace: NAMESPACE_NAME
        name: frontend
      spec:
        template
          containers:
          - name: frontend
            args:
            - --query.credentials-file=/gmp/key.json
      ...
            volumeMounts:
            - name: gmp-sa
              mountPath: /gmp
              readOnly: true
      ...
          volumes:
          - name: gmp-sa
            secret:
              secretName: gmp-test-sa
      ...
      

    2. ファイルを保存して、エディタを閉じます。変更が適用されると、Pod が再作成され、指定されたサービス アカウントで指標のバックエンドに対する認証が開始します。

    また、この例で設定されたフラグを使用する代わりに、GOOGLE_APPLICATION_CREDENTIALS 環境変数を使用してキーファイル パスを設定することもできます。

    フロントエンド プロキシ経由での Grafana の使用

    Managed Service for Prometheus は、Grafana の組み込み型 Prometheus データソースを使用するため、変更なしで、コミュニティで作成されたダッシュボードや個人の Grafana ダッシュボードを引き続き使用できます。Grafana ダッシュボードを Cloud Monitoring にインポートすることもできます。

    Google Cloud APIs に対する認証

    Google Cloud APIs では、すべて OAuth2 を使用した認証が必要です。ただし、Grafana では、Prometheus データソースで使用されるサービス アカウントの OAuth2 認証はサポートされていません。Grafana と Managed Service for Prometheus を使用するには、スタンドアロン Prometheus フロントエンド UI を認証プロキシとして使用します。

    データをグローバルにクエリするには、Grafana がスタンドアロン フロントエンド UI プロキシを指すように設定する必要があります。それらの手順を行わなかった場合、Grafana は、ローカルの Prometheus サーバーにあるデータに対してのみクエリを実行します。

    Prometheus UIfrontend サービスをプロキシとしてデプロイしていない場合は、次のコマンドを実行してデプロイします。

    curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.12.0/examples/frontend.yaml |
    sed 's/\$PROJECT_ID/PROJECT_ID/' |
    kubectl apply -n NAMESPACE_NAME -f -
    

    Anthos clusters などの GKE 以外の Kubernetes クラスタの場合は、指標のクエリ権限を frontend サービスに付与するために認証情報を明示的に指定することもできます。

    複数のプロジェクト間でクエリを行うために、frontend サービスで使用される指標スコープを構成する手順については、クエリされたプロジェクトの変更をご覧ください。

    kube-prometheus ライブラリによってインストールされたものや Helm チャートを使用してインストールされたものなど、既存の Grafana Deployment がある場合は、Managed Service for 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/beb779d32f4dd531a3faad9f2916617b8d9baefd/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 UI を認証プロキシとして使用して Grafana で Managed Service for Prometheus にクエリを実行するには、新しいデータソースを Grafana に追加する必要があります。マネージド サービスのデータソースを追加する手順は次のとおりです。

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

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

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

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

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

    4. [HTTP] ペインの [URL] フィールドに、Managed Service for Prometheus frontend サービスの URL を入力します。Prometheus フロントエンド UI がポート 9090 で動作するように構成した場合、このフィールドのサービス URL は http://frontend.NAMESPACE_NAME.svc:9090 になります。

      [HTTP] ペインの [Timeout] フィールドで、値を 120 に設定します。

      基本認証情報でフロントエンド UI プロキシを構成した場合は、[Auth] ペインの [Basic auth] スイッチを有効にして、ユーザー名とパスワードを入力します。

      [Query timeout] フィールドの値を 2m に設定します。

      [HTTP Method] フィールドで GET を選択します。

      [Prometheus type] フィールドで Prometheus を選択します。

      [Prometheus version] フィールドで、2.40.x 以上を選択します。

      Prometheus のデータソースが複数ある場合は、「Managed Prometheus Service」などの名前を付けます。他のフィールドはデフォルト値のままでも構いません。

      Managed Service for Prometheus データソースを構成します。

    5. [Save & Test] をクリックし、データソースが動作していることを示すメッセージを探します。

      Managed Service for Prometheus データソースをテストします。

    新しいデータソースを使用する

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

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

    Managed Service for Prometheus を Thanos に接続する

    オープンソースの thanos-promql-connector を使用して、Managed Service for Prometheus をセルフデプロイの Thanos スタックに連携できます。Google Cloud は、このインテグレーションをサポートしていません。

    Prometheus HTTP API

    Managed Service for Prometheus は、https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/ で始まる URL でアップストリームの Prometheus HTTP API をサポートします。サポートされているエンドポイントについては、API の互換性をご覧ください。

    この API には、標準の Prometheus サーバーに接続可能な任意のツールからアクセスできます。これは API エンドポイント専用で、UI は提供されません。この API は Google Cloud API として OAuth2 認証を使用します。また、Cloud Monitoring API の一部として、PROJECT_ID の値は指標スコープのスコープ対象プロジェクトになるため、指標スコープ内の任意のプロジェクトからデータを取得できます。スコープ対象の詳細については、指標スコープをご覧ください。

    このエンドポイントを使用するには、PromQL 式を指定します。たとえば、次のインスタント クエリは、指標名が up のすべての時系列を取得します。

    curl https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/query \
      -d "query=up" \
      -H "Authorization: Bearer $(gcloud auth print-access-token)"
    

    リクエストが成功すると、次のような結果が読みやすい形式で返されます。

    {
      "status":"success",
      "data":{
        "resultType":"vector",
        "result":[{
          "metric": {
            "__name__":"up",
            "cluster":"gmp-test",
            "instance":"prom-example-84c6f547f5-g4ljn:web",
            "job":"prometheus",
            "location":"us-central1-a",
            "project_id":"a-gcp-project"
          },
          "value": [1634873239.971,"1"]
        }]
      }
    }
    

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

    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 のデータソースを構成することもできます。 match[] パラメータは、__name__ ラベルでの正規表現の照合をサポートしていません。