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

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

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

Prerequisites

PromQL を使用して Azure Monitor ワークスペースにクエリを実行するには、次のものが必要です。

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

Authentication

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

Microsoft Entra 認証を設定するには、次の手順に従います。

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

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

アプリを登録するには、「アプリを 登録して承認トークンを要求し、API を操作する」の手順に従います。

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

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

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

2. [ 概要 ] ページで、REST 要求で使用するクエリ エンドポイントをメモします。

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

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

   

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

6. [ 監視データ 閲覧者] を選択し、[ メンバー ] タブを選択します。

   

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

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

9. Choose Select.

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

    

アプリの登録を作成し、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 要求で使用するために、応答のアクセス トークンを保存します。

Query endpoint

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

Supported APIs

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

Instant queries

詳細については、「 インスタント クエリ」を参照してください。

Path:/api/v1/query

Examples

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>'

Range queries

詳細については、「 範囲クエリ」を参照してください。

Path:/api/v1/query_range

Examples

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'

Series

詳細については、「 系列」を参照してください。

Path:/api/v1/series

Examples

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"}'

Labels

詳細については、「 ラベル」を参照してください。

Path:/api/v1/labels

Examples

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'

Label values

詳細については、「 ラベル値」を参照してください。

Path:/api/v1/label/__name__/values

Example

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

オープンソース ソフトウェア Prometheus API の完全な仕様については、 Prometheus HTTP API に関するページを参照してください。

API limitations

Prometheus 仕様に記載されている制限事項に加えて、次の制限事項があります。

• 時系列フェッチ クエリ (/series 、 /query 、または /query_range) には、 \_\_name\_\_ ラベル マッチャーが含まれている必要があります。 つまり、各クエリのスコープはメトリックに設定されている必要があります。 クエリに含めることができるラベル マッチャー \_\_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 メトリック」を参照してください。

Case sensitivity

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

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

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

前述の例は、時系列データベースの 1 つの時系列です。 次の考慮事項が適用されます。

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

時系列を生成またはスクレイピングするには、単一の一貫したケースを使用するのがベスト プラクティスです。

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

重複する時系列の回避

Prometheus では、重複する時系列はサポートされていません。 Azure Managed Prometheus では、重複する時系列を自動的に削除するのではなく、422 エラーとしてユーザーに表示されます。 これらのエラーが発生したユーザーは、時系列の重複を避けるためにアクションを実行する必要があります。

たとえば、ユーザーが異なるリソース グループに格納されているが、同じ AMW に取り込まれる 2 つの異なるクラスターに同じ "クラスター" ラベル値を使用する場合、一意にするためにこれらのラベルの一方の名前を変更する必要があります。 このエラーは、このシナリオでは、タイムスタンプと値が両方のクラスターで同じである場合にのみ発生します。

これを修正するには、一意の識別子ラベルを追加するか、一意であることを意図した既存のラベルを再挿入するか、 relabel_configs を使用してスクレーピング時にラベルを挿入または変更します。

よく寄せられる質問

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

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

トラブルシューティング ガイドを使用して、マネージド エージェントから Prometheus メトリックを取り込む方法について説明します。

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

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

メトリック データにいくつかのギャップが見られます。 この動作が発生するのはなぜですか?

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

この動作は想定されており、推奨されるアラート ルールには影響しません。

Related content

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