# PromQL クエリ
[メトリクスエンドポイント](CloudWatch-OTLPEndpoint.md#CloudWatch-MetricsEndpoint) 経由で 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 提供のメトリクス](CloudWatch-OTelEnrichment.md)。
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/](https://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 アクセス許可](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)」を参照してください。
Grafana を設定するには、以下のステップを実行します。
1. Grafana プラグインカタログから **Amazon Managed Service for Prometheus** データソースプラグインをインストールします。
1. Grafana で、**[接続]**、**[データソース]** の順に移動し、**[データソースを追加]** を選択し、**[Amazon Managed Service for Prometheus]** を選択します。
1. データソース **[URL]** を `https://monitoring.{{AWS Region}}.amazonaws.com` に設定します。
1. **[リージョン]** を自分の AWS リージョンに設定します。環境に適した **[認証プロバイダー]** (デフォルトの認証情報チェーン、アクセスキー、またはワークスペース IAM ロール) を選択します。
1. **[保存してテスト]** を選択します。
## 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 データソースに接続する](https://docs.aws.amazon.com/grafana/latest/userguide/amazon-prometheus-data-source.html)」を参照してください。
**IAM 前提条件** — Amazon Managed Grafana ワークスペース IAM ロールには、`cloudwatch:GetMetricData` (インスタントクエリと範囲クエリに必要) と `cloudwatch:ListMetrics` (系列とラベルの検出に必要) の両方が必要です。詳細については、「[PromQL の IAM アクセス許可](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)」を参照してください。
データソースを設定するには、次の手順に従います。
1. Amazon Managed Grafana ワークスペースで、**Amazon Managed Service for Prometheus** データソースを追加します。
1. データソース **[URL]** を `https://monitoring.{{AWS Region}}.amazonaws.com` に設定します。
1. **[リージョン]** を自分の AWS リージョンに設定します。Amazon Managed Grafana はワークスペース IAM ロールから認証情報を自動的に挿入します。静的キーを設定する必要はありません。
1. **[保存してテスト]** を選択します。
## MCP ツールを使用したクエリ
[CloudWatch MCP サーバー](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server/)は、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 用のツール](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server#tools-for-cloudwatch-promql)」を参照してください。
## HTTP API を使用したクエリ
Prometheus 互換 HTTP エンドポイントを直接呼び出すことで、プログラムで CloudWatch PromQL データをクエリすることもできます。リクエストは、`monitoring` をサービス名として使用して、[AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) で署名する必要があります。
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](CloudWatch-PromQL-APIs.md)」を参照してください。PromQL クエリが利用可能な AWS リージョンのリストについては、「[サポート対象の AWS リージョン](CloudWatch-PromQL.md#CloudWatch-PromQL-Regions)」を参照してください。各オペレーションに必要な IAM アクションについては、「[PromQL の IAM アクセス許可](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)」を参照してください。