windows_exporter 的 ad collector 全解析：Active Directory 域控制器性能监控指标采集实战-平芜编程栈

可观测性
指标监控

【免费下载链接】windows_exporter

Prometheus exporter for Windows machines

项目地址：https://gitcode.com/gh_mirrors/wi/windows_exporter

本篇技术指南聚焦 windows_exporter 项目中的adcollector，它用于在一台 Active Directory 域服务（AD DS）域控制器上采集目录服务自身的性能数据，并将 Windows 性能计数器转换为 Prometheus 指标。读完本文你将掌握：如何在域控制器上启用adcollector、它暴露的 62 个指标各自的含义与标签维度、指标背后的 Windows 性能计数器来源，以及如何基于源码理解数值单位换算与验证手段。全文以 docs/collector.ad.md 为骨架，并结合仓库内的 Go 源码实现逐层展开。

一、collector 概览

adcollector 的定位非常明确：它只能运行在域控制器（Domain Controller）上，度量的是 AD DS 目录服务进程自身的活动，包括 LDAP 请求、复制（Replication）、SAM 安全账户管理、目录数据库操作、安全描述符传播等。以下信息直接来自 docs/collector.ad.md：

属性	值
Metric name prefix（指标名前缀）	`ad`
Classes（数据源 WMI 类）	`Win32_PerfRawData_DirectoryServices_DirectoryServices`
Enabled by default?（默认是否启用）	否
Flags（专属命令行参数）	无

两点值得注意：

默认不启用：windows_exporter 的默认采集器集合定义在 pkg/collector/types.go 中，即cpu,memory,logical_disk,physical_disk,net,os,service,system，其中并不包含ad。这是因为ad指标只在域控制器上有意义，普通成员服务器上对应的性能计数器对象不存在，强制采集反而会报错。
无专属 Flags：从源码看，ad.Config是一个空结构体（internal/collector/ad/ad.go），ConfigDefaults也是空值，因此该 collector 没有任何可调参数，启用即用。

二、在域控制器上启用 ad collector

由于ad不在默认启用列表内，需要显式启用。windows_exporter 提供了命令行参数与 YAML 配置文件两种方式。

2.1 命令行方式

在域控制器上以管理员身份运行 windows_exporter 时，通过--collectors.enabled指定：

windows_exporter.exe --collectors.enabled=ad

若既要保留默认采集器、又要追加ad，可以使用[defaults]占位符：

windows_exporter.exe --collectors.enabled="[defaults],ad"

--collectors.enabled与--collectors.disabled两个参数的解析逻辑定义在 cmd/windows_exporter/main.go：前者是逗号分隔的启用列表，后者用于从默认集合中排除某些 collector。[defaults]会被展开为默认集合字符串（cmd/windows_exporter/main.go），随后由 pkg/collector/collection.go 的Enable/Disable方法完成 collector 的保留与剔除。

2.2 配置文件方式

与命令行等价，在 YAML 配置文件的collectors.enabled字段中启用，例如参考仓库根目录的 config.yaml：

collectors: enabled: "[defaults],ad"

配置文件结构由 internal/config/config.go 定义，其中的collector段下还可以为各 collector 提供ad子配置（此处为空即可）：

collector: ad: {}

2.3 前置条件与限制

adcollector 必须运行在域控制器上；在普通 Windows 服务器上，DirectoryServices性能计数器对象不存在，采集会返回 "failed to collect DirectoryServices (AD) metrics" 错误（见 internal/collector/ad/ad.go）。
需要域控制器角色已经安装并正常工作，即NTDS服务与目录服务性能计数器可用。
由于读取的是本机性能计数器，建议直接在该 DC 上部署 windows_exporter，而不是跨机器远程采集。

三、实现原理：从 DirectoryServices 性能计数器到 Prometheus 指标

adcollector 的数据链路非常清晰，全部源码位于 internal/collector/ad/ 目录下，由三个文件组成：ad.go（主实现）、types.go（性能计数器字段映射）、ad_test.go（测试）。

3.1 性能计数器绑定

在 ad.go 的Build阶段，collector 通过内部pdh包创建性能计数器采集器：

