企业官网建设流程全解析

Nightingale 集成 Azure Monitor：使用 Categraf 采集 Azure 云资源指标完整指南

【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale

导读

Azure Monitor 是微软 Azure 云平台的统一监控服务，提供云资源（虚拟机、SQL 数据库、存储、负载均衡器等）的性能指标与日志数据。本文基于夜莺（Nightingale）开源仓库中的 Azure 集成插件文档，完整讲解如何使用 Categraf 采集器对接 Azure Monitor API，将 Azure 资源指标纳入夜莺监控体系：从服务主体（Service Principal）注册、Monitor Reader 授权，到三种采集目标配置（指定资源 / 资源组 / 订阅）与aggregation_interval聚合粒度调优，并提供可直接复制运行的 TOML 配置。读完本文，你将能够独立完成 Azure 云资源的指标接入、配额评估与常见问题排查。

Azure 采集插件概述

该插件位于仓库 integrations/Azure 目录下，中文说明文档为 integrations/Azure/markdown/azure.md，对应英文版为 integrations/Azure/markdown/README.en_US.md，配套的采集配置文件为 integrations/Azure/collect/azure/azure.toml。

它的核心职责是：通过 Azure Monitor 的 REST API 拉取 Azure 资源的指标数据。插件本身不负责存储和告警，而是作为采集器 Categraf 的一个输入插件运行——夜莺项目本身不提供监控数据采集能力，官方推荐使用 Categraf 作为采集器，通过 Remote Write 协议将数据推送给夜莺，再由夜莺转存到时序库（如 Prometheus、VictoriaMetrics）并提供告警与可视化能力（见 README_zh.md）。

从配置文件的结构可以推断出插件的工作流：

1. 使用client_id、client_secret、tenant_id向 Azure Active Directory（Entra ID）换取访问令牌（Access Token）；
2. 携带令牌，按配置的采集目标（资源 / 资源组 / 订阅）枚举资源；
3. 调用 Azure Monitor 指标查询 API 拉取原始数据点；
4. 按aggregation_interval将原始点聚合为指定粒度的指标序列，输出为时序数据。

配额须知：每小时 12,000 次读取限制

文档中特别标注了一个重要约束：

Azure API 每小时有 12,000 次读取限制。请确保在配置的时间间隔内，您的总指标数量不超过此限制。

这意味着采集规模不能无限放大。估算时需考虑：采集的资源数量 × 每个资源的指标数量 × 每小时查询次数，总和应低于 12,000。合理设置interval（查询周期）与aggregation_interval（聚合粒度）是在配额内获取足够数据密度的关键，后文会给出具体调优建议。

前置准备：注册服务主体与授权

注册服务主体（Service Principal）

插件通过服务主体进行身份认证，因此第一步必须在 Azure 中注册一个服务主体（Service Principal）。这是标准的应用注册流程：在 Azure Active Directory（现称 Microsoft Entra ID）下注册一个应用程序，系统会生成client_id（应用 ID）与client_secret（客户端密钥），用于插件换取访问令牌。

授权：Monitor Reader 角色

仅注册服务主体还不够，还需要为它授予读取 Azure Monitor 数据的权限。文档明确指出所需权限为Monitor Reader（中文界面显示为"监视查阅者"）。请将服务主体以该角色授权到目标订阅、资源组或资源上，否则后续指标查询会因权限不足而失败。

关键属性获取指南

文档列出了各认证属性在 Azure 门户中的查找位置，整理如下：

需要注意resource_id的取值格式：配置注释中明确要求它必须以resourceGroups/...开头，并去掉资源 ID 属性值开头的/subscriptions/xxxxxxxx-xxxx-xxxx-xxx-xxxxxxxxxxxx前缀，示例：

resource_id = "resourceGroups/flashcat/providers/Microsoft.Compute/virtualMachines/lfn-test"

cloud_option用于指定 Azure 主权云（Sovereign Cloud）的 API 端点。若使用公有云，可保持默认AzurePublic不填；若资源位于中国区或政府云，则需要显式配置。

