Prometheus サービスからデータをクエリする

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

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

  • Prometheus ベースのインターフェース:

    • Google Cloud Console の [Prometheus 向けのマネージド サービス] ページ
    • Prometheus HTTP API
    • Prometheus UI
    • Grafana
  • Google Cloud Console の Cloud Monitoring

始める前に

マネージド サービスをまだデプロイしていない場合は、マネージド コレクションまたはセルフデプロイ コレクションを設定します。

環境を構成する

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

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

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

      gcloud config set project PROJECT_ID
      
    • クラスタを使用するように kubectl ツールを構成します。

      kubectl config set-cluster CLUSTER_NAME
      

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

名前空間を設定する

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

kubectl create ns gmp-test

Workload Identity のサービス アカウントを構成する

Kubernetes クラスタで Workload Identity が有効になっていない場合は、このセクションをスキップできます。

Managed Service for Prometheus は、Cloud Monitoring API を使用して指標データをキャプチャします。クラスタで Workload Identity を使用している場合は、Kubernetes サービス アカウントに Monitoring API の権限を付与する必要があります。このセクションでは、次のことを説明します。

サービス アカウントを作成してバインドする

この手順は、Managed Service for Prometheus のドキュメントの複数の場所で説明されています。前のタスクですでに行っている場合は、この手順を繰り返す必要はありません。サービス アカウントを承認するに進んでください。

次のコマンド シーケンスでは、gmp-test-sa サービス アカウントを作成し、gmp-test 名前空間でデフォルトの Kubernetes サービス アカウントにバインドします。

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[gmp-test/default]" \
  gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace gmp-test \
  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

このドキュメントの例では、Google Cloud サービス アカウントをデフォルトの Kubernetes サービス アカウントにバインドし、Monitoring API を使用するために必要なすべての権限を Google Cloud サービス アカウントに付与しています。

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

クエリと指標のスコープ

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

Monitoring の指標スコープは読み取り専用の構成です。これを使用すると、指標スコープがホストされている専用の Cloud プロジェクト(スコープ対象プロジェクト)から複数の Google Cloud プロジェクトをモニタリングできます。

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

プロジェクト内の指標をクエリし、そのプロジェクトがマルチプロジェクトの指標スコープをホストしている場合は、複数のプロジェクトからデータを取得できます。

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

[Prometheus 向けのマネージド サービス] ページ

Prometheus データがエクスポートされていることを確認する最も簡単な方法は、Google Cloud Console で PromQL ベースの [Prometheus 向けのマネージド サービス] ページを使用することです。

このページを表示するには、次のようにします。

  1. Cloud Console で、[Monitoring] に移動するか、次のボタンを使用します。

    [Monitoring] に移動

  2. [Monitoring] ナビゲーション パネルで、[マネージド Prometheus] をクリックします。

[Prometheus 向けのマネージド サービス] ページでは、PromQL クエリを使用して、マネージド サービスによって収集されたデータを取得してグラフ化できます。このページでは、Managed Service for Prometheus によって収集されたデータのみをクエリできます。

次のスクリーンショットは、up 指標を表示するグラフを示しています。

Prometheus の「Up」指標を表示する Managed Service for Prometheus グラフ。

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 では、Managed Service for Prometheus コレクタによって取り込まれた指標のみをクエリできます。PromQL を使用して Google Cloud システム指標のクエリを実行することはできません。

Prometheus UI

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

この UI は、取り込まれたデータにアクセスするための認証プロキシとしても機能します。この機能は、OAuth2 をサポートしていないクライアント ツール(Grafana など)で使用できます。Grafana を使用して Managed Service for Prometheus からのデータを可視化する場合は、Prometheus UI もデプロイする必要があります。

UI をデプロイする

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

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

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

    kubectl -n gmp-test 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 UI で指標を表示

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

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

GKE で実行する場合、フロントエンドは、Compute Engine のデフォルト サービス アカウントまたは Workload Identity の設定に応じて環境から認証情報を自動的に取得します。

GKE 以外の Kubernetes クラスタでは、フラグまたは GOOGLE_APPLICATION_CREDENTIALS 環境変数を使用して、認証情報をフロントエンドに明示的に提供する必要があります。

  1. サービス アカウントを作成します。

    gcloud iam service-accounts create gmp-test-sa
    

    この手順では、Workload Identity の手順ですでに作成したサービス アカウントを作成します。

  2. サービス アカウントに必要な権限を付与します。

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

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

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

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

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

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

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      namespace: gmp-test
      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
    ...
    

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

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

クエリ対象のプロジェクトを変更する

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

別のプロジェクトを指定するには、--query.project-id フラグを使用します。

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

  • ターゲット プロジェクトを frontend Deployment に指示します。
  • ターゲット プロジェクトの読み取り権限をサービス アカウントに付与します。Compute Engine の default サービス アカウントを使用している場合は、次のいずれかを行います。

別の 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 gmp-test edit deploy frontend
    
  3. --query.project-id フラグを使用してターゲット プロジェクトを指定します。

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

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

Grafana

Grafana は、Prometheus データソースの OAuth2 認証をサポートしていません。Grafana と Managed Service for Prometheus データソースを使用するには、認証プロキシとして Prometheus UI を使用する必要があります。