c.perfDataCollector, err = pdh.NewCollectorperfDataCounterValues), pdh.CounterTypeRaw, // 原始计数类型 "DirectoryServices", // 性能计数器对象名 pdh.InstancesAll, // 所有实例 )

其中pdh.CounterTypeRaw表示以原始计数（而非格式化计数）读取数据，DirectoryServices是 Windows 内置的目录服务性能计数器对象，对应文档表格中提到的Win32_PerfRawData_DirectoryServices_DirectoryServicesWMI 类。该对象没有多实例，因此InstancesAll（即["*"]）在实际采集时只产生一个实例，体现在代码中统一使用c.perfDataObject[0]取值。

3.2 字段到指标的映射

types.go 用结构体 tag 将 Go 字段与 Windows 性能计数器的原始名称一一对应，例如：

AbANRPerSec float64 `perfdata:"AB ANR/sec"` AtqThreadsLDAP float64 `perfdata:"ATQ Threads LDAP"` LdapBindTime float64 `perfdata:"LDAP Bind Time"` SamPasswordChangesPerSec float64 `perfdata:"SAM Password Changes/sec"`

这份结构体几乎是 DirectoryServices 性能计数器对象全部计数器的完整清单（超过 200 个计数器名，未使用的用_占位），因此它是理解每个 Prometheus 指标底层数据来源的权威对照表。需要注意：types.go中被_占位的计数器（如 "LDAP Add Operations"、"DRA total time ..."）尚未被adcollector 暴露为指标。

3.3 指标描述符与采集

Build阶段为每个指标创建prometheus.Desc（名称统一使用windows_+ad_前缀，命名空间常量定义于internal/types），Collect阶段则调用perfDataCollector.Collect拉取快照，再用prometheus.MustNewConstMetric逐条发送到指标通道。整个 collector 的生命周期方法（New、NewWithFlags、GetName、Close、Build、Collect）均实现于 ad.go，并注册进全局 collector 表 pkg/collector/map.go（键为ad.Name）。

四、指标全景（62 个指标按功能域详解）

以下完整列出adcollector 暴露的全部 62 个指标（继承自 docs/collector.ad.md，并补充了每个指标对应的 Windows 性能计数器来源与标签取值）。原文档中大部分指标的 Description 标注为Not yet documented，本节的"对应计数器"列依据 types.go 中的字段绑定给出可验证的底层数据源。

4.1 通讯簿（Address Book）指标

通讯簿是 LDAP 客户端查询目录时经常访问的"地址簿"视图（如 Outlook 通讯簿解析），相关计数器以AB前缀命名。

Name	Description	Type	Labels
`windows_ad_address_book_operations_total`	Not yet documented（对应计数器：`AB ANR/sec`、`AB Browses/sec`、`AB Matches/sec`、`AB Property Reads/sec`、`AB Searches/sec`、`AB Proxy Lookups/sec`）	counter	`operation`
`windows_ad_address_book_client_sessions`	Not yet documented（对应计数器：`AB Client Sessions`）	gauge	无

其中operation标签的取值在 ad.go 中逐一固定为：ambiguous_name_resolution、browse、find、property_read、search、proxy_search，分别对应上述 6 个AB .../sec计数器。

4.2 ATQ 异步线程队列指标

ATQ（Asynchronous Thread Queue）是 AD 处理传入请求的工作线程池，直接反映 DC 的"忙碌程度"与排队压力。

Name	Description	Type	Labels
`windows_ad_approximate_highest_distinguished_name_tag`	Not yet documented（对应计数器：`Approximate highest DNT`）	gauge	无
`windows_ad_atq_estimated_delay_seconds`	Not yet documented（对应计数器：`ATQ Estimated Queue Delay`，源码中除以 1000 将毫秒换算为秒）	gauge	无
`windows_ad_atq_outstanding_requests`	Not yet documented（对应计数器：`ATQ Outstanding Queued Requests`）	gauge	无
`windows_ad_atq_average_request_latency`	Not yet documented（对应计数器：`ATQ Request Latency`）	gauge	无
`windows_ad_atq_current_threads`	Not yet documented（对应计数器：`ATQ Threads LDAP`、`ATQ Threads Other`）	gauge	`service`

