# PromQL を使用してメトリクスをクエリする
**Topics**
+ [Prometheus クエリ言語 (PromQL) とは](#CloudWatch-PromQL-WhatIs)
+ [PromQL の制限と規制](#CloudWatch-PromQL-Limits)
+ [サポート対象の AWS リージョン](#CloudWatch-PromQL-Regions)
+ [PromQL の IAM アクセス許可](#CloudWatch-PromQL-IAM)
+ [PromQL クエリ](CloudWatch-PromQL-Querying.md)
+ [Query Studio での PromQL クエリの実行 (プレビュー)](CloudWatch-PromQL-QueryStudio.md)
+ [アラームでの PromQL の使用](CloudWatch-PromQL-Alarms.md)
**注記**
OTLP メトリクスの取り込み、PromQL クエリ、提供された AWS メトリクスの OTel エンリッチメント、および Query Studio はパブリックプレビューリリースであり、無料ですが、変更される可能性があります。
## Prometheus クエリ言語 (PromQL) とは
Prometheus クエリ言語 (PromQL) は、時系列データをリアルタイムで選択、集約、変換できる機能的なクエリ言語です。PromQL は当初は Prometheus 向けに設計されましたが、メトリクスの一般的なクエリ言語となっています。
Amazon CloudWatch は、OpenTelemetry Line Protocol (OTLP) を介して取り込まれたメトリクスや [AWS 提供のエンリッチされたメトリクスなどのメトリクス](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/aws-services-cloudwatch-metrics.html)をクエリするための PromQL をサポートしています。OTLP メトリクスを取り込むと、CloudWatch はリソース属性、計装スコープ、データポイント属性、AWS 固有のメタデータなど、テレメトリの完全なセマンティック構造を保持し、クエリ可能な PromQL ラベルとして公開します。
PromQL では、次のことを実行できます:
+ メトリクス名とラベルマッチャーで時系列を選択します。
+ 時系列全体に数学関数と演算子を適用します。
+ サービス、リージョン、アカウントなどのディメンション全体でメトリクスを集約します。
+ 計算レート、ヒストグラム、分位数、および移動平均。
PromQL クエリは、[Query Studio での PromQL クエリの実行 (プレビュー)](CloudWatch-PromQL-QueryStudio.md) で、また CloudWatch アラームを作成するためにインタラクティブに使用できます。詳細については、「[PromQL クエリ](CloudWatch-PromQL-Querying.md)」および「[アラームでの PromQL の使用](CloudWatch-PromQL-Alarms.md)」を参照してください。
**注記**
CloudWatch は、Prometheus 3.0 仕様に基づいて PromQL を使用します。これには、UTF-8 メトリクス名とラベル名のサポートが含まれます。
以下の概念は、CloudWatch で PromQL を使用するための基本概念です。
| 概念 | 説明 |
| --- | --- |
| **時系列** | メトリクス名と、*ラベル*と呼ばれる一連のキーと値のペアによって識別されるタイムスタンプ付きの値のストリーム。メトリクス名とラベルの一意の組み合わせはそれぞれ異なる時系列を形成します。 |
| **[インスタントベクトル]** | 各系列に 1 つのサンプルを含む一連の時系列。すべて同じタイムスタンプを共有します。`{"http.server.active_requests", "@resource.service.name"="myservice"}` などのクエリによって返されます。 |
| **[範囲ベクトル]** | 各系列の経時的なデータポイントの範囲を含む一連の時系列。括弧に時間セレクターを入れて作成します。例: `avg_over_time({"http.server.active_requests", "@resource.service.name"="myservice"}[5m])`。 |
| **ラベル** | 時系列にアタッチされたキーと値のペア。OTLP で取り込まれたメトリクスでは、ラベルはリソース属性、計装スコープ、データポイント属性、および AWS 固有のメタデータから導出されます。 |
| **[ラベルマッチャー]** | ラベル値で時系列をフィルタリングする中括弧内の式。完全一致 (`=`)、等しくない (`!=`)、正規表現一致 (`=~`)、負の正規表現一致 (`!~`) をサポートします。 |
| **[集約演算子]** | 複数の時系列をより少ない系列に結合する関数。一般的な演算子には、`sum`、`avg`、`min`、`max`、`count`、および `topk` が含まれます。 |
## PromQL の制限と規制
次の表に、PromQL の制限と規制を示します。
| 制限 | 値 | 追加情報 | エラーコード |
| --- | --- | --- | --- |
| アカウントあたりのクエリリクエストの最大 TPS | 300 | アカウントごとに許可される 1 秒あたりのクエリリクエスト (/query、/query\$1range) の最大数。 | 422 |
| アカウントあたりの検出リクエストの最大 TPS | 10 | アカウントごとに許可される 1 秒あたりの検出リクエスト (/series、/label、/label\$1values) の最大数。 | 422 |
| アカウントあたりの同時クエリリクエストの最大数 | 30 | アカウントが同時にアクティブに実行できるクエリ (/query、/query\$1range) の最大数。 | 429 |
| アカウントあたりの同時検出リクエストの最大数 | 30 | アカウントが同時にアクティブに実行できる検出リクエスト (/series、/labels、/label\$1values) の最大数。 | 429 |
| クエリリクエストごとに返される最大系列数 | 500 | クエリリクエスト (/query、/query\$1range) が返すことができる一意の時系列の最大数。 | 200 - 切り捨て後のレスポンス |
| 検出リクエストごとに返される最大ラベル数 | 10,000 | 検出リクエスト (/series、/labels、/label\$1values) が返すことができる一意のラベルの最大数。 | 200 - 切り捨て後のレスポンス |
| リクエストあたりの最大範囲 | 7 日間 | 範囲パラメータやルックバック期間など、クエリが実行できる最大時間範囲。 | 422 |
| 24 時間枠ごとにスキャンされる最大系列数 | 100,000 | クエリ実行の 24 時間枠ごとにスキャンできる一意の時系列の最大数。 | 422 |
| 24 時間枠ごとにスキャンされる最大サンプル数 | 300,000,000 | クエリ実行の 24 時間枠ごとにスキャンできるサンプルの最大数。 | 422 |
| 24 時間枠ごとに処理される最大サンプル数 | 3,000,000,000 | クエリ実行の 24 時間枠ごとに処理できるサンプルの最大数。 | 422 |
| 実行タイムアウト | 20 秒 | エンジンがクエリの評価に費やすことができる最大時間。キューに費やされた時間やストレージからのデータの取得は除きます。 | 422 |
## サポート対象の AWS リージョン
次の表に、OTLP メトリクスの取り込み、PromQL クエリ、および Query Studio が利用可能な AWS リージョンを示します。
| リージョン名 | リージョンコード | OTLP メトリクスの取り込み | PromQL クエリ | Query Studio |
| --- | --- | --- | --- | --- |
| 米国東部 (バージニア北部) | us–east–1 | ✓ | ✓ | ✓ |
| 米国西部 (オレゴン) | us-west-2 | ✓ | ✓ | ✓ |
| 欧州 (アイルランド) | eu-west-1 | ✓ | ✓ | ✓ |
| アジアパシフィック (シンガポール) | ap-southeast-1 | ✓ | ✓ | ✓ |
| アジアパシフィック (シドニー) | ap-southeast-2 | ✓ | ✓ | ✓ |
## PromQL の IAM アクセス許可
PromQL クエリを実行するには、`cloudwatch:GetMetricData` と `cloudwatch:ListMetrics` の両方のアクセス許可が必要です。次の表に、新しい PromQL API オペレーションとそれらの必要な IAM アクションを示します:
| API オペレーション: | 必須アクション |
| --- | --- |
| ExecuteMetricQueryPost | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` |
| ExecuteMetricQueryGet | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` |
| ExecuteMetricRangeQuery | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` |
| ExecuteMetricRangeQueryGet | `cloudwatch:GetMetricData`, `cloudwatch:ListMetrics` |
| ExecuteMetricSeriesPost | `cloudwatch:ListMetrics` |
| ExecuteMetricSeriesGet | `cloudwatch:ListMetrics` |
| ExecuteMetricLabelsPost | `cloudwatch:ListMetrics` |
| ExecuteMetricLabelsGet | `cloudwatch:ListMetrics` |
| ExecuteMetricLabelValuesGet | `cloudwatch:ListMetrics` |