View a markdown version of this page

PromQL 查詢 - Amazon CloudWatch
使用 PromQL 查詢已結束的 AWS 指標從 Grafana 查詢從 Amazon Managed Grafana 查詢使用 MCP 工具查詢使用 HTTP API 查詢

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

PromQL 查詢

當您透過 將 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 指標

若要能夠在 PromQL 中查詢已售出 AWS 指標，您必須先啟用已售出指標的 OTel 擴充。請參閱：AWS 以 OpenTelemetry 格式提供的指標。

啟用 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 查詢

您可以透過新增 Amazon Managed Service for Prometheus 資料來源外掛程式並將其指向 CloudWatch 監控端點，從 Grafana 查詢 CloudWatch PromQL 資料。 CloudWatch SigV4 簽署內建於外掛程式，且一律啟用，因此沒有開啟的切換。外掛程式發佈於 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 許可。

若要設定 Grafana，請完成下列步驟。

  1. 從 Grafana 外掛程式目錄中安裝 Amazon Managed Service for Prometheus 資料來源外掛程式。

  2. 在 Grafana 中，前往連線、資料來源，選擇新增資料來源，然後選取 Amazon Managed Service for Prometheus。

  3. 將資料來源 URL 設定為 https://monitoring.AWS Region.amazonaws.com。

  4. 將 區域設定為您的 AWS 區域。選擇適合您環境的身分驗證提供者 （預設憑證鏈、存取金鑰或工作區 IAM 角色）。

  5. 選擇儲存並測試。

從 Amazon Managed Grafana 查詢

您可以透過新增指向 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 資料來源。

IAM 先決條件 — Amazon Managed Grafana 工作區 IAM 角色必須同時具有 cloudwatch:GetMetricData（即時和範圍查詢需要） 和 cloudwatch:ListMetrics（系列和標籤探索需要）。如需詳細資訊，請參閱PromQL 的 IAM 許可。

若要設定資料來源，請完成下列步驟。

  1. 在您的 Amazon Managed Grafana 工作區中，新增 Amazon Managed Service for Prometheus 資料來源。

  2. 將資料來源 URL 設定為 https://monitoring.AWS Region.amazonaws.com。

  3. 將 區域設定為您的 AWS 區域。Amazon Managed Grafana 會自動從工作區 IAM 角色注入登入資料；您不需要設定靜態金鑰。

  4. 選擇儲存並測試。

使用 MCP 工具查詢

CloudWatch MCP 伺服器提供模型內容通訊協定 (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 的工具。 CloudWatch

使用 HTTP API 查詢

您也可以直接呼叫 Prometheus 相容 HTTP 端點，以程式設計方式查詢 CloudWatch PromQL 資料。請求必須使用 AWS Signature 第 4 版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。如需可使用 PromQL 查詢 AWS 的區域清單，請參閱 支援 AWS 的區域。如需每個操作所需的 IAM 動作，請參閱 PromQL 的 IAM 許可。