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

[アーティクル]
10/15/2024

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 認証を設定するには、次の手順を実行します。

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

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

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

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

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

Azure portal で Azure Monitor ワークスペースを開きます。
[概要] ページで、REST 要求で使うクエリエンドポイントを記録しておきます。
[アクセス制御 (IAM)] を選択します。
[追加] を選択してから、[アクセス制御 (IAM)] ページで [ロールの割り当てを追加] を選択します。
[ロールの割り当ての追加] ページで、"監視" を検索します。
[Monitoring Data Reader] (監視データ閲覧者) を選んでから、[メンバー] タブを選びます。
[メンバーの選択] を選びます。
登録したアプリを見つけて選びます。
[選択] を選択します。
[レビューと割り当て] を選択します。

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

トークンの要求

コマンドプロンプトで、または Insomnia や PowerShell の Invoke-RestMethod などのクライアントを使用して、次の要求を送信します

curl -X POST 'https://login.microsoftonline.com/<tenant 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.

Note

__name__ は、この API のサポートされている唯一のバージョンであり、すべてのメトリック名を返します。他の /api/v1/label/<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 は、大文字と小文字を区別しないシステムです。メトリック名、ラベル名、ラベル値などの文字列が、文字列の大文字と小文字が異なるだけで別の時系列と異なる場合、それらの文字列は同じ時系列として扱われます。

Note

大文字と小文字を区別するシステムであるネイティブオープンソース Prometheus ではこの動作は異なります。
Azure VM、VMSS、または Azure Kubernetes Service (AKS) クラスター内で実行されているセルフマネージド 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 メトリックにクエリを実行する

次の方法で共有

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

前提条件

認証

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

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

トークンの要求

クエリエンドポイント

サポート対象 API

インスタントクエリ

範囲クエリ

系列

ラベル

ラベルの値

API の制限

大文字小文字の区別

よく寄せられる質問

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

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

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

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

前提条件

認証

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

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

トークンの要求

クエリ エンドポイント

サポート対象 API

インスタント クエリ

範囲クエリ

系列

ラベル

ラベルの値

API の制限

大文字小文字の区別

よく寄せられる質問

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

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

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

次のステップ

フィードバック

その他のリソース

クエリエンドポイント

インスタントクエリ

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

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