配置详解

完整配置以 TOML 格式编写，实际使用时可参考 integrations/Azure/collect/azure/azure.toml 这个可直接落地的版本。先看基础部分：

# Gather Azure resources metrics from Azure Monitor API # 每2m查询一次azure monitor, 查询时间范围也为2m interval = "2m" [[instances]] # can be found under Overview->Essentials in the Azure portal for your application/service subscription_id = "" # can be obtained by registering an application under Azure Active Directory client_id = "" # can be obtained by registering an application under Azure Active Directory. # If not specified Default Azure Credentials chain will be attempted: # - Environment credentials (AZURE_*) # - Workload Identity in Kubernetes cluster # - Managed Identity # - Azure CLI auth # - Developer Azure CLI auth client_secret = "" # can be found under Azure Active Directory->Properties tenant_id = "" # Define the optional Azure cloud option e.g. AzureChina, AzureGovernment or AzurePublic. The default is AzurePublic. # cloud_option = "AzurePublic" # 聚合粒度 # 比如我采集周期是10m, 指标上报周期是30s, 那么在10m内会有20个原始点 # 经过该参数的聚合处理后，比如聚合粒度是1m, 那么就会获取到10个点 # 注意，最小值是1m aggregation_interval = "1m"

interval：查询周期

顶层interval定义采集器多久查询一次 Azure Monitor。示例为"2m"，即每 2 分钟查询一次，查询的时间范围同样为 2 分钟。该参数同时决定了数据新鲜度与 API 调用频次，是配额消耗的第一影响因素。

client_secret缺省时的凭据链

值得注意的一个细节：client_secret注释中说明，若未指定，插件会依次尝试 Default Azure Credentials 链，顺序为：

1. 环境变量凭据（AZURE_*）；
2. Kubernetes 集群内的 Workload Identity；
3. 托管标识（Managed Identity）；
4. Azure CLI 认证；
5. Developer Azure CLI 认证。

这意味着在 AKS 等场景中，可以借助 Workload Identity 或 Managed Identity 免去明文密钥，提升安全性。

aggregation_interval：聚合粒度

这是控制数据点密度与 API 消耗的核心参数。文档给出了一个非常直观的例子：

比如采集周期是 10m，指标上报周期是 30s，那么在 10m 内会有 20 个原始点；经过该参数的聚合处理后，比如聚合粒度是 1m，那么就会获取到 10 个点。

注意，最小值是 1m。配置文件注释进一步补充了约束（见 azure.toml）：

• 支持的取值为1m, 5m, 15m, 30m, 1h, 6h, 12h, 1d；
• aggregation_interval不能大于interval；
• 聚合粒度越粗，单次查询返回的数据点越少，占用的读取配额越少，适合大规模资源场景。

cloud_option：云环境端点

# Define the optional Azure cloud option e.g. AzureChina, AzureGovernment or AzurePublic. The default is AzurePublic. # cloud_option = "AzurePublic"

可选值为AzureChina、AzureGovernment、AzurePublic，默认AzurePublic，用于对接 Azure 主权云。

采集目标配置：三种方式

文档与配置文件共同说明，采集目标支持三种定义方式，三种方式可以同时使用：

1. resource_target：通过资源 ID 从特定资源收集指标；
2. resource_group_target：从资源组下具有特定资源类型的资源收集指标；
3. subscription_target：从订阅下具有特定资源类型的资源收集指标。

方式一：指定具体资源（resource_target）

适合只关心某几台虚拟机等少量具体资源时使用：

# resource target #1 to collect metrics from [[instances.resource_target]] # can be found under Overview->Essentials->JSON View in the Azure portal for your application/service # must start with 'resourceGroups/...' ('/subscriptions/xxxxxxxx-xxxx-xxxx-xxx-xxxxxxxxxxxx' # must be removed from the beginning of Resource ID property value) resource_id = "resourceGroups/flashcat/providers/Microsoft.Compute/virtualMachines/lfn-test" # the metric names to collect # leave the array empty to use all metrics available to this resource # metrics = [ "<<METRIC>>", "<<METRIC>>" ] # metrics aggregation type value to collect # can be 'Total', 'Count', 'Average', 'Minimum', 'Maximum' # leave the array empty to collect all aggregation types values for each metric # aggregations = [ "<<AGGREGATION>>", "<<AGGREGATION>>" ]

