Azure 指标接入
当运维人员需要在 ONE 中查看 Azure 服务的监控指标时,可以通过 SmartGate 接入 Azure Monitor 数据,按资源查询指标并核对变化,确认数据能够用于后续性能分析和告警。
Azure 指标集成通过 Azure Resource Graph 发现目标资源,通过 Azure Monitor 的指标定义接口获取指标名称、聚合方式、粒度及维度,再读取指标数据。接入时按目标服务选择集成对象,配置订阅、认证信息和指标范围;本文以 Blob Storage 为例说明完整接入过程。
确认接入条件
开始配置前,先确认平台权限、SmartGate 环境和 Azure 源端数据均已准备就绪。
| 检查项 | 要求 |
|---|---|
| 平台权限 | 账号具有数据集成管理权限,并具有可用的数据接入相关 License |
| SmartGate 版本 | 已部署 SmartGate 4.3.0 或以上版本 |
| 支持系统架构 | Linux amd64 |
| 平台通信 | SmartGate 能够与 Bonree ONE 正常通信 |
| Azure 网络访问 | SmartGate 运行环境能够访问 Microsoft Entra ID、Azure Resource Manager 和目标区域的 Azure Monitor 指标接口 |
| Azure 认证 | 已准备具有目标订阅读取权限的 Microsoft Entra ID 应用服务主体及客户端密钥 |
| 资源提供程序 | 目标订阅已注册 Microsoft.Insights |
| 源端数据 | 目标资源已经向 Azure Monitor 提供需要采集的指标,所选时间范围内存在实际数据点 |
SmartGate 的部署方法见 SmartGate 安装。本文中的认证及网络配置以 Azure 公有云为例,所需地址包括 login.microsoftonline.com、management.azure.com 和目标区域的 *.metrics.monitor.azure.com,通过 HTTPS 访问。
采集读取 Azure Monitor 已提供的平台指标。缩短任务执行间隔不会提高源端指标的原始粒度,也不会自动产生资源尚未提供的指标。
配置 Azure 权限并获取认证信息
这一步为采集程序准备可用身份,并确保该身份能够发现和读取目标指标。Azure 侧权限应授予采集实际使用的应用服务主体。
注册应用并获取认证参数
- 登录 Azure 门户,进入 Microsoft Entra ID → 应用注册 → 新注册,在目标订阅所属租户中注册用于采集的应用。
- 打开应用的概述页面,记录目录(租户)ID 和应用程序(客户端)ID,分别填写到
tenant_id和client_id。 - 进入证书和密码 → 客户端密码 → 新客户端密码,填写说明并设置有效期,创建后立即保存客户端密码的值。
- 进入 订阅,选择目标资源所在订阅,在概述页面复制订阅 ID,填写到
subscription_id。
客户端密码的值用于 client_secret,不要填写密码 ID;该值仅在创建时显示。应在到期前更新采集使用的密钥。操作方法见 注册应用和创建客户端密码。
| 参数 | 是否必填 | 说明及获取方式 |
|---|---|---|
subscription_id | 是 | 目标资源所属订阅的订阅 ID;每个采集任务配置一个订阅 |
tenant_id | 是 | 应用概述中的目录(租户)ID |
client_id | 是 | 应用概述中的应用程序(客户端)ID,不是对象 ID |
client_secret | 与环境变量方式二选一 | 应用客户端密码的值;按平台组件表单要求填写 |
client_secret_env | 否 | client_secret 为空时,从该参数指定的环境变量读取密钥;默认变量名为 AZURE_CLIENT_SECRET |
显式填写的 client_secret 优先于环境变量。使用环境变量方式时,client_secret_env 填写变量名称,变量的值保存客户端密钥,并须在 SmartGate 采集进程的运行环境中可读取。操作人员本机上的环境变量不会自动供远端 SmartGate 使用。
配置订阅范围的读取权限
- 由具有角色分配权限的 Azure 管理员进入目标订阅 → 访问控制(IAM)。
- 选择添加角色分配,选择 Monitoring Reader 角色。
- 在成员中选择采集使用的应用服务主体,核对订阅范围和应用身份后完成分配。
- 进入同一订阅的资源提供程序,搜索
Microsoft.Insights;尚未注册时完成注册。
本集成使用 Azure Monitor 批量指标接口 metrics:getBatch,需要在订阅范围授予指标读取权限。仅在单个资源或资源组上分配角色,即使可以查看该资源的指标,也不能替代批量接口所需的订阅级授权。
角色分配方法见 Azure 门户中的角色分配,资源提供程序操作见资源提供程序注册。订阅授权及 Microsoft.Insights 要求见 Azure Monitor 批量指标接口说明。
选择采集对象并准备接入配置
这一步确定采集哪类资源、哪些指标,以及是否需要按维度拆分。不同 Azure 服务共用前面的认证授权步骤和后面的平台任务配置流程;一个任务对应一种服务类型和一个订阅。
选择服务集成
以下集成对象可按监控场景选择,实际可用指标取决于资源类型、服务配置及 Azure Monitor 已提供的数据。
| 集成对象 | type | 采集资源 | 主要指标及使用说明 |
|---|---|---|---|
| Azure Blob Storage | blob | 存储账户及 Blob 服务 | 事务数、流入流出、可用性、延迟和容量;账户与 Blob 服务属于不同资源层级 |
| Azure Files | files | 存储账户及 File 服务 | 文件服务事务、吞吐、延迟、容量及配额;指标随存储配置有所不同 |
| Azure Cosmos DB | cosmosdb | Cosmos DB 数据库账户 | 请求、RU 消耗、延迟和存储;需要数据库或容器粒度时,先核对指标支持的维度 |
| Azure DNS | dns | DNS 区域及 DNS Private Resolver | DNS 查询和解析器指标;区域与解析器的指标粒度不同 |
| Azure Database for PostgreSQL | postgresql | PostgreSQL 灵活服务器 | CPU、内存、存储、连接和 I/O;增强指标依赖源端启用相应功能 |
| Azure Virtual Network | vnet | 虚拟网络、网络接口、公网 IP 和 NAT 网关 | 网络流量、连接和相关状态;部分指标仅在对应网络功能启用后产生 |
| Azure VPN Gateway | vpngw | 虚拟网络网关 | VPN 隧道流量、连接和 BGP 状态;隧道指标依赖实际连接 |
Blob Storage 和 Azure Files 从存储账户发现对应服务子资源,资源 ID 分别以 /blobServices/default 和 /fileServices/default 结尾。Azure DNS 的解析器资源类型为 Microsoft.Network/dnsResolvers;不要将 DNS 记录集作为解析器资源。可用指标见 DNS Private Resolver 指标参考。
获取资源及指标信息
- 在 Azure 门户打开目标资源,记录所属订阅、资源组、区域和完整资源 ID。资源 ID 可从资源的属性或 JSON 视图获取。
- 进入资源的监视 → 指标,选择目标资源范围、指标命名空间、指标和聚合方式,确认近期存在数据点。
- 通过 Azure Monitor 指标定义接口或后文的 Azure CLI 命令,核对指标的 REST 名称、支持的聚合方式、数据粒度和维度,再填写采集配置。
门户中的指标显示名称可能经过本地化。include_metrics[].name 使用指标定义中的 name.value,应保留实际名称的大小写、空格和其他字符;不要直接使用翻译后的显示名称。
| 参数 | 是否必填 | 说明及获取方式 |
|---|---|---|
type | 是 | 采集服务类型,与所选集成一致,例如 blob、cosmosdb |
resource_groups | 否 | 资源组名称列表;默认 [],不按资源组限制采集范围 |
resource_ids | 否 | 完整 Azure 资源 ID 列表;默认 [],自动发现目标服务资源,不填写资源显示名称 |
include_metrics | 否 | 指标配置对象列表;未配置或为 [] 时,采集指标定义接口发现的指标 |
exclude_metrics | 否 | 排除的指标 REST 名称列表;默认 [],不排除指标 |
static_labels | 否 | 为指标补充固定标签,例如环境或业务归属 |
Azure 资源 ID 示例为 /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>。首次接入可先限定一个资源组,验证少量指标后再扩大范围。避免将同一指标同时放入包含列表和排除列表。
include_metrics 的每一项可以配置以下内容:
| 字段 | 是否必填 | 说明 |
|---|---|---|
name | 是 | 指标 REST 名称,例如 Transactions |
aggregation | 否 | 当前指标的聚合方式,可选 average、minimum、maximum、total、count,须为指标实际支持的方式 |
split_by | 否 | 按一个指定维度拆分时间序列,例如 ApiName;须为指标定义中支持的维度,未配置时不按此项拆分 |
output_name | 否 | 自定义输出指标名称;调整后须同步核对数据流及下游查询使用的名称 |
unit | 否 | 补充指标单位标识;填写单位本身不会执行数值换算 |
static_labels | 否 | 为当前指标补充固定标签;同名项覆盖任务级静态标签 |
使用 Blob Storage 接入示例
首次接入可选择已经有访问数据的 Blob Storage 资源,先采集事务数 Transactions 和端到端延迟 SuccessE2ELatency。前者使用 total,后者使用 average,避免将不同含义的指标统一设置为同一种聚合方式。
以下示例限定 rg-prod 资源组,采用环境变量读取客户端密钥。将订阅、租户、应用 ID 和资源组替换为实际值,并在所选 SmartGate 的运行环境中提供 AZURE_CLIENT_SECRET。使用平台表单填写客户端密钥时,按前文配置 client_secret。
type: blob
subscription_id: your subscription_id
tenant_id: your tenant_id
client_id: your client_id
client_secret_env: AZURE_CLIENT_SECRET
resource_groups:
- rg-prod
resource_ids: []
include_metrics:
- name: Transactions
aggregation: total
- name: SuccessE2ELatency
aggregation: average
exclude_metrics: []
data_delay_seconds: 60
lookback_seconds: 300
interval_seconds: 60
static_labels:
environment: prod
需要按 API 操作查看事务数时,可在 Transactions 配置项中增加 split_by: ApiName。本采集配置的 split_by 每项指定一个维度;拆分后会产生更多时间序列,应只为需要分析的指标启用。
Transactions 等请求类指标可提供分钟粒度的数据,容量类指标可能按小时或更长周期提供。添加容量指标前,应先核对其数据粒度,并相应扩大数据延迟和回溯窗口;不要直接套用本例的查询窗口。具体范围见 Blob 服务指标参考。
平台最终的指标名称、标签和单位以任务数据流的输出为准。核对数据时,应保留订阅、资源组、资源类型、资源名称和区域等资源信息,区分存储账户与 Blob 服务层级,避免将不同资源层级的同名指标直接合并。
在 ONE 中创建并启用任务
将准备好的 Azure 认证、采集对象和指标范围填写到平台,保存后检查任务及数据流,确保配置已下发并用于实际采集。
创建接入任务
- 进入 数据体系 → 数据集成 → 自定义集成,选择目标 Azure 服务卡片,例如 Azure Blob Storage,点击创建接入。
- 切换到配置页签,选择数据中心,填写任务名称,按实际数据权限要求配置数据标签。
- 点击添加组件,选择运行采集任务的 SmartGate,并按表单要求填写订阅、认证及采集参数。前面的 YAML 示例展示采集配置内容;使用环境变量读取密钥时,须确认所选 SmartGate 能读取该变量。
- 核对组件列表后点击保存,进入 数据体系 → 数据处理,按任务名称找到对应任务。
- 打开任务详情,检查数据流的输入、处理和输出配置,确认需要使用的版本处于部署状态,并核对指标名称、标签和单位。
- 检查任务启停状态。尚未启动时,在完成配置检查后启动任务,并核对 SmartGate 配置同步状态及状态更新时间。
完整平台操作见通过自定义集成创建数据任务,数据流编辑和发布见任务管理。集成卡片提供配套资源时,可按需安装并核对集成资源。
按需调整采集参数
采集执行间隔、指标数据粒度和查询窗口分别控制任务执行频率、源端数据的聚合粒度和读取时间范围。采集根据 Azure 指标定义选择可用粒度;先确认源端数据,再调整任务参数。
| 参数 | 是否必填 | 默认值及作用 |
|---|---|---|
default_aggregation | 否 | 未配置时使用指标定义的 primaryAggregationType;单个指标的 aggregation 优先于此项 |
data_delay_seconds | 否 | 默认 60 秒,查询结束时间相对当前时间向前偏移的时长 |
lookback_seconds | 否 | 默认 300 秒,从查询结束时间向前查询的时间窗口 |
interval_seconds | 否 | 默认 60 秒,采集任务执行间隔 |
timeout_seconds | 否 | 默认 15 秒,单次 Azure API 请求超时 |
retry_count | 否 | 默认 3,请求失败后的额外重试次数 |
schedule.jitter | 否 | 默认 true,分散多个任务的请求时间 |
例如,data_delay_seconds: 60、lookback_seconds: 300 表示查询窗口约为当前时间之前 6 分钟至 1 分钟。对于小时粒度或延迟更长的指标,仅增大 interval_seconds 不足以保证读到数据,还应扩大查询窗口,使其覆盖已经产生的数据点。
聚合方式按 include_metrics[].aggregation、default_aggregation、指标定义的 primaryAggregationType 的顺序确定。填写覆盖值前,先确认指标支持该聚合方式。
验证指标接入结果
先检查平台中是否存在目标资源的实际数据;结果不符合预期时,再通过 Azure API 区分身份、权限和源端数据问题。
检查平台实际数据
- 确认任务已启动、SmartGate 配置已同步、目标数据流版本已部署。
- 等待至少一个任务执行间隔,同时考虑源端指标生成粒度和配置的数据延迟。
- 在 数据体系 → 数据模型 → 指标 中核对指标定义,在 观测洞察 → 数据探索 中查询实际数据。
- 核对订阅、资源组、资源类型、资源名称、区域、指标时间戳和数值,并观察后续数据是否持续更新。
- 与 Azure 门户对比时,使用相同的资源层级、指标、时间范围、数据粒度、聚合方式、维度拆分方式和单位。
使用 Azure CLI 分层验证
需要进一步排查时,在具备 Azure CLI 的环境中使用与采集任务相同的服务主体进行以下检查。尽量在 SmartGate 所在运行环境执行;命令行不会自动读取平台组件配置中的凭证。
1. 确认身份及订阅
先在当前命令环境中准备 AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET 和 AZURE_SUBSCRIPTION_ID,分别对应前面的认证参数。执行:
az login --service-principal \
--username "$AZURE_CLIENT_ID" \
--password="$AZURE_CLIENT_SECRET" \
--tenant "$AZURE_TENANT_ID" \
--output none
az account set --subscription "$AZURE_SUBSCRIPTION_ID"
az account show \
--query '{subscription:id,tenant:tenantId,identity:user.name}' \
--output json
确认返回的订阅、租户和应用身份与采集配置一致。登录成功只证明身份可认证,不能证明已取得资源发现或指标读取权限。参见 使用服务主体登录 Azure CLI。
2. 核对指标定义
以下以 Blob 服务为例。先将 RESOURCE_ID 中的占位内容替换为实际值,注意保留 /blobServices/default 子资源层级:
RESOURCE_ID='/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>/blobServices/default'
az monitor metrics list-definitions \
--resource "$RESOURCE_ID" \
--namespace Microsoft.Storage/storageAccounts/blobServices \
--output json
确认结果包含 name.value 为 Transactions 的指标,并检查 supportedAggregationTypes、primaryAggregationType、metricAvailabilities[].timeGrain 和 dimensions。找到指标定义只说明该资源支持该指标,不代表当前时间范围已有数据。
3. 核对实际数据点
az monitor metrics list \
--resource "$RESOURCE_ID" \
--namespace Microsoft.Storage/storageAccounts/blobServices \
--metrics Transactions \
--aggregation Total \
--interval 1m \
--offset 1h \
--output json
以上命令查询最近一小时的数据。检查 value[].timeseries[].data 中是否存在具有时间戳和 total 数值的数据点;时间序列为空或数值为空不表示已经接入成功。与采集结果对比时,应再通过 --start-time、--end-time 指定与任务一致的查询窗口;配置了维度拆分时也须使用相同维度。命令参数见 Azure CLI 指标查询参考。
以上 CLI 指标命令验证单资源查询链路。采集还会使用区域级 metrics:getBatch 接口,因此单资源查询成功后,仍需核对服务主体具有订阅范围的 Monitoring Reader、Microsoft.Insights 已注册,并确认 SmartGate 能够访问对应区域的指标接口。
排查接入异常
| 现象 | 优先检查 |
|---|---|
| 认证失败或客户端密钥无效 | tenant_id、client_id 是否对应同一应用;是否误填对象 ID 或密码 ID;客户端密码是否到期;环境变量是否由 SmartGate 采集进程实际读取 |
| 资源或指标查询权限不足 | 角色是否分配给采集实际使用的服务主体;授权范围是否覆盖目标订阅;修改后是否已生效 |
| 单资源查询正常,但批量指标查询失败 | 是否仅授予资源或资源组权限;是否已在订阅范围分配 Monitoring Reader;Microsoft.Insights 是否已注册;区域指标接口是否可访问 |
| 任务正常运行但未发现目标资源 | subscription_id、type、资源组及资源 ID 是否正确;目标资源是否属于所选集成支持的资源类型;Blob/File 是否核对了服务子资源层级 |
| 能获取指标定义,但没有数据点 | 指标是否已在 Azure 门户产生数据;资源是否有相应业务活动或已启用相关功能;查询窗口是否覆盖已有数据点 |
| 提示指标、聚合方式或维度不支持 | 是否使用 REST 指标名称;大小写和空格是否一致;aggregation、split_by 是否属于指标定义支持的值 |
| 小时粒度指标缺失或间断 | 延迟和回溯窗口是否足以覆盖源端数据周期;是否仅增大执行间隔而仍保留过短的查询窗口 |
| Azure 已有数据,但平台查询不到 | 任务是否启动、SmartGate 配置是否同步、目标数据流是否部署;数据流是否输出标准指标;查询名称、时间范围和资源标签是否匹配 |
| 平台与 Azure 门户的数值不同 | 是否比较同一资源层级;时间范围、粒度、聚合方式、维度拆分和单位是否一致;是否将账户与子服务数据合并 |
任务与 SmartGate 状态检查见运行维护。需要进一步定位时,可下载 SmartGate 日志,结合对应任务的认证、资源发现、指标定义及指标查询错误信息排查。