Azure Monitor 工作区的资源范围查询

本文介绍如何在特定 Azure 资源的上下文中查询 Azure Monitor 工作区指标，而不是直接查询工作区。 通过面向资源的查询，可以查询您有权限访问的资源指标，而无需直接访问底层的 Azure Monitor 工作区。

概述

资源范围的查询提供了一种更灵活、更安全的方式来访问 Azure Monitor 工作区中存储的指标：

• 按资源上下文查询：查询范围限定为特定 Azure 资源、资源组或订阅的指标
• 简化的访问控制：用户只需要对所监视的资源进行读取访问权限，而不是工作区本身（适当配置工作区时）
• 自动资源发现：无需知道哪个工作区包含给定资源的指标
• 增强安全性：通过限制对已授权资源的指标可见性，遵循最低特权访问原则

先决条件

• 一个或多个 Azure 资源将指标发送到 Azure Monitor 工作区
• 配置为接收指标的 Azure Monitor 工作区
• 所需的相应 Azure RBAC 权限 用于要查询的资源
• 了解 PromQL 基础知识

资源范围与工作区范围查询的比较

查询终结点和身份验证

区域查询终结点

资源范围的查询使用区域终结点，该终结点会自动将请求路由到相应的工作区（s）：

https://query.<region>.prometheus.monitor.azure.com

示例：

• https://query.centralus.prometheus.monitor.azure.com
• https://query.westeurope.prometheus.monitor.azure.com

范围标头

要进行资源范围查询，需要 HTTP 标头来指定范围。

示例：

# Resource scope
x-ms-azure-scoping: /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Compute/virtualMachines/{vm-name}

# Resource group scope  
x-ms-azure-scoping: /subscriptions/{subscription-id}/resourceGroups/{resource-group}

# Subscription scope
x-ms-azure-scoping: /subscriptions/{subscription-id}

Authentication

资源范围内的查询支持以下身份验证方法：

• Microsoft Entra ID （以前为 Azure AD）：用户凭据或服务主体
• 托管标识：系统分配的或用户分配的托管标识

已验证标识必须对被查询的资源拥有监视读取者角色（或更高权限）。

资源维度

从 2024 年 9 月起，Azure Monitor 会自动标记通过 Azure Monitor 代理引入的指标的以下维度：

维度可见性

• 资源范围的查询：所有 Microsoft.* 维度都可见，可在 PromQL 查询中使用
• 工作区范围的查询：默认情况下，仅显示Microsoft.resourceid，以减少容器为中心场景中的混淆。

查询示例

基于资源范围的基本查询

# Query CPU utilization for a specific VM
curl -X GET \
  'https://query.eastus.prometheus.monitor.azure.com/api/v1/query?query=avg({"system.cpu.utilization"})+by+("Microsoft.resourceid")' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-ms-azure-scoping: /subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/prod-rg/providers/Microsoft.Compute/virtualMachines/vm-01'

资源组范围

# Query all VMs in a resource group
avg({"system.cpu.utilization"}) by ("Microsoft.resourceid")

添加标头：

x-ms-azure-scoping: /subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/prod-rg

订阅范围与筛选

# Query specific resource types across a subscription
avg({"system.cpu.utilization"}) by ("Microsoft.resourceid")
{
  "Microsoft.resourcetype"="Microsoft.Compute/virtualMachines"
}

添加标头：

x-ms-azure-scoping: /subscriptions/12345678-1234-1234-1234-123456789012

与 Grafana 一起使用

1. 在 Grafana 中创建新的 Prometheus 数据源。
2. 将 Prometheus 服务器 URL 设置为 https://query.eastus.prometheus.monitor.azure.com （或区域）。
3. 配置身份验证：
   • 对于 Azure 托管 Prometheus 数据源：使用 Azure 身份验证。
   • 对于开源 Prometheus 数据源：使用具有监视读取者角色的托管标识。
4. 添加自定义 HTTP 标头：
   • 键：x-ms-azure-scoping
   • 值：资源 ID、资源组 ID 或订阅 ID

Grafana 变量的示例：

为动态范围创建变量：

• 名称：ResourceScope
• 类型：Custom
• 值：资源 ID 或订阅 ID 的列表

将 ${ResourceScope} 用作标头值，以便在不复制仪表板的情况下在资源之间切换。

所需的权限

资源范围查询

经过身份验证的标识必须对要查询的资源具有以下角色之一：

• 监视读取器 （最低，建议）
• Reader
• Contributor
• Owner

工作区访问模式依赖项

资源范围的查询行为取决于工作区 访问控制模式：

支持的方案

以下 Azure Monitor 体验支持资源范围查询：

门户体验

• 指标边栏选项卡：查看资源（VM、AKS、应用服务等）的指标时，单击“在编辑器中查看 AMW 指标”以使用 PromQL 进行查询
• 仪表板：使用 PromQL 编辑器创建资源范围的指标图表
• 工作簿：在工作簿查询中引用资源范围的指标

Grafana

• 创建范围限定为订阅、资源组或单个资源的仪表板
• 使用 Grafana 变量动态切换资源范围
• 利用 Azure 托管 Prometheus 数据源进行简化身份验证

警报

• 指标警报：通过统一警报控制平面创建资源范围的 Prometheus 警报
• Prometheus 规则组：定义限定于特定资源的录制规则和警报规则

精心策划的体验

资源范围查询是以下功能的默认设置：

• VM Insights v2：存储在 Azure Monitor 工作区中的 OpenTelemetry 系统指标（性能计数器）
• Application Insights：将 OpenTelemetry 的 HTTP 和 RPC 指标存储在 Azure Monitor 工作区中
• 容器见解：正式发布后迁移到资源范围模型

错误处理