每个资源目标下有两个可选子配置：

• metrics：要采集的指标名数组。留空数组表示采集该资源可用的全部指标；
• aggregations：指标的聚合方式数组，可选Total、Count、Average、Minimum、Maximum。留空数组表示采集每种指标的全部聚合值。

方式二：指定资源组（resource_group_target）

按资源组批量采集——资源组下可声明多个resource块，每个块按resource_type过滤：

# resource group target #1 to collect metrics from resources under it with resource type [[instances.resource_group_target]] # the resource group name resource_group = "flashcat" # defines the resources to collect metrics from [[instances.resource_group_target.resource]] # the resource type resource_type = "Microsoft.Compute/virtualMachines" # metrics = [ "<<METRIC>>", "<<METRIC>>" ] # aggregations = [ "<<AGGREGATION>>", "<<AGGREGATION>>" ] # resource group target #2 [[instances.resource_group_target]] resource_group = "<<RESOURCE_GROUP_NAME>>" [[instances.resource_group_target.resource]] resource_type = "<<RESOURCE_TYPE>>" metrics = [ "<<METRIC>>", "<<METRIC>>" ] aggregations = [ "<<AGGREGATION>>", "<<AGGREGATION>>" ]

资源类型使用完整的 ARM 类型名称，例如Microsoft.Compute/virtualMachines。

方式三：指定订阅（subscription_target）

在订阅维度按资源类型批量采集，覆盖范围最广：

# subscription target #1 to collect metrics from resources under it with resource type [[instances.subscription_target]] resource_type = "<<RESOURCE_TYPE>>" metrics = [ "<<METRIC>>", "<<METRIC>>" ] aggregations = [ "<<AGGREGATION>>", "<<AGGREGATION>>" ] # subscription target #2 [[instances.subscription_target]] resource_type = "<<RESOURCE_TYPE>>" metrics = [ "<<METRIC>>", "<<METRIC>>" ] aggregations = [ "<<AGGREGATION>>", "<<AGGREGATION>>" ]

三种方式的粒度从细到粗：单资源 → 资源组 → 订阅。从实现角度看，插件需要根据目标类型调用不同的资源列举与指标查询接口，因此目标覆盖范围越大，单轮采集产生的 API 调用越多，配置时应结合配额限制评估。

指标选择与配额控制实战建议

关于可采集的指标清单，文档指引查阅 Azure 官方的"支持的指标页面"了解各资源类型可用的指标。综合文档与配置约束，给出以下工程实践建议：

1. 优先用resource_target精确圈定资源，避免订阅级全量采集带来的配额压力；
2. 善用metrics白名单：只采集真正需要关注的指标，不要留空采集全部指标；
3. 按告警精度需求设置aggregation_interval：1m粒度最精细但配额消耗最大，长周期存储或大规模资源可上调至5m、15m甚至更粗；
4. 保证aggregation_interval ≤ interval，并注意interval本身也直接决定每小时查询次数；
5. 评估规模时，将"资源数 × 每资源指标数 × 每小时查询次数"与 12,000 的每小时配额对照，留出余量。

小结

本文基于夜莺仓库中的 integrations/Azure/markdown/azure.md 与配套的 azure.toml 配置文件，系统梳理了 Azure Monitor 指标接入夜莺生态的完整链路：通过服务主体 + Monitor Reader 授权打通 API 访问，用三种采集目标方式圈定监控范围，再借助aggregation_interval在配额与数据密度之间取得平衡。接入完成后，Azure 资源指标即可与本地机房、其他云厂商的指标统一汇入夜莺，实现跨云统一监控、告警与可视化的运维目标。

【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale