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

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

當您透過 將 OpenTelemetry 指標擷取至 CloudWatch 時[指標端點](CloudWatch-OTLPEndpoint.md#CloudWatch-MetricsEndpoint)，階層式 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 擴充。請參閱：[AWS 以 OpenTelemetry 格式提供的指標](CloudWatch-OTelEnrichment.md)。

啟用 OTel 擴充後，透過 PromQL 和其他標籤可 AWS 查詢的指標。指標名稱與原始 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` | 

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

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

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

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

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

您可以透過新增 Amazon Managed Service for Prometheus 資料來源外掛程式並將其指向 CloudWatch 監控端點，從 Grafana 查詢 CloudWatch PromQL 資料。 **** CloudWatch SigV4 簽署內建於外掛程式，且一律啟用，因此沒有開啟的切換。外掛程式發佈於 [grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/](https://grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/)：//。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 查詢
<a name="CloudWatch-PromQL-Querying-AMG"></a>

您可以透過新增指向 CloudWatch 監控端點的 Amazon Managed Service for Prometheus 資料來源，從 Amazon Managed Grafana 工作區查詢 CloudWatch PromQL 資料。 **** CloudWatch 此資料來源外掛程式會自動使用工作區 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 工具查詢
<a name="CloudWatch-PromQL-Querying-MCP"></a>

[CloudWatch MCP 伺服器](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server/)提供模型內容通訊協定 (MCP) 工具，可讓 AI 助理和開發工具代表您查詢 CloudWatch PromQL 資料。MCP 工具會自動處理身分驗證和請求格式，因此您可以專注於撰寫 PromQL 查詢，而不是管理 HTTP 請求和 SigV4 簽署。

下列 PromQL 工具可在 CloudWatch MCP 伺服器中使用：


| 工具 | 說明 | 
| --- | --- | 
| `execute_promql_query` | 執行即時 PromQL 查詢，並在單一時間點傳回指標值。 | 
| `execute_promql_range_query` | 在時段內執行 PromQL 範圍查詢，傳回用於趨勢分析和圖形的時間序列資料。 | 
| `get_promql_label_values` | 擷取特定 PromQL 標籤的值，例如`__name__`指標名稱或 `@resource.service.name`服務的值。 | 
| `get_promql_series` | 尋找符合 PromQL 標籤選擇器的時間序列，並傳回每個相符序列的完整標籤集。 | 
| `get_promql_labels` | 列出所有可用的 PromQL 標籤名稱，以協助探索指標的標籤結構。 | 

如需參數、組態和設定指示的完整詳細資訊，請參閱 [ CloudWatch MCP Server 文件中的適用於 CloudWatch PromQL 的工具](https://awslabs.github.io/mcp/servers/cloudwatch-mcp-server#tools-for-cloudwatch-promql)。 CloudWatch 

## 使用 HTTP API 查詢
<a name="CloudWatch-PromQL-Querying-API"></a>

您也可以直接呼叫 Prometheus 相容 HTTP 端點，以程式設計方式查詢 CloudWatch PromQL 資料。請求必須使用 [AWS Signature 第 4 版](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)`monitoring`做為服務名稱來簽署。

PromQL 端點遵循模式 `https://monitoring.{{AWS Region}}.amazonaws.com/api/v1/{{operation}}`。例如，對於美國東部 （維吉尼亞北部） (us-east-1) 區域，即時查詢的端點為 `https://monitoring.us-east-1.amazonaws.com/api/v1/query`。

如需完整的 API 參考，包括支援的操作、請求參數和回應格式，請參閱 [與 Prometheu 相容的 API](CloudWatch-PromQL-APIs.md)。如需可使用 PromQL 查詢 AWS 的區域清單，請參閱 [支援 AWS 的區域](CloudWatch-PromQL.md#CloudWatch-PromQL-Regions)。如需每個操作所需的 IAM 動作，請參閱 [PromQL 的 IAM 許可](CloudWatch-PromQL.md#CloudWatch-PromQL-IAM)。