PromQL を使用した提供された AWS メトリクスのクエリ Grafana からのクエリ Amazon Managed Grafana からのクエリ MCP ツールを使用したクエリ HTTP API を使用したクエリ

PromQL クエリ

メトリクスエンドポイント経由で OpenTelemetry メトリクスを CloudWatch に取り込むと、階層 OTLP データモデルは PromQL 互換ラベルにフラット化されます。このセクションでは、ラベル構造、これらのラベルをクエリするための PromQL 構文、および PromQL での UTF-8 サポートについて説明します。

注記

Prometheus 3 の PromQL は、メトリクス名とラベル名で完全な UTF-8 文字をサポートしています。OpenTelemetry セマンティック規則は service.name などの属性名にドットを使用するため、これは OTLP メトリクスにとって特に重要です。以前は、これらのドットは翻訳中にアンダースコアに置き換えられ、OTel 規則で定義されているものと Prometheus でクエリ可能なものとに不一致が生じていました。

CloudWatch で PromQL を使用する場合、@ プレフィックス規則は OTLP スコープラベルと標準の Prometheus ラベルを区別します。各スコープ内のフィールドは二重 @ プレフィックス (@resource.@schema_url など) を使用し、属性は @resource.service.name などの単一 @ スコーププレフィックスを使用します。データポイント属性は、標準の PromQL クエリとの下位互換性のためにベア (プレフィックスなし) アクセスもサポートしているので、例えば {"http.server.active_requests"} と {"@datapoint.@name"="http.server.active_requests"} は同等です。

PromQL 式は中括弧で囲まれ、メトリクス名とオプションのラベルマッチャーのセットを指定します。次の例では、http.server.active_requests メトリクスのすべての時系列を選択します。


{"http.server.active_requests"}

次の例では、OpenTelemetry リソース属性 http.server.active_requests が service.name に等しいメトリクス myservice のすべての時系列を選択します。


{"http.server.active_requests", "@resource.service.name"="myservice"}

1 つのクエリで複数のラベルマッチャーを組み合わせることができます。次の例では、OpenTelemetry リソース属性 service.name がすべての米国リージョンで myservice に等しい http.server.active_requests メトリクスのすべての時系列を選択します。


{"http.server.active_requests",
 "@resource.service.name"="myservice",
 "@aws.region"=~"us-.*"}

以下に、範囲クエリの例を示します。各時系列の指定された時間範囲内のすべてのデータポイントの平均値を計算します。


avg_over_time(
  {"http.server.active_requests",
   "@resource.service.name"="myservice"}[5m]
)

次の表は、各 OTLP スコープのプレフィックス規則をまとめたものです:

OTLP スコープ	フィールドプレフィックス	属性プレフィックス	例
リソース	`@resource.@`	`@resource.`	`@resource.service.name="myservice"`
計装スコープ	`@instrumentation.@`	`@instrumentation.`	`@instrumentation.@name="otel-go/metrics"`
データポイント	`@datapoint.@`	`@datapoint.` またはベア	`cpu="cpu0"`、または `@datapoint.cpu="cpu0"`
AWS 予約済み	該当なし	`@aws.`	`@aws.account_id="123456789"`

PromQL を使用した提供された AWS メトリクスのクエリ

PromQL で提供された AWS メトリクスをクエリできるようにするには、まず提供されたメトリクスの OTel エンリッチメントを有効にする必要があります。以下を参照してください: OpenTelemetry 形式の AWS 提供のメトリクス。

OTel エンリッチメントを有効にすると、提供された AWS メトリクスは、ラベルが追加されて PromQL 経由でクエリ可能になります。メトリクス名は元の CloudWatch メトリクス名と同じで、元の CloudWatch ディメンションはデータポイント属性として使用できます。次のラベルを使用できます (以下の例は EC2 インスタンス用です)。

PromQL ラベル	説明	例
`InstanceId`	データポイント属性としての元の CloudWatch ディメンション	`i-0123456789abcdef0`
`"@resource.cloud.resource_id"`	リソースの完全な ARN	`arn:aws:ec2:us-east-1:123456789012:instance/i-0123456789abcdef0`
`"@resource.cloud.provider"`	クラウドプロバイダー	`aws`
`"@resource.cloud.region"`	このメトリクスが発生した AWS リージョン	`us-east-1`
`"@resource.cloud.account.id"`	このメトリクスが発生した AWS アカウント ID	`123456789012`
`"@instrumentation.@name"`	ソースサービスを識別する計装スコープ名	`cloudwatch.aws/ec2`
`"@instrumentation.cloudwatch.source"`	ソースサービス識別子	`aws.ec2`
`"@instrumentation.cloudwatch.solution"`	エンリッチメントソリューション識別子	`CloudWatchOTelEnrichment`
`"@aws.tag.Environment"`	AWS リソースタグ	`production`
`"@aws.account"`	このメトリクスが取り込まれた AWS アカウント (システムラベル)	`123456789012`
`"@aws.region"`	このメトリクスが取り込まれた AWS リージョン (システムラベル)	`us-east-1`

次の例では、特定の Lambda 関数の Invocations を選択します。


{Invocations, FunctionName="my-api-handler"}

次の例では、特定のチームでタグ付けされたすべての関数の Lambda Errors を選択します。


{Errors, "@instrumentation.@name"="cloudwatch.aws/lambda", "@aws.tag.Team"="backend"}

次の例では、チーム別にグループ化された Lambda Invocations の合計を計算します。


sum by ("@aws.tag.Team")(
    {Invocations, "@instrumentation.@name"="cloudwatch.aws/lambda"}
)

