使用 API 和 PromQL 查詢 Prometheus 指標

適用於 Prometheus 的 Azure 監視器受控服務會從 Azure Kubernetes 叢集收集計量，並將其儲存在 Azure 監視器工作區中。 Prometheus 查詢語言 （PromQL） 是一種功能查詢語言，可用來查詢和匯總時間序列數據。 使用 PromQL 以查詢和彙總儲存在 Azure 監視器工作區中的計量。

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

Prerequisites

若要使用 PromQL 查詢 Azure 監視器工作區，您需要：

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

Authentication

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

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

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

使用 Microsoft Entra ID 註冊應用程式

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

允許應用程式存取工作區

將監視數據讀取者角色指派給您的應用程式，以便從 Azure 監視器工作區查詢數據。

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

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

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

4. 在 [ 訪問控制 （IAM）] 頁面上，選取 [ 新增>角色指派]。

   

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

6. 選取 監視數據讀取器，然後選取 成員 選項卡。

   

7. 選擇 [選取成員]。

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

9. 選擇 [] 選取 []。

10. 選取檢閱+指派。

    

您已建立應用程式註冊，並授予它查詢 Azure Monitor 工作區數據的權限。 您現在可產生權杖並在查詢中使用。

要求權杖

在命令提示符中，或者使用用戶端如 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 Monitor 工作區概覽頁面上，尋找您的 Azure Monitor 工作區的查詢端點。

支援的 API

支援下列查詢。

即時查詢

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

路徑：/api/v1/query

Examples

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

Examples

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'

Series

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

路徑：/api/v1/series

Examples

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"}'

Labels

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

路徑：/api/v1/labels

Examples

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

Example

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

如需開放原始碼軟體 Prometheus API 的完整規格，請參閱 Prometheus HTTP API。

API 限制

除了 Prometheus 規格中所述的限制之外，還有下列限制：

• 任何時間序列擷取查詢（/series或/query或/query_range）都必須包含\_\_name\_\_標籤比對器。 意即，每個查詢的範圍必須設定為一個指標。 查詢中只能有一個 \_\_name\_\_ 標籤比對器。

• 查詢 /series 不支援正則表達式篩選。

• 支援的時間範圍：

  • /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 Monitor 工作區中所有保留的資料。

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

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

區分大小寫

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

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

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

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

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

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

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

避免重複的時間序列

Prometheus 不支援重複的時間序列。 Azure Managed Prometheus 會將這些呈現為 422 錯誤給使用者，而不是默默地捨棄重複的時間序列。 遇到這些錯誤的使用者應採取動作，以避免重複時間序列。

例如，如果使用者針對儲存於不同資源群組但匯入至相同AMW系統的兩個不同叢集使用相同的「叢集」標籤值，則應該重新命名其中一個標籤，以確保其唯一性。 此錯誤僅會在這個案例中，當兩個叢集中具有相同時間戳記和值的邊緣情況下出現。

您可以藉由新增唯一識別碼、重新檢測唯一設計的現有標籤，或使用 relabel_configs 在抓取時插入或修改標籤來解決此問題。

常見問題

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

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

使用 疑難解答指南 來瞭解如何從受控代理程式內嵌 Prometheus 計量。

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

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

我在計量數據中看到一些差距。 為什麼會發生此行為？

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

這是預期的行為，且不會影響任何建議的警示規則。

相關內容

• Azure 監視器工作區概觀
• 管理 Azure 監視器工作區
• 適用於 Prometheus 的 Azure 監視器受控服務概觀
• 透過 Azure 活頁簿查詢 Prometheus 指標