使用 API 和 PromQL 查詢 Prometheus 計量

適用於 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 驗證，請遵循下列步驟：

1. 使用 Microsoft Entra ID 註冊應用程式。
2. 將應用程式的存取權授與 Azure 監視器工作區。
3. 要求權杖。

使用 Microsoft Entra ID 註冊應用程式

1. 若要註冊應用程式，請遵循註冊應用程式以要求授權權杖並使用 API 中的步驟

允許應用程式存取工作區

交監視資料讀者角色指派給應用程式，以便可從 Azure 監視器工作區查詢資料。

1. 在 Azure 入口網站中開啟 Azure 監視器工作區。

2. 在 [概觀] 頁面上，記下查詢端點以用於 REST 要求。

3. 選取 [存取控制 (IAM)]。

4. 選取 [新增]，然後從 [存取控制 (IAM)] 頁面選取 [新增角色指派]。

   

5. 在 [新增角色指派] 頁面上，搜尋 [監視]。

6. 選取 [監視資料讀者]，然後選取 [成員] 索引標籤。

   

7. 選取 [選取成員]。

8. 搜尋您要註冊的應用程式並選取。

9. 選擇選取。

10. 選取檢閱+指派。

    

您已建立應用程式註冊並指派存取權，以便可以從 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/labels
範例：

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

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

標籤值

如需詳細資訊，請參閱標籤值
路徑：/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 VM、VMSS 或 Azure Kubernetes Service （AKS） 叢集中執行的自我管理 Prometheus 實例是區分大小寫的系統。

在 Azure 受控 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 監視器工作區
適用於 Prometheus 的 Azure 監視器受控服務概觀
使用 Azure 活頁簿查詢 Prometheus 計量