你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 API 和 PromQL 查询 Prometheus 指标

项目
10/15/2024

Azure Monitor 适用于 Prometheus 的托管服务会从 Kubernetes 群集收集指标并将其存储在 Azure Monitor 工作区内。 PromQL（Prometheus 查询语言）是一种功能查询语言，可用于查询和聚合时序数据。请使用 PromQL 来查询和聚合存储在 Azure Monitor 工作区中的指标。

本文介绍了如何使用 PromQL 通过 REST API 查询 Azure Monitor 工作区。有关 PromQL 的详细信息，请参阅查询 Prometheus。

先决条件

若要使用 PromQL 来查询 Azure Monitor 工作区，需要满足以下先决条件：

Azure Kubernetes 群集或远程 Kubernetes 群集。
Azure Monitor 适用于 Prometheus 的托管服务从 Kubernetes 群集抓取指标。
存储 Prometheus 指标的 Azure Monitor 工作区。

身份验证

要查询 Azure Monitor 工作区，请使用 Microsoft Entra ID 进行身份验证。 API 支持使用客户端凭据进行 Microsoft Entra 身份验证。使用 Microsoft Entra ID 注册客户端应用并请求令牌。

要设置 Microsoft Entra 身份验证，请执行以下步骤：

使用 Microsoft Entra ID 注册应用。
向该应用授予对你的 Azure Monitor 工作区的访问权限。
请求令牌。

使用 Microsoft Entra ID 注册应用

若要注册应用，请按照注册应用以请求授权令牌并使用 API 中的步骤进行操作

允许应用访问你的工作区

为应用分配监视数据读者角色，以便它可以从 Azure Monitor 工作区查询数据。

在 Azure 门户中打开你的 Azure Monitor 工作区。
在“概述”页面上，记下要在 REST 请求中使用的查询终结点。
选择“访问控制 (IAM)”。
在“访问控制(IAM)”页面中，依次选择“添加”、“添加角色分配”。
在“添加角色分配”页面上，搜索“监视”。
选择“监视数据读取者”，然后选择“成员”选项卡。
选择“选择成员”。
搜索你注册的应用，然后选择该应用。
选择“选择”。
选择“查看 + 分配”。

现已创建应用注册，并为其分配了从你的 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
示例：

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 or /query or /query_range) 都必须包含 __name__ 标签匹配器。也就是说，每个查询的范围必须限定为一个指标。一个查询中只能有一个 __name__ 标签匹配器。
Query /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，因为后者是区分大小写的系统。
在 Azure VM、VMSS 或 Azure Kubernetes 服务 (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 Monitor 工作区概述
 管理 Azure Monitor 工作区
 Azure Monitor 适用于 Prometheus 的托管服务概述
 使用 Azure 工作簿查询 Prometheus 指标

通过

使用 API 和 PromQL 查询 Prometheus 指标

先决条件

身份验证

使用 Microsoft Entra ID 注册应用

允许应用访问你的工作区

请求令牌

查询终结点

受支持的 API

即时查询

范围查询

系列

标签

标签值

API 限制

事例敏感性

常见问题解答

我缺少所有或部分指标。如何进行故障排除？

为什么我缺少具有名称相同但大小写不同的两个标签的指标？

指标数据中存在一些差距，为什么会这样？

后续步骤

反馈

其他资源

通过

使用 API 和 PromQL 查询 Prometheus 指标

先决条件

身份验证

使用 Microsoft Entra ID 注册应用

允许应用访问你的工作区

请求令牌

查询终结点

受支持的 API

即时查询

范围查询

系列

标签

标签值

API 限制

事例敏感性

常见问题解答

我缺少所有或部分指标。 如何进行故障排除？

为什么我缺少具有名称相同但大小写不同的两个标签的指标？

指标数据中存在一些差距，为什么会这样？

后续步骤

反馈

其他资源

我缺少所有或部分指标。如何进行故障排除？