# PromQL クエリ
<a name="CloudWatch-PromQL-Querying"></a>

OpenTelemetry Protocol (OTLP) 経由で 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 メトリクスのクエリ
<a name="CloudWatch-PromQL-Querying-Vended"></a>

PromQL で提供された AWS メトリクスをクエリできるようにするには、まず提供されたメトリクスの OTel エンリッチメントを有効にする必要があります。以下を参照してください: [PromQL で提供されたメトリクスを有効にする](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` を選択します。

```
histogram_sum({Invocations, FunctionName="my-api-handler"})
```

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

```
histogram_sum(
  {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"})
```