使用 API 和 PromQL 查詢 Prometheus 計量

2025-04-21

Azure 監視器適用於 Prometheus 的受管理服務會從 Azure Kubernetes 叢集收集計量，並將其儲存在 Azure 監視器工作區中。 PromQL (Prometheus 查詢語言) 是功能查詢語言，可讓您查詢和彙總時間序列資料。使用 PromQL 以查詢和彙總儲存在 Azure 監視器工作區中的計量。

本文說明如何透過 REST API 以使用 PromQL 查詢 Azure 監視器工作區。如需 PromQL 的詳細資訊，請參閱查詢 Prometheus。

先決條件

若要使用 PromQL 查詢 Azure 監視器工作區，您需要下列必要條件：

Azure Kubernetes 叢集或遠端 Kubernetes 叢集。
適用於 Prometheus 的 Azure 監視器受管理服務，可用於從 Kubernetes叢集抓取計量。
儲存 Prometheus 計量的 Azure 監視器工作區。

認證

若要查詢 Azure 監視器工作區，請使用 Microsoft Entra ID 進行驗證。 API 支援使用用戶端認證進行 Microsoft Entra 驗證。使用 Microsoft Entra ID 註冊用戶端應用程式，並要求權杖。

若要設定 Microsoft Entra 驗證，請遵循下列步驟：

使用 Microsoft Entra ID 註冊應用程式。
授權應用程式存取至 Azure 監視器工作區。
要求權杖。

使用 Microsoft Entra ID 註冊應用程式

若要註冊應用程式，請遵循註冊應用程式以要求授權令牌和使用 API 中的步驟。

允許應用程式存取工作區

將 監視資料讀者 角色指派到您的應用程式，使其能夠從 Azure Monitor 查詢資料。

在 Azure 入口網站中開啟 Azure 監視器工作區。
在 [概觀] 頁面上，記下查詢端點以用於 REST 要求。
選取 [存取控制 (IAM)]。
選取 [新增]，然後從 [存取控制 (IAM)] 頁面選取 [新增角色指派]。
在新增角色指派頁面上，搜尋監視。
選取 [監視資料讀取器]，然後選取 [成員] 索引標籤。
選取 [選取成員]。
搜尋您已註冊的應用程式並選取。
選擇 [] 選取 []。
選取檢閱+指派。

您已建立應用程式註冊，並指派存取權以便於從 Azure 監視器工作區查詢資料。您現在可產生權杖並在查詢中使用。

要求權杖

在命令提示字元中或使用像是 Insomnia 或 PowerShell 的 Invoke-RestMethod用戶端，傳送下列要求。

curl -X POST 'https://login.microsoftonline.com/<tenant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret>' \
--data-urlencode 'resource=https://prometheus.monitor.azure.com'

樣本回應本文：

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https:/prometheus.monitor.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

儲存回應中的存取權杖，以在下列 HTTP 要求中使用。

查詢端點

在 Azure 監視器工作區概觀頁面上尋找 Azure 監視器工作區的查詢端點。

支援的 API

下列查詢項目受到支援：

立即查詢

如需詳細資訊，請參閱立即查詢。

路徑：/api/v1/query

範例：

POST https://k8s-02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query
--header 'Authorization: Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=sum( \
    container_memory_working_set_bytes \
    * on(namespace,pod) \
    group_left(workload, workload_type) \
    namespace_workload_pod:kube_pod_owner:relabel{ workload_type="deployment"}) by (pod)'

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query?query=container_memory_working_set_bytes' 
--header 'Authorization: Bearer <access token>'

範圍查詢

如需詳細資訊，請參閱範圍查詢。

路徑：/api/v1/query_range

範例：

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range?query=container_memory_working_set_bytes&start=2023-03-01T00:00:00.000Z&end=2023-03-20T00:00:00.000Z&step=6h'
--header 'Authorization: Bearer <access token>

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range' 
--header 'Authorization: Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=up' 
--data-urlencode 'start=2023-03-01T20:10:30.781Z' 
--data-urlencode 'end=2023-03-20T20:10:30.781Z' 
--data-urlencode 'step=6h'

數列

如需詳細資訊，請參閱數列。

路徑：/api/v1/series

範例：

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series' 
--header 'Authorization: Bearer <access token>
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'match[]=kube_pod_info{pod="bestapp-123abc456d-4nmfm"}'

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series?match[]=container_network_receive_bytes_total{namespace="default-1669648428598"}'

標籤值

如需詳細資訊，請參閱標籤值。

路徑：/api/v1/label/__name__/values.

備註

__name__ 是此 API 唯一支援版本，並傳回所有計量名稱。不支援其他 /api/v1/label/<label_name>/values。

範例︰

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/label/__name__/values'

如需 OSS prom API 的完整規格，請參閱 Prometheus HTTP API。

API 限制

除了 Prometheus 規格中詳述的限制外，還有下列限制。

