Azure 诊断实战：使用 Azure Resource Graph（ARG）跨订阅排查资源健康与故障

Azure Resource Graph（ARG）是 Azure 平台提供的高速资源查询服务，支持通过 Kusto 查询语言（KQL）经az graph query命令跨订阅、跨资源组检索资源元数据、资源健康状态与服务健康事件。本文是 azure-diagnostics 技能（SKILL.md）中 Azure 诊断查询能力的核心参考，读者将掌握 ARG 的四张核心表结构、六类可直接复用的诊断查询模式，以及将 ARG 健康数据与 Azure Monitor 指标、日志查询相结合的完整排障工作流。

Azure Resource Graph 在诊断流程中的定位

在 azure-diagnostics 技能定义的"系统化诊断流程"中，第一步是识别症状，第二步便是检查资源健康——"Check resource health before deep-diving into logs"（先查资源健康，再深入日志）。这正是 ARG 的用武之地：它能在毫秒级响应内跨订阅扫描所有资源，回答"哪些资源处于不健康或降级状态""哪些部署卡在非成功状态""当前是否有活跃的服务健康事件"这类全局性问题，避免在逐一进入应用日志前做无谓的深挖。

ARG 查询的典型应用场景包括：

• 检查资源健康状态（可用性、降级、不可用）；
• 发现处于失败或停滞状态的部署（provisioningState 异常）；
• 查询活跃的 Azure 服务健康事件与事故；
• 在深入应用日志（App Insights / Log Analytics）之前，先做全局健康筛查。

查询方式与前置条件

通过 MCP 工具生成查询命令

在 azure-diagnostics 技能所服务的 Agent 环境中，可以使用extension_cli_generateMCP 工具，用自然语言描述诊断意图，自动生成对应的az graph query命令：

mcp_azure_mcp_extension_cli_generate intent: "query Azure Resource Graph to <describe what you want to diagnose>" cli-type: "az"

将<describe what you want to diagnose>替换为具体诊断目标（例如 "find all resources in degraded health state across subscriptions"），工具会返回可直接执行的 CLI 命令。

直接构造 CLI 命令

也可以手动构造查询，基本命令形态如下：

az graph query -q "<KQL>" --query "data[].{name:name, type:type}" -o table

• -q传入 KQL 查询字符串；
• --query "data[].{name:name, type:type}"使用 JMESPath 对返回的data数组做投影，只保留name与type字段；
• -o table以表格形式输出，便于人工阅读。

⚠️ 前置条件：安装 resource-graph 扩展

az graph query属于 Azure CLI 的扩展命令，首次使用前必须先安装扩展：

az extension add --name resource-graph

未安装该扩展时直接执行az graph query会报错提示命令不存在。

核心表：四张诊断数据源

ARG 将资源数据组织为若干逻辑表，诊断场景中最常用的是以下四张：

其中Resources是最基础的表，覆盖全部 ARM 资源类型；HealthResources对应microsoft.resourcehealth/availabilitystatuses类型；ServiceHealthResources对应microsoft.resourcehealth/events类型；ResourceContainers则用于按订阅、资源组或管理组维度做聚合与范围限定。

诊断查询模式（可直接复制使用）

以下六类查询模式覆盖了 Azure 生产环境排障中最常见的问题，均可直接复制到az graph query -q "<KQL>"中执行。

1. 跨资源检查资源健康状态

列出所有资源及其 Resource Health 可用性状态：

HealthResources | where type =~ 'microsoft.resourcehealth/availabilitystatuses' | project name, availabilityState=properties.availabilityState, reasonType=properties.reasonType

availabilityState字段取值通常为Available（可用）、Degraded（降级）、Unavailable（不可用）、Unknown（未知）；reasonType给出状态对应的原因类型，如平台故障或用户操作引发。

2. 找出处于不健康或降级状态的资源

在上一查询基础上增加过滤条件，只保留非Available的资源，并补充summary摘要字段：

HealthResources | where type =~ 'microsoft.resourcehealth/availabilitystatuses' | where properties.availabilityState != 'Available' | project name, state=properties.availabilityState, reason=properties.reasonType, summary=properties.summary

该查询是"先查资源健康，再深挖日志"流程中的关键一步：先通过它锁定不健康资源的清单与原因，再有针对性地进入对应服务的应用日志。

3. 查询活跃的服务健康事件

获取当前仍处于 Active 状态的 Azure 服务健康事件（如区域性服务中断公告）：

ServiceHealthResources | where type =~ 'microsoft.resourcehealth/events' | where properties.Status == 'Active' | project name, title=properties.Title, impact=properties.Impact, status=properties.Status

properties.Impact描述事件影响范围，properties.Title是事件标题。此查询常用于判断"问题是否源于 Azure 平台侧"——若存在匹配的活跃服务事件，则可优先等待平台恢复而非深挖自身应用。