atq_current_threads的service标签取值为ldap与other（见 ad.go），区分处理 LDAP 请求与其它请求的线程数量。

4.3 目录搜索与数据库操作指标

搜索指标按搜索范围（scope）拆分，数据库操作指标按操作类型拆分，是衡量 DC 读写负载最直接的指标组。

Name	Description	Type	Labels
`windows_ad_searches_total`	Not yet documented（对应计数器：`Base searches/sec`、`Subtree searches/sec`、`Onelevel searches/sec`）	counter	`scope`
`windows_ad_database_operations_total`	Not yet documented（对应计数器：`Database adds/sec`、`Database deletes/sec`、`Database modifys/sec`、`Database recycles/sec`）	counter	`operation`

searches_total的scope标签取值：base、subtree、one_level；database_operations_total的operation标签取值：add、delete、modify、recycle（见 ad.go）。

4.4 绑定（Bind）指标

绑定指标统计客户端通过不同认证机制向 DC 发起 LDAP 绑定（登录验证）的速率，可用于观察认证流量结构与异常绑定尝试。

Name	Description	Type	Labels
`windows_ad_binds_total`	Not yet documented（对应计数器：`Digest Binds/sec`、`DS Client Binds/sec`、`DS Server Binds/sec`、`External Binds/sec`、`Fast Binds/sec`、`Negotiated Binds/sec`、`NTLM Binds/sec`、`Simple Binds/sec`、`LDAP Successful Binds/sec`）	counter	`bind_method`

bind_method标签取值完整对应上述 9 个计数器：digest、ds_client、ds_server、external、fast、negotiate、ntlm、simple、ldap（见 ad.go）。

4.5 复制（Replication / DRA）指标

复制指标来自 DRA（Directory Replication Agent，目录复制代理），是判断多域控制器环境中复制健康度的核心数据。注意replication_highest_usn在源码中通过高 32 位 << 32 + 低 32 位将两个计数器拼装为完整的 64 位 USN 值（ad.go）。

Name	Description	Type	Labels
`windows_ad_replication_highest_usn`	Not yet documented（对应计数器：`DRA Highest USN Committed (High/Low part)`、`DRA Highest USN Issued (High/Low part)`）	counter	`state`
`windows_ad_replication_data_intrasite_bytes_total`	Not yet documented（对应计数器：`DRA Inbound/Outbound Bytes Not Compressed (Within Site)/sec`）	counter	`direction`
`windows_ad_replication_data_intersite_bytes_total`	Not yet documented（对应计数器：`DRA Inbound/Outbound Bytes Compressed (Between Sites, After Compression)/sec`）	counter	`direction`
`windows_ad_replication_inbound_sync_objects_remaining`	Not yet documented（对应计数器：`DRA Inbound Full Sync Objects Remaining`）	gauge	无
`windows_ad_replication_inbound_link_value_updates_remaining`	Not yet documented（对应计数器：`DRA Inbound Link Value Updates Remaining in Packet`）	gauge	无
`windows_ad_replication_inbound_objects_updated_total`	Not yet documented（对应计数器：`DRA Inbound Objects Applied/sec`）	counter	无
`windows_ad_replication_inbound_objects_filtered_total`	Not yet documented（对应计数器：`DRA Inbound Objects Filtered/sec`）	counter	无
`windows_ad_replication_inbound_properties_updated_total`	Not yet documented（对应计数器：`DRA Inbound Properties Applied/sec`）	counter	无
`windows_ad_replication_inbound_properties_filtered_total`	Not yet documented（对应计数器：`DRA Inbound Properties Filtered/sec`）	counter	无
`windows_ad_replication_pending_operations`	Not yet documented（对应计数器：`DRA Pending Replication Operations`）	gauge	无
`windows_ad_replication_pending_synchronizations`	Not yet documented（对应计数器：`DRA Pending Replication Synchronizations`）	gauge	无
`windows_ad_replication_sync_requests_total`	Not yet documented（对应计数器：`DRA Sync Requests Made`）	counter	无
`windows_ad_replication_sync_requests_success_total`	Not yet documented（对应计数器：`DRA Sync Requests Successful`）	counter	无
`windows_ad_replication_sync_requests_schema_mismatch_failure_total`	Not yet documented（对应计数器：`DRA Sync Failures on Schema Mismatch`）	counter	无