查詢的範圍必須設定為計量。

任何時間序列擷取查詢 (/series 或 /query 或 /query_range) 必須包含 __name__ 標籤比對器。意即，每個查詢的範圍必須設定為一個指標。查詢中僅可有一個 __name__ 標籤比對器。
查詢/序列不支援規則運算式篩選
支持的時間範圍
- /query_range API 支援 32 天時間範圍。這是允許的時間範圍上限，包含查詢本身指定的範圍選取器。例如，查詢過去 24 小時的資料 rate(http_requests_total[1h]，實際上意味著查詢範圍涵蓋了 25 小時。這來自 24 小時範圍，加上查詢本身指定的 1 小時。
- /series API 擷取 12 小時時間範圍上限的資料。如果未提供 endTime，endTime = time.now()。如果時間範圍大於 12 小時，則 startTime 設定為 endTime – 12h。
忽略的時間範圍

系統忽略 /labels 和 /label/__name__/values 提供的開始時間和結束時間，並查詢 Azure 監視器工作區中保留的所有資料。
實驗性功能

不支援範例等實驗性功能。

如需 Prometheus 計量限制的詳細資訊，請參閱 Prometheus 計量。

區分大小寫

Azure 監視器適用於 Prometheus 的受管理服務是不區分大小寫的系統。如果字串 (例如計量名稱、標籤名稱或標籤值) 與其他時間序列的區別只有字串的大小寫不同，則系統會將這些字串視為相同的時間序列。

備註

此行為與原生開放原始碼 Prometheus 不同，這是區分大小寫的系統。在 Azure 虛擬機器、虛擬機器擴展集或 Azure Kubernetes Service 叢集中執行的自我管理的 Prometheus 執行個體是區分大小寫的系統。

在 Prometheus 的受控服務中，下列時間序列會視為相同：

diskSize(cluster="eastus", node="node1", filesystem="usr_mnt")
diskSize(cluster="eastus", node="node1", filesystem="usr_MNT")

上述範例是時間序列資料庫中的單一時間序列。下列考量適用：

針對這些時間序列擷取的任何樣本也將儲存，就像其是針對單一時間序列抓取或擷取的樣本。
如果上述範例是以相同時間戳記擷取，則會隨機捨棄其中一個樣本。
時間序列資料庫中儲存並由查詢傳回的大小寫無法預測。相同的時間序列在不同的時間可能會傳回不同的大小寫。
在查詢中存在的任何度量名稱或標籤名稱/值配對器，皆透過不區分大小寫的比較，從時間序列資料庫中擷取。如果查詢中有區分大小寫的比對器，則會在字串比較中自動視為不區分大小寫的比對器。

最佳做法是使用單一一致的案例來產生或抓取時間序列。

開放原始碼 Prometheus 會將上述範例視為兩個不同的時間序列。針對時間序列抓取或擷取的任何樣本將個別儲存。

常見問題

本節提供常見問題的解答。

我遺漏所有或部分計量。如何進行疑難排解？

您可以使用疑難解答指南，從受控代理程式擷取 Prometheus 計量。

為什麼我缺少具有相同名稱但大小寫不同的兩個標籤的度量數據？

Azure 管理 Prometheus 系統是不區分大小寫的。如果字串 (例如計量名稱、標籤名稱或標籤值) 與其他時間序列的區別只有字串的大小寫不同，則系統會將這些字串視為相同的時間序列。如需詳細資訊，請參閱 Prometheus 計量概觀。

我發現計量資料有一些差距，為什麼會發生此狀況？

在節點更新期間，對於從我們的叢集層級收集器所收集的計量，計量資料可能會出現 1 分鐘到 2 分鐘的差距。在正常更新過程中，由於執行資料的節點正在進行更新，因此會出現此間隙。此更新程序會影響整個叢集的目標，例如 kube-state-metrics 和指定的自訂應用程式目標。手動或透過自動更新來更新您的叢集時，就會發生這種情況。這是預期的行為，發生的原因是其執行所在的節點正在更新。此行為不會影響任何建議的警示規則。

後續步驟

Azure 監視器工作區概觀管理 Azure 監視器工作區 Azure 監視器受控服務概觀使用 Azure 活頁簿查詢 Prometheus 指標

共用方式為

使用 API 和 PromQL 查詢 Prometheus 計量

先決條件

認證

使用 Microsoft Entra ID 註冊應用程式

允許應用程式存取工作區

要求權杖

查詢端點

支援的 API

立即查詢

範圍查詢

數列

標籤

標籤值

API 限制

區分大小寫

常見問題

我遺漏所有或部分計量。 如何進行疑難排解？

為什麼我缺少具有相同名稱但大小寫不同的兩個標籤的度量數據？

我發現計量資料有一些差距，為什麼會發生此狀況？

後續步驟

意見反應

其他資源

我遺漏所有或部分計量。如何進行疑難排解？