使用 API 和 PromQL 查询 Prometheus 指标

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

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

Prerequisites

若要使用 PromQL 查询 Azure Monitor 工作区,需要:

  • Azure Kubernetes 群集或远程 Kubernetes 群集。
  • Azure Monitor 为 Prometheus 提供托管服务,从 Kubernetes 集群中收集指标数据。
  • 存储 Prometheus 指标的 Azure Monitor 工作区。

Authentication

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

若要设置Microsoft Entra 身份验证,请执行以下步骤:

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

使用 Microsoft Entra ID 注册应用

若要注册应用,请按照注册应用中的步骤 请求授权令牌并使用 API

允许应用访问你的工作区

将“监视数据读取者”角色分配给应用,以便它可以从 Azure Monitor 工作区查询数据。

  1. 在 Azure 门户中打开你的 Azure Monitor 工作区。

  2. “概述 ”页上,记下查询终结点,以便在 REST 请求中使用。

  3. 选择“访问控制(IAM)”

  4. “访问控制”(IAM)页上,选择添加>角色分配

    显示“Azure Monitor 工作区概述”页的屏幕截图。

  5. “添加角色分配 ”页上,搜索 “监视”。

  6. 选择“ 监视数据读取者”,然后选择“ 成员 ”选项卡。

    显示“添加角色分配”页的屏幕截图。

  7. 选择“选择成员”

  8. 搜索你注册的应用,然后选择该应用。

  9. Choose Select.

  10. 选择审核 + 分配

    显示“添加角色分配”页的屏幕截图,其中“选择成员”窗格处于打开状态。

你创建了应用注册,并为其分配了对 Azure Monitor 工作区中查询数据的访问权限。 现在,你可以生成令牌并将其用于查询。

请求令牌

在命令提示符中或使用客户端(如 Insomnia 或 PowerShell Invoke-RestMethod 命令)发送以下请求。

curl -X POST 'https://login.partner.microsoftonline.cn/<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.cn'

示例响应正文

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

保存响应中的访问令牌,以便在以下 HTTP 请求中使用。

Query endpoint

在 Azure Monitor 工作区 概述 页上查找 Azure Monitor 工作区的查询终结点。

显示 Azure Monitor 工作区“概述”页上的查询终结点的屏幕截图。

Supported APIs

支持以下查询。

Instant queries

有关详细信息,请参阅 即时查询

Path:/api/v1/query

Examples

POST https://k8s-02-workspace-abcd.chinanorth3.prometheus.monitor.azure.cn/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.chinanorth3.prometheus.monitor.azure.cn/api/v1/query?query=container_memory_working_set_bytes' 
--header 'Authorization: Bearer <access token>'

Range queries

有关详细信息,请参阅 范围查询

Path:/api/v1/query_range

Examples

GET 'https://k8s02-workspace-abcd.chinanorth3.prometheus.monitor.azure.cn/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.chinanorth3.prometheus.monitor.azure.cn/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

有关详细信息,请参阅 系列

Path:/api/v1/series

Examples

POST 'https://k8s02-workspace-abcd.chinanorth3.prometheus.monitor.azure.cn/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.chinanorth3.prometheus.monitor.azure.cn/api/v1/series?match[]=container_network_receive_bytes_total{namespace="default-1669648428598"}'

Labels

有关详细信息,请参阅 标签

Path:/api/v1/labels

Examples

GET 'https://k8s02-workspace-abcd.chinanorth3.prometheus.monitor.azure.cn/api/v1/labels'
POST 'https://k8s02-workspace-abcd.chinanorth3.prometheus.monitor.azure.cn/api/v1/labels'

Label values

有关详细信息,请参阅 “标签”值

Path:/api/v1/label/__name__/values

备注

此 API 唯一受支持的版本是 __name__,它返回所有指标名称。 不支持其他 /api/v1/label/<label_name>/values

Example

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

有关开源软件 Prometheus API 的完整规范,请参阅 Prometheus HTTP API

API limitations

除了 Prometheus 规范中所述的限制外,还有以下限制:

  • 任何时序提取查询(/series/query/query_range)都必须包含\_\_name\_\_标签匹配器。 也就是说,每个查询的范围必须限定为一个指标。 查询中只能有一个 \_\_name\_\_ 标签匹配器。

  • /series查询不支持正则表达式筛选器。

  • 支持的时间范围:

    • API /query_range 支持 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 指标

Case sensitivity

Azure Monitor 适用于 Prometheus 的托管服务是一个不区分大小写的系统。 如果字符串(例如指标名称、标签名称或标签值)与另一个时序的区别仅在于字符串的大小写,则它会将这些字符串视为相同的时序。

备注

此行为不同于本机开放源代码 Prometheus,因为后者是区分大小写的系统。 在 Azure 虚拟机、虚拟机规模集或 Azure Kubernetes 服务群集中运行的自托管 Prometheus 实例是区分大小写的系统。

在 Prometheus 的托管服务中,以下时序数据被视为相同:

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

前述示例是时序数据库中的单个时序。 请注意以下事项:

  • 任何针对它们引入的样本都会存储,如同它们是针对单个时间序列进行抓取或引入的一样。
  • 如果前述示例采用相同的时间戳引入,则会随机删除其中一个示例。
  • 存储在时间序列数据库中并通过查询返回的大小写不可预测。 同一时间序列可能在不同时间返回不同的大小写。
  • 通过不区分大小写的比较,可从时序数据库中检索查询中存在的任何指标名称或标签名称/值匹配器。 如果查询中存在区分大小写的匹配器,则在字符串比较中,会将其视为不区分大小写的匹配器。

最佳做法是使用统一的大小写来生成或抓取时间序列。

开源 Prometheus 会将前述示例视为两个不同的时序。 针对它们抓取或引入的任何样本都会单独进行存储。

常见问题

本部分提供常见问题的解答。

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

使用 故障排除指南 了解如何从托管代理引入 Prometheus 指标。

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

Azure 管理型 Prometheus 是一个不区分大小写的系统。 如果字符串(例如指标名称、标签名称或标签值)与另一个时序的区别仅在于字符串的大小写,则它会将这些字符串视为相同的时序。 有关详细信息,请参阅 Prometheus 指标概述

我看到指标数据存在一些差距。 为什么会发生此行为?

在节点更新期间,对于从群集级别收集器收集的指标,可能会发现指标数据存在一分钟到两分钟的差距。 发生此差距的原因是运行数据的节点正在作为正常更新过程的一部分进行更新。 此更新过程影响整个群集范围内的目标,例如 kube-state-metrics 和指定的自定义应用程序目标。 当群集手动更新或通过自动更新时,将发生此过程。

此行为是预期的,不会影响我们推荐的任何警报规则。