次の例では、EC2 CPUUtilization メトリクスのすべての時系列を選択します。"@instrumentation.@name"="cloudwatch.aws/ec2" の使用法は、Amazon Relational Database Service などの他の AWS のサービスではなく、EC2 からの CPUUtilization と排他的に一致させることです。


histogram_avg({CPUUtilization, "@instrumentation.@name"="cloudwatch.aws/ec2"})

Grafana からのクエリ

Amazon Managed Service for Prometheus データソースプラグインを追加して CloudWatch モニタリングエンドポイントにポイントすることで、Grafana から CloudWatch PromQL データをクエリできます。SigV4 署名はプラグインに組み込まれており、常に有効になっているため、オンにする切り替えはありません。プラグインは grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/ で公開されています。データソースを追加する前に、Grafana プラグインカタログからインストールします。AMP プラグイン v3.0.0 には Grafana >=11.6.11 <12 || >=12.0.10 <12.1 || >=12.1.7 <12.2 || >=12.2.5 が必要です。

IAM 前提条件 — Grafana が使用する認証情報を持つ IAM プリンシパルには、cloudwatch:GetMetricData (インスタントクエリと範囲クエリに必要) と cloudwatch:ListMetrics (シリーズとラベルの検出に必要) の両方が必要です。詳細については、「PromQL の IAM アクセス許可」を参照してください。

Grafana を設定するには、以下のステップを実行します。

Grafana プラグインカタログから Amazon Managed Service for Prometheus データソースプラグインをインストールします。
Grafana で、[接続]、[データソース] の順に移動し、[データソースを追加] を選択し、[Amazon Managed Service for Prometheus] を選択します。
データソース [URL] を https://monitoring.AWS Region.amazonaws.com に設定します。
[リージョン] を自分の AWS リージョンに設定します。環境に適した [認証プロバイダー] (デフォルトの認証情報チェーン、アクセスキー、またはワークスペース IAM ロール) を選択します。
[保存してテスト] を選択します。

Amazon Managed Grafana からのクエリ

CloudWatch モニタリングエンドポイントを指す Amazon Managed Service for Prometheus データソースを追加することで、Amazon Managed Grafana ワークスペースから CloudWatch PromQL データをクエリできます。このデータソースプラグインは、ワークスペース IAM ロールを使用して SigV4 でリクエストに自動的に署名します。SigV4 は常に有効になっており、設定の切り替えはありません。プラグインは Amazon Managed Grafana バージョン 12 以降で使用できます。詳細については、「Amazon Managed Grafana ユーザーガイド」の「Amazon Managed Service for Prometheus データソースに接続する」を参照してください。

IAM 前提条件 — Amazon Managed Grafana ワークスペース IAM ロールには、cloudwatch:GetMetricData (インスタントクエリと範囲クエリに必要) と cloudwatch:ListMetrics (系列とラベルの検出に必要) の両方が必要です。詳細については、「PromQL の IAM アクセス許可」を参照してください。

データソースを設定するには、次の手順に従います。

Amazon Managed Grafana ワークスペースで、Amazon Managed Service for Prometheus データソースを追加します。
データソース [URL] を https://monitoring.AWS Region.amazonaws.com に設定します。
[リージョン] を自分の AWS リージョンに設定します。Amazon Managed Grafana はワークスペース IAM ロールから認証情報を自動的に挿入します。静的キーを設定する必要はありません。
[保存してテスト] を選択します。

MCP ツールを使用したクエリ

CloudWatch MCP サーバーは、AI アシスタントと開発ツールがユーザーに代わって CloudWatch PromQL データをクエリできるようにするモデルコンテキストプロトコル (MCP) ツールを提供します。MCP ツールは認証とリクエストのフォーマットを自動的に処理するため、HTTP リクエストと SigV4 署名を管理せずに、PromQL クエリの作成に集中できます。

次の PromQL ツールを CloudWatch MCP サーバーで使用できます。

ツール	説明
`execute_promql_query`	インスタント PromQL クエリを実行し、特定の時点でメトリクス値を返します。
`execute_promql_range_query`	PromQL 範囲クエリを時間枠にわたって実行し、トレンド分析とグラフ化のために時系列データを返します。
`get_promql_label_values`	メトリクス名として `__name__` やサービスとして `@resource.service.name` など、特定の PromQL ラベルの値を取得します。
`get_promql_series`	PromQL ラベルセレクタに一致する時系列を検索し、一致する各系列の完全なラベルセットを返します。
`get_promql_labels`	使用可能なすべての PromQL ラベル名を一覧表示して、メトリクスのラベル構造を検出するのに役立てます。

パラメータ、設定、セットアップ手順の詳細については、CloudWatch MCP サーバードキュメントの「CloudWatch PromQL 用のツール」を参照してください。

HTTP API を使用したクエリ

Prometheus 互換 HTTP エンドポイントを直接呼び出すことで、プログラムで CloudWatch PromQL データをクエリすることもできます。リクエストは、monitoring をサービス名として使用して、AWS Signature Version 4 で署名する必要があります。

PromQL エンドポイントはパターン https://monitoring.AWS Region.amazonaws.com/api/v1/operation に従います。例えば、米国東部 (バージニア北部) (us-east-1) リージョンの場合、インスタントクエリのエンドポイントは https://monitoring.us-east-1.amazonaws.com/api/v1/query です。

サポートされているオペレーション、リクエストパラメータ、レスポンス形式を含む完全な API リファレンスについては、「Prometheus 互換 API」を参照してください。PromQL クエリが利用可能な AWS リージョンのリストについては、「サポート対象の AWS リージョン」を参照してください。各オペレーションに必要な IAM アクションについては、「PromQL の IAM アクセス許可」を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

PromQL を使用してメトリクスをクエリする

Query Studio での PromQL クエリの実行