API と PromQL を使用して Prometheus のメトリックのクエリを実行する

Prometheus 用 Azure Monitor マネージド サービスは、Azure Kubernetes クラスターからメトリックを収集し、それを Azure Monitor ワークスペースに格納します。 PromQL (Prometheus クエリ言語) は、時系列データのクエリと集計を実行できる機能クエリ言語です。 Azure Monitor ワークスペースに格納されているメトリックのクエリと集計を行うには、PromQL を使います。

この記事では、REST API から PromQL を使って Azure Monitor ワークスペースのクエリを実行する方法について説明します。 PromQL について詳しくは、「Prometheus のクエリ」をご覧ください。

前提条件

PromQL を使って Azure Monitor ワークスペースのクエリを実行するには、次の前提条件が必要です。

• Azure Kubernetes クラスターまたはリモート Kubernetes クラスター。
• Kubernetes クラスターからメトリックをスクレイピングする Prometheus 用 Azure Monitor マネージド サービス。
• Prometheus メトリックが格納されている Azure Monitor ワークスペース。

認証

Azure Monitor ワークスペースのクエリを実行するには、Microsoft Entra ID を使って認証を行います。 API では、クライアント資格情報を使った Microsoft Entra 認証がサポートされています。 クライアント アプリを Microsoft Entra ID に登録し、トークンを要求します。

Microsoft Entra 認証を設定するには、次の手順を実行します。

1. アプリを Microsoft Entra ID に登録します。
2. Azure Monitor ワークスペースへのアプリのアクセスを許可します。
3. トークンを要求します。

アプリを Microsoft Entra ID に登録する

1. アプリを登録するには、「承認トークンを要求し、API を操作するために、アプリを登録する」の手順のようにします

ワークスペースへのアプリのアクセスを許可する

Azure Monitor ワークスペースからデータを照会できるように、監視データ閲覧者ロールをアプリに割り当てます。

1. Azure portal で Azure Monitor ワークスペースを開きます。

2. [概要] ページで、REST 要求で使うクエリ エンドポイントを記録しておきます。

3. [アクセス制御 (IAM)] を選択します。

4. [追加] を選択してから、[アクセス制御 (IAM)] ページで [ロールの割り当てを追加] を選択します。

   

5. [ロールの割り当ての追加] ページで、[監視] を検索します。

6. [Monitoring Data Reader] (監視データ閲覧者) を選んでから、[メンバー] タブを選びます。

   

7. [メンバーの選択] を選びます。

8. 登録したアプリを見つけて選びます。

9. [選択] を選択します。

10. [レビューと割り当て] を選択します。

    

アプリの登録を作成し、Azure Monitor ワークスペースのらデータを照会するためのアクセス権をそれに割り当てました。 これで、トークンを生成してクエリで使用できるようになります。

トークンの要求

コマンド プロンプトで、または Postman などのクライアントを使用して、次の要求を送信します。

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret>' \
--data-urlencode 'resource=https://prometheus.monitor.azure.com'

応答本文の例:

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https:/prometheus.monitor.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

次の HTTP 要求で使用するために、応答のアクセス トークンを保存します。

クエリ エンドポイント

Azure Monitor ワークスペースの概要ページで、Azure Monitor ワークスペースのクエリ エンドポイントを見つけます。

サポート対象 API

次のクエリがサポートされています。

インスタント クエリ

詳しくは、「インスタント クエリ」をご覧ください

パス: /api/v1/query
例 :

POST https://k8s-02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query  
--header 'Authorization:  Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=sum( \
    container_memory_working_set_bytes \
    * on(namespace,pod) \
    group_left(workload, workload_type) \
    namespace_workload_pod:kube_pod_owner:relabel{ workload_type="deployment"}) by (pod)'

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query?query=container_memory_working_set_bytes' 
--header 'Authorization:  Bearer <access token>'

範囲クエリ

詳しくは、「範囲クエリ」をご覧ください
パス: /api/v1/query_range
例 :

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range?query=container_memory_working_set_bytes&start=2023-03-01T00:00:00.000Z&end=2023-03-20T00:00:00.000Z&step=6h'
--header 'Authorization: Bearer <access token>

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range' 
--header 'Authorization:  Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=up' 
--data-urlencode 'start=2023-03-01T20:10:30.781Z' 
--data-urlencode 'end=2023-03-20T20:10:30.781Z' 
--data-urlencode 'step=6h'

系列

詳しくは、系列に関するページをご覧ください

パス: /api/v1/series
例 :

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series' 
--header 'Authorization: Bearer <access token>
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'match[]=kube_pod_info{pod="bestapp-123abc456d-4nmfm"}'

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series?match[]=container_network_receive_bytes_total{namespace="default-1669648428598"}'

ラベル

詳しくは、ラベルに関する記事をご覧ください。パス: /api/v1/labels
例 :

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

ラベルの値

詳しくは、ラベルの値に関する記事をご覧ください
パス: /api/v1/label/__name__/values.