标签取值说明：

replication_highest_usn的state标签为committed（已提交的 USN）与issued（已签发的 USN）；
两个字节量指标（intrasite/intersite）的direction标签均为inbound、outbound；
从源码注释看（ad.go），intersite 字节量只采用"压缩后（After Compression）"的计数器，压缩前的数值被认为参考价值有限而未暴露。

4.6 名称翻译、更改通知与名称缓存指标

这部分反映目录服务的名称解析、变更通知队列与名称缓存命中情况，与客户端体验（如查找速度、变更是否及时推送）密切相关。

Name	Description	Type	Labels
`windows_ad_name_translations_total`	Not yet documented（对应计数器：`DS Client Name Translations/sec`、`DS Server Name Translations/sec`）	counter	`target_name`
`windows_ad_change_monitors_registered`	Not yet documented（对应计数器：`DS Monitor List Size`）	gauge	无
`windows_ad_change_monitor_updates_pending`	Not yet documented（对应计数器：`DS Notify Queue Size`）	gauge	无
`windows_ad_name_cache_hits_total`	Not yet documented（对应计数器：`DS Name Cache hit rate`）	counter	无
`windows_ad_name_cache_lookups_total`	Not yet documented（对应计数器：`DS Name Cache hit rate,secondvalue`）	counter	无

name_translations_total的target_name标签取值：client、server（ad.go）。

4.7 目录操作（按来源拆分的读写查）指标

这是指标最丰富的单点之一：directory_operations_total同时携带operation（read/search/write）与origin（请求来源组件）两个标签，可以精确回答"谁在给 DC 施加读/搜/写压力"。底层计数器是DS % Reads from ...、DS % Searches from ...、DS % Writes from ...系列（types.go）。

Name	Description	Type	Labels
`windows_ad_directory_operations_total`	Not yet documented（对应计数器：`DS % Reads/Searches/Writes from DRA/KCC/LSA/NSPI/NTDSAPI/SAM/LDAP/Other`）	counter	`operation`,`origin`
`windows_ad_directory_search_suboperations_total`	Not yet documented（对应计数器：`DS Search sub-operations/sec`）	counter	无

origin标签的全部取值（见 ad.go）：replication_agent（DRA）、knowledge_consistency_checker（KCC）、local_security_authority（LSA）、name_service_provider_interface（NSPI）、directory_service_api（NTDSAPI）、security_account_manager（SAM）、ldap，以及兜底的other。

4.8 安全描述符传播指标

安全描述符传播器（Security Descriptor Propagator）负责在 ACL 继承变更后递归更新对象的安全描述符，这些指标可用于诊断"继承权限更改后长时间未生效"的问题。

Name	Description	Type	Labels
`windows_ad_security_descriptor_propagation_events_total`	Not yet documented（对应计数器：`DS Security Descriptor sub-operations/sec`）	counter	无
`windows_ad_security_descriptor_propagation_events_queued`	Not yet documented（对应计数器：`DS Security Descriptor Propagations Events`）	gauge	无
`windows_ad_security_descriptor_propagation_access_wait_total_seconds`	Not yet documented（对应计数器：`DS Security Descriptor Propagator Average Exclusion Time`，源码中未做单位换算，直接输出）	gauge	无
`windows_ad_security_descriptor_propagation_items_queued_total`	Not yet documented（对应计数器：`DS Security Descriptor Propagator Runtime Queue`）	counter	无

4.9 线程与 LDAP 连接指标