资源范围的查询可能会返回以下错误：

缺少身份验证标头

HTTP 401 未授权

{
  "error": {
    "code": "AuthenticationFailed",
    "message": "Authentication failed. The 'Authorization' header is missing."
  }
}

解决方案：在Authorization标头中包含有效的Bearer令牌。

缺少或无效的范围标头

HTTP 400 错误请求

{
  "error": {
    "code": "BadArgumentError",
    "message": "The 'x-ms-azure-scoping' header is missing or malformed."
  }
}

解决方案：验证 x-ms-azure-scoping 标头是否包含有效的 Azure 资源 ID、资源组 ID 或订阅 ID。

权限不足

HTTP 403 禁止访问

{
  "error": {
    "code": "InsufficientAccessError",
    "message": "The provided credentials have insufficient access to perform the requested operation",
    "innererror": {
      "code": "AuthorizationFailedError",
      "message": "User does not have access to read metrics for this resource"
    }
  }
}

解决方案：验证已验证标识对范围标头中指定的资源拥有监视读取者角色（或更高权限）。 如果工作区处于“需要工作区权限”模式，请验证对工作区的访问权限。

无效令牌

HTTP 403 禁止访问

{
  "error": {
    "code": "InvalidAuthenticationToken",
    "message": "The access token is invalid."
  }
}

解决方案：确保令牌有效、未过期，并为正确的资源获取令牌。 如果使用 Grafana，请确保用于配置数据源的托管标识对查询的资源具有适当的访问权限。 在验证访问权限时，还应考虑查询的范围（订阅、资源组或资源）。

查询语法错误

HTTP 400 错误请求 或 HTTP 422 不可处理实体

{
  "error": {
    "code": "QueryValidationError",
    "message": "Failed parsing the query"
  }
}

解决方案：验证 PromQL 语法。 有关查询语法的参考，请参阅 PromQL 文档，或使用 Copilot 浏览 PromQL 查询的最佳实践。

查询超时值

HTTP 503 服务不可用

{
  "status": "error",
  "errorType": "timeout",
  "error": "query timed out"
}

解决方案：简化查询、减少时间范围，或使用 记录规则 预先聚合数据。

未返回任何数据

HTTP 200 正常， 结果为空

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": []
  }
}

可能的原因：

• 在查询的时间范围内，指定资源没有指标。
• 指标未加上 Microsoft.resourceid 维度标签（只有通过 Azure Monitor 代理引入的指标会自动标记）
• 范围标头中的资源 ID 与存储指标中的值不匹配Microsoft.resourceid

解决方案：验证数据引入、使用工作区范围的查询检查维度值，并确认范围标头与实际资源 ID 匹配。

最佳做法

1. 默认使用订阅范围：在订阅级别上查询，并按"Microsoft.resourcetype"或"Microsoft.resourceid"进行筛选，以提高灵活性。

2. 按资源 ID 分组：在聚合中始终包含by ("Microsoft.resourceid")以保持资源级别的细化程度

   avg({"system.cpu.utilization"}) by ("Microsoft.resourceid")
   

3. 利用记录规则：对于复杂或频繁运行的查询，请使用记录规则来预先聚合数据，从而减少查询负载。

4. 配置工作区访问模式：将工作区设置为“使用资源或工作区权限”模式以启用真正的资源范围访问

5. 来自同一区域的查询：跨区域查询工作时，从工作区所在的同一区域查询可提供最佳性能

6. 在 Grafana 中使用托管标识：对于 Grafana 部署，请使用托管标识认证来避免凭据管理

常见应用场景

应用程序团队监控

场景：Jane 管理一个跨越多个 VM 的应用程序，但她无权访问中央监视工作区。

解决方案：Jane 的标识在其资源组上拥有监视读取者权限。 她使用以下方法创建 Grafana 仪表板：

• Prometheus URL： https://query.eastus.prometheus.monitor.azure.com
• 范围标头： /subscriptions/{sub-id}/resourceGroups/jane-app-rg

她可以在没有工作区访问权限的情况下查询其资源的所有指标。

多租户监视

方案：Bob 管理多个应用程序团队的基础结构，需要向每个团队授予仅对其资源的访问权限。

解决方案：

1. Bob 使用“使用资源或工作区权限”访问模式配置中心工作区。
2. 每个团队在其资源组上都获得“监视读取者”角色。
3. 团队使用资源组 ID 创建资源范围查询。
4. Bob 维护工作区范围查询以进行跨团队监视。

Kubernetes 命名空间隔离

方案：Tim 可以访问特定的 AKS 命名空间，但无法访问整个群集。

解决方案：Tim 使用命名空间资源 ID 查询：

x-ms-azure-scoping: /subscriptions/{sub-id}/resourceGroups/{rg}/providers/Microsoft.ContainerService/managedClusters/{cluster}/namespaces/{namespace}

他可以为命名空间创建警报和仪表板，而无需访问群集范围的指标。

局限性

• 逗号分隔的范围：目前不支持在单个请求中查询多个不相关的资源（逗号分隔的资源 ID）。
• 非 Azure 资源：资源范围的查询需要 Azure 资源 ID。 支持已启用 Arc 的资源。
• 维度标记：只有通过 Azure Monitor 代理引入的指标（自 2025 年 9 月以来）才会 Microsoft.* 自动标记维度。
• 跨工作区查询：支持资源范围内的隐式跨工作区查询，但只能同时查询最多 10 个 Azure Monitor 工作区。

相关内容

• 管理对 Azure Monitor 工作区的访问权限
• PromQL 在 OpenTelemetry 指标中的最佳实践
• 用于系统指标和性能计数器的 PromQL
• 使用 API 和 PromQL 查询 Prometheus 指标
• Azure Monitor 工作区概述