例:

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/label/__name__/values'

OSS Prom API の完全な仕様については、Prometheus の HTTP API に関する記事をご覧ください。

API の制限

Prometheus の仕様で詳しく説明されている制限に加えて、次の制限があります。

• クエリのスコープをメトリックに設定する必要がある
  すべての時系列フェッチ クエリ (/series、/query、または /query_range) には、__name__ ラベル マッチャーが含まれている必要があります。 つまり、各クエリのスコープはメトリックに設定されている必要があります。 1 つのクエリで使用できる __name__ ラベル マッチャーは 1 つだけです。
• クエリ /series は、正規表現フィルターをサポートしていません
• サポートされている時間範囲
  • /query_range API でサポートされている時間範囲は 32 日です。 これは、クエリ自体で指定される範囲セレクターを含め、許容される最大時間範囲です。 たとえば、過去 24 時間のクエリ rate(http_requests_total[1h] は、実際には 25 時間のデータのクエリが実行されることを意味します。 これは、24 時間の範囲に加えて、クエリ自体で指定された 1 時間に基づくものです。
  • /series API は、最大 12 時間の時間範囲のデータをフェッチします。 endTime が指定されていない場合、endTime = time.now()。 時間範囲が 12 時間を超える場合、startTime は endTime – 12h に設定されます
• 無視される時間範囲
  /labels と /label/__name__/values で指定された開始時刻と終了時刻は無視され、Azure Monitor ワークスペースに保持されているすべてのデータのクエリが実行されます。
• 実験的な機能
  事例などの実験的な機能はサポートされていません。

Prometheus のメトリックの制限について詳しくは、「Prometheus メトリック」をご覧ください

大文字小文字の区別

Azure マネージド Prometheus は、大文字と小文字を区別しないシステムです。 メトリック名、ラベル名、ラベル値などの文字列が、文字列の大文字と小文字が異なるだけで別の時系列と異なる場合、それらの文字列は同じ時系列として扱われます。

Azure マネージド Prometheus では、次の時系列は同じと見なされます。

diskSize(cluster="eastus", node="node1", filesystem="usr_mnt")
diskSize(cluster="eastus", node="node1", filesystem="usr_MNT")

上記の例は、時系列データベースの 1 つの時系列です。

• それらに対して取り込まれたサンプルは、単一の時系列に対してスクレイピングされたか取り込まれたかのように格納されます。
• 前述の例が同じタイムスタンプで取り込まれた場合、そのうちの 1 つがランダムに削除されます。
• 時系列データベースに格納され、クエリで返される大文字と小文字は予測できません。 同じ時系列に対して、異なる大文字と小文字が異なるタイミングで返される場合があります。
• クエリに存在するメトリック名またはラベル名/値マッチャーは、大文字と小文字を区別しない比較を行うことで、時系列データベースから取得されます。 クエリに大文字と小文字を区別するマッチャーがある場合、文字列比較を行うときに、大文字と小文字を区別しないマッチャーとして自動的に扱われます。

1 つの一貫性のある大文字と小文字を使用して時系列を生成またはスクレイピングすることをお勧めします。

オープンソース Prometheus では、上記の時系列は 2 つの異なる時系列として扱われます。 スクレイピングされるか取り込まれたサンプルは、個別に保存されます。

よく寄せられる質問

このセクションでは、一般的な質問への回答を示します。

メトリックのすべてまたは一部が欠落しています。 トラブルシューティングをどのように行えばよいですか?

マネージド エージェントから Prometheus メトリックを取り込むためのトラブルシューティング ガイドは、こちらで参照できます。

同じ名前で大文字と小文字が異なる 2 つのラベルを持つメトリックが見つからないのはなぜですか?

Azure マネージド Prometheus は、大文字と小文字を区別しないシステムです。 メトリック名、ラベル名、ラベル値などの文字列が、文字列の大文字と小文字が異なるだけで別の時系列と異なる場合、それらの文字列は同じ時系列として扱われます。 詳細については、Prometheus のメトリックの概要に関する記事を参照してください。

メトリック データにギャップが表示されますが、これはなぜ発生するのですか?

ノードの更新中に、クラスター レベルのコレクターから収集されたメトリックのメトリック データに 1 分から 2 分のギャップが表示される場合があります。 このギャップは、データが実行されているノードが通常の更新プロセスの一環として更新されているために発生します。 この更新プロセスにより、指定された kube-state-metrics やカスタム アプリケーション ターゲットなどのクラスター全体のターゲットが影響を受けます。 これは、クラスターが手動または自動更新によって更新されるときに発生します。 この動作は想定されているものであり、実行されているノードが更新されるために発生します。 この動作は、いずれも推奨される警告ルールの影響を受けません。

次のステップ

Azure Monitor ワークスペースの概要
Azure Monitor ワークスペースを管理する
Prometheus 用 Azure Monitor マネージド サービスの概要
Azure Workbooks を使用して Prometheus メトリックにクエリを実行する