Name	Description	Type	Labels
`windows_ad_directory_service_threads`	Not yet documented（对应计数器：`DS Threads in Use`）	gauge	无
`windows_ad_ldap_closed_connections_total`	Not yet documented（对应计数器：`LDAP Closed Connections/sec`）	counter	无
`windows_ad_ldap_opened_connections_total`	Not yet documented（对应计数器：`LDAP New Connections/sec`、`LDAP New SSL Connections/sec`）	counter	`type`
`windows_ad_ldap_active_threads`	Not yet documented（对应计数器：`LDAP Active Threads`）	gauge	无
`windows_ad_ldap_last_bind_time_seconds`	Not yet documented（对应计数器：`LDAP Bind Time`，源码中除以 1000 将毫秒换算为秒）	gauge	无
`windows_ad_ldap_searches_total`	Not yet documented（对应计数器：`LDAP Searches/sec`）	counter	无
`windows_ad_ldap_udp_operations_total`	Not yet documented（对应计数器：`LDAP UDP operations/sec`）	counter	无
`windows_ad_ldap_writes_total`	Not yet documented（对应计数器：`LDAP Writes/sec`）	counter	无
`windows_ad_ldap_client_sessions`	This is the number of sessions opened by LDAP clients at the time the data is taken. This is helpful in determining LDAP client activity and if the DC is able to handle the load. Of course, spikes during normal periods of authentication — such as first thing in the morning — are not necessarily a problem, but long sustained periods of high values indicate an overworked DC（对应计数器：`LDAP Client Sessions`）	gauge	无

ldap_opened_connections_total的type标签取值：ldap（明文连接）、ldaps（SSL 连接）。ldap_client_sessions是当前文档中唯一拥有完整官方描述的指标：它反映采样时刻 LDAP 客户端打开的会话数，用于判断 DC 是否过载——早晨集中认证时段出现尖峰通常正常，但长期高位则提示 DC 负载过重。

4.10 链接值清理、幽灵对象与墓碑对象指标

这些指标反映目录垃圾回收（GC）与一致性维护工作的进展，对应计数器集中在Link Values Cleaned/sec、Phantoms Cleaned/Visited per sec、Tombstones Garbage Collected/Visited per sec。

Name	Description	Type	Labels
`windows_ad_link_values_cleaned_total`	Not yet documented	counter	无
`windows_ad_phantom_objects_cleaned_total`	Not yet documented	counter	无
`windows_ad_phantom_objects_visited_total`	Not yet documented	counter	无
`windows_ad_tombstoned_objects_collected_total`	Not yet documented（注意：源码字段名为`TombstonesGarbageCollectedPerSec`）	counter	无
`windows_ad_tombstoned_objects_visited_total`	Not yet documented	counter	无

4.11 SAM 安全账户管理指标

SAM（Security Accounts Manager，安全账户管理器）指标覆盖组隶属关系评估、用户/计算机创建、密码变更等账户管理活动，是观察 DC 认证与账户操作负载的关键分组。

Name	Description	Type	Labels
`windows_ad_sam_group_membership_evaluations_total`	Not yet documented（对应计数器：`SAM Global/Domain Local/Universal Group Membership Evaluations/sec`）	counter	`group_type`
`windows_ad_sam_group_membership_global_catalog_evaluations_total`	Not yet documented（对应计数器：`SAM GC Evaluations/sec`）	counter	无
`windows_ad_sam_group_membership_evaluations_nontransitive_total`	Not yet documented（对应计数器：`SAM Non-Transitive Membership Evaluations/sec`）	counter	无
`windows_ad_sam_group_membership_evaluations_transitive_total`	Not yet documented（对应计数器：`SAM Transitive Membership Evaluations/sec`）	counter	无
`windows_ad_sam_group_evaluation_latency`	The mean latency of the last 100 group evaluations performed for authentication（对应计数器：`SAM Account Group Evaluation Latency`、`SAM Resource Group Evaluation Latency`）	gauge	`evaluation_type`
`windows_ad_sam_computer_creation_requests_total`	Not yet documented（对应计数器：`SAM Successful Computer Creations/sec: Includes all requests`）	counter	无
`windows_ad_sam_computer_creation_successful_requests_total`	Not yet documented（对应计数器：`SAM Machine Creation Attempts/sec`）	counter	无
`windows_ad_sam_user_creation_requests_total`	Not yet documented（对应计数器：`SAM User Creation Attempts/sec`）	counter	无
`windows_ad_sam_user_creation_successful_requests_total`	Not yet documented（对应计数器：`SAM Successful User Creations/sec`）	counter	无
`windows_ad_sam_query_display_requests_total`	Not yet documented（对应计数器：`SAM Display Information Queries/sec`）	counter	无
`windows_ad_sam_enumerations_total`	Not yet documented（对应计数器：`SAM Enumerations/sec`）	counter	无
`windows_ad_sam_membership_changes_total`	Not yet documented（对应计数器：`SAM Membership Changes/sec`）	counter	无
`windows_ad_sam_password_changes_total`	Not yet documented（对应计数器：`SAM Password Changes/sec`）	counter	无

