跳到主要内容

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 侧权限应授予采集实际使用的应用服务主体。

注册应用并获取认证参数​

  1. 登录 Azure 门户,进入 Microsoft Entra ID → 应用注册 → 新注册,在目标订阅所属租户中注册用于采集的应用。
  2. 打开应用的概述页面,记录目录(租户)ID 和应用程序(客户端)ID,分别填写到 tenant_id 和 client_id。
  3. 进入证书和密码 → 客户端密码 → 新客户端密码,填写说明并设置有效期,创建后立即保存客户端密码的值。
  4. 进入 订阅,选择目标资源所在订阅,在概述页面复制订阅 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 使用。

配置订阅范围的读取权限​

  1. 由具有角色分配权限的 Azure 管理员进入目标订阅 → 访问控制(IAM)。
  2. 选择添加角色分配,选择 Monitoring Reader 角色。
  3. 在成员中选择采集使用的应用服务主体,核对订阅范围和应用身份后完成分配。
  4. 进入同一订阅的资源提供程序,搜索 Microsoft.Insights;尚未注册时完成注册。

本集成使用 Azure Monitor 批量指标接口 metrics:getBatch,需要在订阅范围授予指标读取权限。仅在单个资源或资源组上分配角色,即使可以查看该资源的指标,也不能替代批量接口所需的订阅级授权。

角色分配方法见 Azure 门户中的角色分配,资源提供程序操作见资源提供程序注册。订阅授权及 Microsoft.Insights 要求见 Azure Monitor 批量指标接口说明。

选择采集对象并准备接入配置​

这一步确定采集哪类资源、哪些指标,以及是否需要按维度拆分。不同 Azure 服务共用前面的认证授权步骤和后面的平台任务配置流程;一个任务对应一种服务类型和一个订阅。

选择服务集成​

以下集成对象可按监控场景选择,实际可用指标取决于资源类型、服务配置及 Azure Monitor 已提供的数据。

集成对象type采集资源主要指标及使用说明
Azure Blob Storageblob存储账户及 Blob 服务事务数、流入流出、可用性、延迟和容量;账户与 Blob 服务属于不同资源层级
Azure Filesfiles存储账户及 File 服务文件服务事务、吞吐、延迟、容量及配额;指标随存储配置有所不同
Azure Cosmos DBcosmosdbCosmos DB 数据库账户请求、RU 消耗、延迟和存储;需要数据库或容器粒度时,先核对指标支持的维度
Azure DNSdnsDNS 区域及 DNS Private ResolverDNS 查询和解析器指标;区域与解析器的指标粒度不同
Azure Database for PostgreSQLpostgresqlPostgreSQL 灵活服务器CPU、内存、存储、连接和 I/O;增强指标依赖源端启用相应功能
Azure Virtual Networkvnet虚拟网络、网络接口、公网 IP 和 NAT 网关网络流量、连接和相关状态;部分指标仅在对应网络功能启用后产生
Azure VPN Gatewayvpngw虚拟网络网关VPN 隧道流量、连接和 BGP 状态;隧道指标依赖实际连接

Blob Storage 和 Azure Files 从存储账户发现对应服务子资源,资源 ID 分别以 /blobServices/default 和 /fileServices/default 结尾。Azure DNS 的解析器资源类型为 Microsoft.Network/dnsResolvers;不要将 DNS 记录集作为解析器资源。可用指标见 DNS Private Resolver 指标参考。

获取资源及指标信息​

  1. 在 Azure 门户打开目标资源,记录所属订阅、资源组、区域和完整资源 ID。资源 ID 可从资源的属性或 JSON 视图获取。
  2. 进入资源的监视 → 指标,选择目标资源范围、指标命名空间、指标和聚合方式,确认近期存在数据点。
  3. 通过 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 认证、采集对象和指标范围填写到平台,保存后检查任务及数据流,确保配置已下发并用于实际采集。

创建接入任务​

  1. 进入 数据体系 → 数据集成 → 自定义集成,选择目标 Azure 服务卡片,例如 Azure Blob Storage,点击创建接入。
  2. 切换到配置页签,选择数据中心,填写任务名称,按实际数据权限要求配置数据标签。
  3. 点击添加组件,选择运行采集任务的 SmartGate,并按表单要求填写订阅、认证及采集参数。前面的 YAML 示例展示采集配置内容;使用环境变量读取密钥时,须确认所选 SmartGate 能读取该变量。
  4. 核对组件列表后点击保存,进入 数据体系 → 数据处理,按任务名称找到对应任务。
  5. 打开任务详情,检查数据流的输入、处理和输出配置,确认需要使用的版本处于部署状态,并核对指标名称、标签和单位。
  6. 检查任务启停状态。尚未启动时,在完成配置检查后启动任务,并核对 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 区分身份、权限和源端数据问题。

检查平台实际数据​

  1. 确认任务已启动、SmartGate 配置已同步、目标数据流版本已部署。
  2. 等待至少一个任务执行间隔,同时考虑源端指标生成粒度和配置的数据延迟。
  3. 在 数据体系 → 数据模型 → 指标 中核对指标定义,在 观测洞察 → 数据探索 中查询实际数据。
  4. 核对订阅、资源组、资源类型、资源名称、区域、指标时间戳和数值,并观察后续数据是否持续更新。
  5. 与 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 日志,结合对应任务的认证、资源发现、指标定义及指标查询错误信息排查。