Prometheus UI をまだデプロイしていない場合は、デプロイします。

Grafana をデプロイする

すでに Grafana Deployment がある場合は、通常の方法でアクセスできます。

クラスタ内に実行中の Grafana Deployment がない場合は、一時的なテスト Deployment を作成してテストできます。

エフェメラル Grafana Deployment を作成するには、クラスタに Managed Service for Prometheus grafana.yaml マニフェストを適用し、grafana サービスをローカルマシンにポート転送します。次の例では、サービスをポート 3000 に転送します。

  1. grafana.yaml マニフェストを適用します。

    kubectl -n gmp-test apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.1.1/examples/grafana.yaml
    
  2. frontend サービスをローカルマシンにポート転送します。この例では、サービスをポート 9090 に転送します。

    kubectl -n gmp-test port-forward svc/grafana 3000
    

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

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

データソースを構成する

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.gmp-test.svc:9090 になります。

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

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

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

  5. [Test and Save] をクリックし、「データソースは動作しています」のようなメッセージを探します。

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

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

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

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

Cloud Monitoring での Managed Service for Prometheus データ

Managed Service for Prometheus は、データ ストレージ バックエンドの Monarch を Cloud Monitoring と共有します。Cloud Monitoring で提供されるすべてのツールで、Managed Service for Prometheus から収集されたデータを使用できます。たとえば、Monitoring 用の Cloud Console で説明されているように、Metrics Explorer を使用できます。

Monitoring で Managed Service for Prometheus データを扱う場合は、Cloud Monitoring で提供される次のクエリツールを使用します。

[Prometheus 向けのマネージド サービス] ページを除き、Cloud Monitoring は PromQL をサポートしていません。

prometheus_target リソース

Cloud Monitoring では、モニタリング対象リソースタイプの時系列データが書き込まれます。Prometheus 指標の場合、モニタリング対象リソースタイプは prometheus_target です。Prometheus Service for Managed Service のモニタリング クエリでは、このリソースタイプを指定する必要があります。

prometheus_target リソースには次のラベルがあります。これは、クエリ対象データのフィルタリングと操作に使用できます。

  • project_id: このリソースに関連付けられた Google Cloud プロジェクトの ID。
  • location: データを収集して保存する物理的な場所(Cloud プロジェクトのリージョン)。通常、この値は GKE クラスタまたは Compute Engine インスタンスのリージョンです。AWS またはオンプレミス デプロイメントからデータが収集される場合、値は最も近い Cloud プロジェクトのリージョンになります。
  • cluster: GKE クラスタまたは関連するコンセプト。空の場合もあります。
  • namespace: GKE 名前空間または関連するコンセプト。空の場合もあります。
  • job: Prometheus ターゲットのジョブラベル(既知の場合)。ルール評価の結果で空の場合もあります。
  • instance: Prometheus ターゲットのインスタンス ラベル(既知の場合)。ルール評価の結果で空の場合もあります。

これらのラベルの値は収集時に設定されます。

Monitoring 用の Cloud Console

Managed Service for Prometheus データを Cloud Monitoring で時系列に表示するには、Metrics Explorer を使用します。指標を表示するように Metrics Explorer を構成するには、次の手順を行います。

  1. Cloud Console で、[Monitoring] に移動するか、次のボタンを使用します。

    [Monitoring] に移動

  2. [Monitoring] のナビゲーション パネルで、[Metrics Explorer] をクリックします。

  3. グラフに表示するデータを指定します。[MQL] タブまたは [CONFIGURATION] タブを使用できます。

    • [MQL] タブを使用するには、次の操作を行います。

      1. [MQL] タブを選択します。

      2. 次のクエリを入力します。

        fetch prometheus_target::prometheus.googleapis.com/up/gauge
        
      3. [RUN QUERY] をクリックします。

    • [CONFIGURATION] タブを使用するには、次の操作を行います。

      1. [CONFIGURATION] タブを選択します。

      2. [Resource type] フィールドに、「prometheus」と入力してリストをフィルタし、[Prometheus Target] を選択します。

      3. [Metric] フィールドに「up/」と入力してリストをフィルタし、[prometheus/up/gauge] を選択します。

次のスクリーンショットでは、[MQL] タブの Metrics Explorer グラフに up 指標が表示されています。

Managed Service for Prometheus の「Up」指標が表示されている Metrics Explorer グラフ。

API の互換性

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

  • 次のエンドポイントは完全にサポートされています。

    • /api/v1/query
    • /api/v1/query_range
    • /api/v1/metadata

    PromQL の互換性については、PromQL のサポートをご覧ください。

  • /api/v1/$label/values エンドポイントは __name__ ラベルのみをサポートします。この制限により、Grafana の label_values($label) 変数のクエリは失敗します。代わりに label_values($metric, $label) を使用できます。ダッシュボードに関係のない指標のラベル値は取得されないため、このタイプのクエリはおすすめしません。

  • /api/v1/series エンドポイントは GET でサポートされますが、POST リクエストではサポートされません。フロントエンド プロキシを使用する場合、この制限はプロキシによって管理されます。GET リクエストのみを発行するように、Grafana で Prometheus のデータソースを構成することもできます。