标签取值：sam_group_membership_evaluations_total的group_type为global、domain_local、universal；sam_group_evaluation_latency的evaluation_type为account_group、resource_group（ad.go）。其中sam_group_evaluation_latency的官方描述为：最近 100 次认证组评估的平均延迟。

五、源码中的关键细节：单位换算与数值拼装

从 ad.go 的Collect实现可以观察到三类值得注意的数值处理，理解它们有助于正确解读指标数值：

毫秒到秒的换算：atq_estimated_delay_seconds与ldap_last_bind_time_seconds的原始计数器以毫秒为单位，源码中分别执行AtqEstimatedQueueDelay/1000与LdapBindTime/1000（ad.go、ad.go），因此指标名中的_seconds名副其实。
64 位 USN 拼装：replication_highest_usn的 USN 值在 Windows 中以高 32 位 + 低 32 位两个计数器存储，源码用float64(uint64(HighPart)<<32) + LowPart还原完整数值（ad.go）。由于float64的精度限制，超大的 USN 可能产生轻微舍入，但对监控用途足够。
原始计数与"每秒"计数器：collector 使用pdh.CounterTypeRaw读取原始值，因此对.../sec类计数器，指标实际记录的是采样周期内的增量（counter 类型），PromQL 中应使用rate()/increase()计算速率；对 gauge 类指标（如队列长度、线程数、会话数）直接反映采样时刻的快照值。

六、验证与测试

仓库为adcollector 提供了标准测试入口 internal/collector/ad/ad_test.go：

func TestCollector(t *testing.T) { testutils.TestCollector(t, ad.New, nil) } func BenchmarkCollector(b *testing.B) { testutils.FuncBenchmarkCollector(b, ad.Name, ad.NewWithFlags) }

其中TestCollector通过internal/utils/testutils在真实 DC 环境上执行采集并校验指标描述符的合法性；BenchmarkCollector用于度量单次采集的耗时。这些测试带//go:build windows构建约束，且依赖域控制器环境才能通过。日常验证可遵循以下步骤：

在 DC 上启动 windows_exporter（--collectors.enabled=ad）；
访问http://<DC-IP>:9182/metrics，确认输出包含windows_ad_前缀的指标；
用 Prometheus 查询，例如：

# 查看当前 LDAP 客户端会话数（判断 DC 负载） windows_ad_ldap_client_sessions # 查看各认证方式的绑定速率 rate(windows_ad_binds_total[5m]) # 查看复制待处理同步数（接近 0 表示复制健康） windows_ad_replication_pending_synchronizations

七、文档现状与贡献入口

截至当前仓库版本，docs/collector.ad.md 末尾的 "Example metric"、"Useful queries"、"Alerting examples" 三节仍为空占位，原文注明 "This collector does not yet have explained examples, we would appreciate your help adding them!"，即官方示例指标、实用查询与告警示例尚未补充。撰写本文时，指标描述信息以 types.go 中的性能计数器绑定为事实依据；读者若需在 Grafana 告警或查询中使用这些指标，建议先在一台测试 DC 上确认_Not yet documented_指标的实际数值形态（如是否长期为 0），再据此设计阈值。

总结

adcollector 是 windows_exporter 中面向 AD DS 域控制器的专项采集器，通过DirectoryServices性能计数器对象提供 LDAP、复制、SAM、数据库操作、安全描述符传播等 62 个指标，覆盖了 DC 健康度监控的主要维度。其特点是：默认不启用、无专属配置参数、仅在域控制器上可用、指标标签维度极其丰富（绑定方法、搜索范围、复制方向、请求来源组件等）。结合 internal/collector/ad/ad.go、types.go 与 docs/collector.ad.md 三者对照阅读，即可完整掌握每个指标从 Windows 计数器到 Prometheus 序列的映射关系，为 DC 容量规划、认证性能分析与复制故障排查建立可靠的监控底座。