View a markdown version of this page

QueryMetrics - Amazon CloudWatch
URL クエリパラメータ必要な IAM 許可結果の制限リクエスト例レスポンス例

QueryMetrics

QueryMetrics オペレーションは、特定の時点において PromQL インスタントクエリを評価するか、一定期間にわたってクエリを評価します。

有効な HTTP 動詞

GET, POST

有効な URI:

/api/v1/query — 特定の時点でインスタントクエリを評価します。

/api/v1/query_range — 一定期間にわたってクエリを評価します。

完全なリクエスト URL は、AWS リージョンの CloudWatch モニタリングホストを、https://monitoring.AWS Region.amazonaws.com/api/v1/query などのオペレーションパスと組み合わせたものです。エンドポイント、署名、必要となる IAM アクセス許可については、「PromQL クエリ」を参照してください。

URL クエリパラメータ

次のパラメータは、GET リクエストの URL クエリ文字列、または POST リクエストのフォームエンコードされた本文フィールドとして渡されます。

パラメータ 適用対象 説明

query

[Both] (両方)

必須。評価する PromQL 式の文字列。式は、{"http.server.active_requests"} や {__name__="http.server.active_requests"} など、名前でメトリクスを選択する必要があります。メトリクス名のないラベルのみによる系列の選択はサポートされていません。

time

/api/v1/query

オプション。RFC 3339 タイムスタンプまたは Unix タイムスタンプとしての評価タイムスタンプ。デフォルトは現在のサーバー時間です。

start

/api/v1/query_range

必須。RFC 3339 タイムスタンプまたは Unix タイムスタンプとして、時間範囲の開始。

end

/api/v1/query_range

必須。RFC 3339 タイムスタンプまたは Unix タイムスタンプとして、時間範囲の終了。

step

/api/v1/query_range

必須。クエリのステップ幅解像度 (duration 形式または浮動小数点数の秒数)。

limit

[Both] (両方)

オプション。返される一意の時系列の最大数 (1 から 500 まで)。limit を指定しない場合、CloudWatch は最大 (500) まで返します。「結果の制限」を参照してください。

duration

Prometheus 互換 API の duration には、数値に続けて以下の単位のいずれかを指定します。

  • ms ミリ秒

  • s 秒

  • m 分

  • h 時間

  • d 日 (1 日は常に 24h と想定)

  • w 週 (1 週間は常に 7d と想定)

  • y 年 (1 年は常に 365d と想定)

必要な IAM 許可

QueryMetrics を呼び出すには、呼び出し元の ID に次の IAM アクションの両方が必要です。

  • cloudwatch:GetMetricData

  • cloudwatch:ListMetrics

すべての PromQL オペレーションの完全な IAM アクションマッピングについては、「PromQL の IAM アクセス許可」を参照してください。

結果の制限

単一の /api/v1/query または /api/v1/query_range レスポンスは、最大 500 個の一意の時系列を返すことができます。結果の個数を少なくするようにリクエストするには、1 から 500 の値で limit パラメータを渡します。limit を指定しない場合、CloudWatch は最大数を返します。

一致するシリーズが上限を超えると、レスポンスは打ち切られ、標準の Prometheus warnings フィールドにメッセージが含まれます。HTTP ステータスコードは 200 のままです。

TPS、同時実行数、24 時間スキャンウィンドウを含む PromQL 制限の完全なリストについては、「PromQL の制限と規制」を参照してください。

リクエスト例

次の POST リクエストは、フォームエンコードされた本文で PromQL 式を渡します。{、}、" などの特殊文字はパーセントエンコードされています。

POST /api/v1/query HTTP/1.1
Host: monitoring.us-east-1.amazonaws.com
Content-Type: application/x-www-form-urlencoded
Authorization: AUTHPARAMS
X-Amz-Date: 20260605T193725Z
User-Agent: awscurl/0.36

query=sum(%7B%22http.server.active_requests%22%7D)

同じ呼び出しに awscurl を使用:

awscurl --service monitoring --region us-east-1 \
    -X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/query' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'query=sum({"http.server.active_requests"})'

レスポンス例

正常なレスポンスでは、標準の Prometheus JSON エンベロープが次のように使用されます。

HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-abcd-4442-b8c5-262b45e9b535
Content-Type: application/json

{
    "status": "success",
    "data": {
        "resultType": "vector",
        "result": [
            {
                "metric": {},
                "value": [
                    1780000000.000,
                    "42"
                ]
            }
        ]
    }
}

結果セットが呼び出しごとの上限を超えると、CloudWatch は打ち切られた result 配列を返し、warnings フィールドにメッセージを含めます。

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "resultType": "vector",
        "result": [ ... up to 500 series ... ]
    },
    "warnings": [
        "result truncated to the maximum of 500 series; refine the query or use the limit parameter"
    ]
}