4. 按预置状态查找失败/停滞的部署

定位provisioningState不为Succeeded的资源，用于发现失败的部署或卡住的资源变更：

Resources | where properties.provisioningState != 'Succeeded' | project name, type, resourceGroup, provisioningState=properties.provisioningState

provisioningState常见取值包括Succeeded、Failed、Creating、Updating、Deleting、Canceled等。此查询适用于排查"部署失败"类问题，可快速列出所有未成功完成预置的资源及其所属资源组。

5. 查找处于停止或错误状态的 App Service

专门针对microsoft.web/sites（App Service / Web App / Function App 的宿主资源类型）检查运行状态：

Resources | where type =~ 'microsoft.web/sites' | where properties.state != 'Running' | project name, state=properties.state, resourceGroup, location

properties.state反映站点运行状态（如Running、Stopped）。当站点表现为"无法访问"或"502/503"时，先用该查询确认站点本身是否处于停止状态，可参考 App Service 排障指南 继续排查启动命令、健康检查路径等。

6. 查找预置异常的 Container Apps

针对microsoft.app/containerapps（Azure Container Apps）检查预置状态：

Resources | where type =~ 'microsoft.app/containerapps' | where properties.provisioningState != 'Succeeded' | project name, provisioningState=properties.provisioningState, resourceGroup

Container Apps 的预置失败常与镜像拉取失败、注册表凭据缺失相关，可结合 Container Apps 排障指南 中az containerapp show --query "properties.configuration.registries"等命令做进一步定位。

实战延伸：用 ARG 关联查询 Function App 的监控组件

ARG 的价值不止于单表扫描，还体现在跨表 join能力上。在 functions/README.md 中，就有一次将 ARG 用于 Function App 诊断的完整实战：通过一条查询同时返回 Function App 关联的 App Insights 名称、检测密钥（instrumentationKey）、连接字符串与 Log Analytics 工作区：

az graph query -q " resources | where type =~ 'microsoft.web/sites' and name == '<func-app-name>' | project funcName=name, rg=resourceGroup | join kind=inner (resources | where type =~ 'microsoft.insights/components' | project appiName=name, rg=resourceGroup, instrumentationKey=properties.InstrumentationKey, connectionString=properties.ConnectionString, workspaceId=properties.WorkspaceResourceId) on rg | project funcName, appiName, instrumentationKey, connectionString, workspaceId " -o json

该查询以resourceGroup为连接键，将 Function App 与其同资源组下的 App Insights 组件做内连接，一次性拿到后续查询日志所需的全部监控组件信息，省去了多步 CLI 调用。需要注意的是，这种 join 按资源组匹配，若 App Insights 位于不同资源组，需退回使用az functionapp config appsettings list与az monitor app-insights component show的 CLI 兜底方案（详见 functions/README.md）。

查询技巧与注意事项

结合 azure-resource-graph.md 与 azure-diagnostics 技能的整体实践，以下技巧可显著提升查询效率与准确性：

• 使用=~做大小写不敏感的类型匹配：资源类型统一为小写（如microsoft.web/sites），=~可避免大小写不一致导致的漏匹配；
• 用properties.fieldName导航嵌套属性：资源的详细状态位于properties对象下，如properties.availabilityState、properties.provisioningState；
• 用--first N限制返回条数：大规模订阅下避免一次性拉取全量数据，先取前 N 条快速定位；
• 用--subscriptions限定订阅范围：默认查询所有可访问订阅，可通过该参数将查询聚焦到指定订阅 ID；
• 将 ARG 健康数据与 Azure Monitor 指标结合：ARG 回答"资源是否健康"，Azure Monitor 回答"性能表现如何"，两者互补才能还原完整画面；
• 先查HealthResources再深挖应用日志：若平台侧健康状态正常，问题大概率在应用层，此时再进入 App Insights / Log Analytics 查询（可参考 kql-queries.md 中的AppRequests、AppExceptions等 KQL 查询库）；
• 善用 MCP 工具组合：在 azure-diagnostics 技能中，ARG 查询通常与mcp_azure_mcp_applens（AI 驱动的根因诊断）、mcp_azure_mcp_monitor（日志与指标查询）、mcp_azure_mcp_resourcehealth（单资源健康状态）配合使用，形成"全局 ARG 筛查 → 单资源健康确认 → 日志/指标深挖"的完整链路。

小结

Azure Resource Graph 是 Azure 生产环境排障的"第一站"：通过az graph query配合四张核心表，即可在秒级完成跨订阅的资源健康、服务健康事件与预置状态的全局扫描。掌握本文的六类查询模式，并将其嵌入 azure-diagnostics 技能"先查健康、再深挖日志"的系统化流程，配合 Azure Monitor 指标与 KQL 查询库，即可高效定位 App Service、Container Apps、Function App 乃至 AKS 等各类 Azure 资源的故障根因。