本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# PromQL 查詢
<a name="CloudWatch-PromQL-Querying"></a>

當您透過 OpenTelemetry Protocol (OTLP) 將 OpenTelemetry 指標擷取至 CloudWatch 時，階層式 OTLP 資料模型會扁平化為與 PromQL 相容的標籤。本節說明標籤結構、用於查詢這些標籤的 PromQL 語法，以及 PromQL 中的 UTF-8 支援。

**注意**  
Prometheus 3 中的 PromQL 支援指標名稱和標籤名稱的完整 UTF-8 字元。這對 OTLP 指標特別重要，因為 OpenTelemetry 語意慣例在屬性名稱中使用點，例如 `service.name`。先前，這些點在轉譯期間取代為底線，導致 OTel 慣例中定義的內容與 Prometheus 中可查詢的內容之間存在差異。

在 CloudWatch 中使用 PromQL 時，`@`字首慣例會將 OTLP 範圍標籤與標準 Prometheus 標籤區分開來。每個範圍內的欄位都使用雙`@`字首 （例如 `@resource.@schema_url`)，而屬性則使用單一`@`範圍字首，例如 `@resource.service.name`。Datapoint 屬性也支援裸機 （無字首） 存取，以便與標準 PromQL 查詢回溯相容，例如 `{"http.server.active_requests"}`和 `{"@datapoint.@name"="http.server.active_requests"}` 相等。

PromQL 表達式是以大括號括住，指定指標名稱和一組選用的標籤比對器。下列範例會選取`http.server.active_requests`指標的所有時間序列：

```
{"http.server.active_requests"}
```

下列範例會選取 `http.server.active_requests` OpenTelemetry 資源屬性`service.name`等於 之指標的所有時間序列`myservice`：

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

您可以在單一查詢中結合多個標籤比對器。下列範例會選取`http.server.active_requests`指標的所有時間序列，其中 OpenTelemetry 資源屬性`service.name`在所有美國區域`myservice`相等：

```
{"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預留 | N/A | `@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 標籤 | Description | 範例 | 
| --- | --- | --- | 
| `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` | 

下列範例`Invocations`會針對特定 Lambda 函數選取 ：

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

下列範例`Errors`會為標記特定團隊的所有函數選取 Lambda：

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

下列範例會計算依團隊`Invocations`分組的 Lambda 總數：

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

下列範例會選取 EC2 `CPUUtilization` 指標的所有時間序列。的用途`"@instrumentation.@name"="cloudwatch.aws/ec2"`是完全符合來自 EC2 的 CPUUtilization，而不是來自其他 AWS 服務，例如 Amazon Relational Database Service：

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