☰

企业官网建设流程全解析

首页 / 建站日记 / 企业官网建设流程全解析
windows_exporter cache collector 详解：基于 Perflib 的 Windows 文件系统缓存监控指南
2026/10/14 18:15:27 网站建设 项目流程
  • 可观测性
  • 指标监控

【免费下载链接】windows_exporter

Prometheus exporter for Windows machines

项目地址：https://gitcode.com/gh_mirrors/wi/windows_exporter
点击查看免费下载

本文以 windows_exporter 仓库中的 cache collector 官方文档 为骨架，结合其 Go 源码实现 与测试用例，系统讲解 cache collector 的定位、启用方式、指标语义与 PromQL 使用方案。读完本文，你将掌握如何为 Windows 主机开启文件系统缓存（File System Cache）监控，并能在 Prometheus 中正确解读与查询这组指标。

一、Collector 概览：它采集什么、数据从哪来

cache collector 对外暴露的是Windows 文件系统缓存（file system cache）相关的性能指标。Windows 内核会利用物理内存中的空闲部分缓存最近访问的文件页（page），从而加速磁盘 I/O；cache collector 就是通过 Windows 性能计数器（Perflib）中的Cache性能对象，把这些缓存行为（读命中、映射、脏页、延迟写入、预读等）转换为 Prometheus 指标。

该 collector 的核心属性如下（与官方文档一致）：

属性值
Metric name prefix（指标名前缀）cache
Data Source（数据源）Perflib（Performance Library）
Classes（对应 WMI 类）Win32_PerfFormattedData_PerfOS_Cache
Enabled by default?（默认是否启用）否
Flags（专属命令行参数）无

三个关键信息值得展开：

  1. 默认不启用：在 README.md 的 collector 列表（第 20 行）中，cache 一栏的 "Enabled" 列没有勾选标记，它不属于默认启用的 collector 集合。你必须在启动参数、配置文件中显式启用它，才能采集到相关指标。
  2. 无专属 Flags：cache collector 的 Config 结构体 是一个空结构体type Config struct{}，没有任何可配置项，也不注册任何 CLI 标志（NewWithFlags直接返回空 Collector）。
  3. 数据源为 Perflib：它不依赖 WMI 查询，而是直接读取 Windows 性能计数器库中的Cache对象。所有指标通过 pdh 包 提供的 Perflib 客户端采集。

二、启用 cache collector（实操）

由于默认不启用，以下三种方式都可以开启它。

2.1 命令行 Flags

在 windows_exporter 可执行文件所在目录执行：

.\windows_exporter.exe --collectors.enabled=cache

如需在默认 collector 基础上叠加 cache，可使用[defaults]占位符（参见 README.md 的 "Using [defaults]" 一节）：

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

2.2 YAML 配置文件

通过--config.file指定配置文件，例如：

.\windows_exporter.exe --config.file=config.yml
collectors: enabled: cache log: level: warn

仓库中的 config.yaml 和 docs/example_config.yml 展示了同样的配置结构；如果同时使用 CLI Flags 与配置文件，CLI Flags 优先级更高（参见 README.md 的 "Configuration file notes"）。

2.3 MSI 安装器参数

使用安装包部署时，可以通过ENABLED_COLLECTORS参数指定启用的 collector（参见 README.md 的 "Installation" 一节）：

msiexec /i windows_exporter.msi ENABLED_COLLECTORS=cache

2.4 验证指标是否输出

启用后访问默认的指标端点（默认监听:9182，路径/metrics），过滤 cache 相关指标：

curl "http://localhost:9182/metrics" | grep "^windows_cache"

三、源码实现解析：从 Perflib 计数器到 Prometheus 指标

理解底层实现有助于正确使用这组指标。cache collector 的源码集中在 internal/collector/cache/ 目录下，由三个文件构成。

3.1 指标描述符的构建（Build）

在 cache.go 的Build方法中，每个指标通过prometheus.BuildFQName(types.Namespace, Name, "async_copy_reads_total")之类的调用生成完整指标名。其中types.Namespace是全局命名空间（windows），Name是包内常量"cache"，因此最终指标名形如windows_cache_xxx。每个prometheus.Desc的 labels 参数均为nil，所以所有 cache 指标都不带任何标签，与文档中的 Labels 列（全部为 None）一致。

3.2 Perflib 计数器到结构体字段的映射（types.go）

关键设计在 types.go 中：perfDataCounterValues结构体的每个字段都带有perfdata:"..."标签，标签值就是 Perflib 中Cache对象的原始计数器名称，例如：

AsyncCopyReadsTotal float64 `perfdata:"Async Copy Reads/sec"` CopyReadHitsTotal float64 `perfdata:"Copy Read Hits %"` DirtyPages float64 `perfdata:"Dirty Pages"` DirtyPageThreshold float64 `perfdata:"Dirty Page Threshold"`

pdh 包（internal/pdh/collector.go 的NewCollector）通过反射读取这些perfdata标签，将结构体字段与 Windows 性能计数器一一绑定。

3.3 采集流程（Collect）

在Build中，collector 通过以下调用创建 Perflib 数据采集器：

c.perfDataCollector, err = pdh.NewCollectorperfDataCounterValues), pdh.CounterTypeRaw, // 使用原始计数器值 "Cache", // Perflib 对象名 pdh.InstancesAll, // 采集所有实例（"*"） )

pdh.CounterTypeRaw表示直接读取计数器的原始累加值；pdh.InstancesAll对应["*"]，即不按实例区分（Cache 对象本身是单实例的）。随后Collect方法在每次抓取时：

  1. 调用c.perfDataCollector.Collect(&c.perfDataObject)拉取全部计数器值；
  2. 若返回的数据为空，则返回types.ErrNoDataUnexpected错误（见 cache.go 第 294–296 行）；
  3. 通过prometheus.MustNewConstMetric将每个字段值按prometheus.CounterValue或prometheus.GaugeValue类型发送到指标通道。

3.4 注册与装配

cache collector 在三个位置完成注册（可分别查看 pkg/collector/config.go、pkg/collector/collection.go 与 pkg/collector/map.go）：

  • Config中声明Cache cache.Config \yaml:"cache"`配置字段（第 76 行），并给出空配置的默认值cache.ConfigDefaults`（第 132 行）；
  • 收集器集合中以collectors[cache.Name] = cache.New(&config.Cache)完成实例化（第 106 行）；
  • 名称映射表中以cache.Name: NewBuilderWithFlags(cache.NewWithFlags)注册（第 87 行）。

由于Config为空，实际使用中你不需要（也无法）为 cache 配置任何参数，只需在collectors.enabled列表中写入cache即可。

四、指标总览（完整清单）

以下为 cache collector 导出的全部 29 个指标（名称、描述、类型、标签均继承自 docs/collector.cache.md，描述为 Perflib 官方语义）：

指标名描述类型标签
windows_cache_async_copy_reads_totalNumber of times that a filesystem, such as NTFS, maps a page of a file into the file system cache to read a page.counterNone
windows_cache_async_data_maps_totalNumber of times that a filesystem, such as NTFS, maps a page of a file into the file system cache to read the page, and wishes to wait for the page to be retrieved if it is not in main memory.counterNone
windows_cache_async_fast_reads_totalNumber of reads from the file system cache that bypass the installed file system and retrieve the data directly from the cache.counterNone
windows_cache_async_mdl_reads_totalNumber of reads from the file system cache that use a Memory Descriptor List (MDL) to access the pages.counterNone
windows_cache_async_pin_reads_totalNumber of reads from the file system cache preparatory to writing the data back to disk. Pages read in this fashion are pinned in memory at the completion of the read.counterNone
windows_cache_copy_read_hits_totalNumber of copy read requests that hit the cache, that is, they did not require a disk read in order to provide access to the page in the cache.counterNone
windows_cache_copy_reads_totalNumber of reads from pages of the file system cache that involve a memory copy of the data from the cache to the application's buffer.counterNone
windows_cache_data_flushes_totalNumber of times the file system cache has flushed its contents to disk as the result of a request to flush or to satisfy a write-through file write request.counterNone
windows_cache_data_flush_pages_totalNumber of pages the file system cache has flushed to disk as a result of a request to flush or to satisfy a write-through file write request.counterNone
windows_cache_data_map_hits_totalNumber of data maps in the file system cache that could be resolved without having to retrieve a page from the disk, because the page was already in physical memory.counterNone
windows_cache_data_map_pins_totalNumber of data maps in the file system cache that resulted in pinning a page in main memory, an action usually preparatory to writing to the file on disk.counterNone
windows_cache_data_maps_totalNumber of times that a file system such as NTFS, maps a page of a file into the file system cache to read the page.counterNone
windows_cache_dirty_pagesNumber of dirty pages on the system cache.gaugeNone
windows_cache_dirty_page_thresholdThreshold for number of dirty pages on system cache.gaugeNone
windows_cache_fast_read_not_possibles_totalNumber of attempts by an Application Program Interface (API) function call to bypass the file system to get to data in the file system cache that could not be honored without invoking the file system.counterNone
windows_cache_fast_read_resource_misses_totalNumber of cache misses necessitated by the lack of available resources to satisfy the request.counterNone
windows_cache_fast_reads_totalNumber of reads from the file system cache that bypass the installed file system and retrieve the data directly from the cache.counterNone
windows_cache_lazy_write_flushes_totalNumber of Lazy Write flushes the Lazy Writer thread has written to disk. Lazy Writing is the process of updating the disk after the page has been changed in memory, so that the application that changed the file does not have to wait for the disk write to be complete before proceeding.counterNone
windows_cache_lazy_write_pages_totalNumber of Lazy Write pages the Lazy Writer thread has written to disk. Lazy Writing is the process of updating the disk after the page has been changed in memory, so that the application that changed the file does not have to wait for the disk write to be complete before proceeding.counterNone
windows_cache_mdl_read_hits_totalNumber of Memory Descriptor List (MDL) Read requests to the file system cache that hit the cache, i.e., did not require disk accesses in order to provide memory access to the page(s) in the cache.counterNone
windows_cache_mdl_reads_totalNumber of reads from the file system cache that use a Memory Descriptor List (MDL) to access the data.counterNone
windows_cache_pin_read_hits_totalNumber of pin read requests that hit the file system cache, i.e., did not require a disk read in order to provide access to the page in the file system cache. While pinned, a page's physical address in the file system cache will not be altered.counterNone
windows_cache_pin_reads_totalNumber of reads into the file system cache preparatory to writing the data back to disk. Pages read in this fashion are pinned in memory at the completion of the read. While pinned, a page's physical address in the file system cache will not be altered.counterNone
windows_cache_read_aheads_totalNumber of reads from the file system cache in which the Cache detects sequential access to a file. The read aheads permit the data to be transferred in larger blocks than those being requested by the application, reducing the overhead per access.counterNone
windows_cache_sync_copy_reads_totalNumber of reads from pages of the file system cache that involve a memory copy of the data from the cache to the application's buffer. The file system will not regain control until the copy operation is complete, even if the disk must be accessed to retrieve the page.counterNone
windows_cache_sync_data_maps_totalNumber of times that a file system such as NTFS maps a page of a file into the file system cache to read the page.counterNone
windows_cache_sync_fast_reads_totalNumber of reads from the file system cache that bypass the installed file system and retrieve the data directly from the cache. If the data is not in the cache, the request (application program call) will wait until the data has been retrieved from disk.counterNone
windows_cache_sync_mdl_reads_totalNumber of reads from the file system cache that use a Memory Descriptor List (MDL) to access the pages. If the accessed page(s) are not in main memory, the caller will wait for the pages to fault in from the disk.counterNone
windows_cache_sync_pin_reads_totalNumber of reads into the file system cache preparatory to writing the data back to disk. The file system will not regain control until the page is pinned in the file system cache, in particular if the disk must be accessed to retrieve the page.counterNone

五、指标语义分组解读

上面的 29 个指标虽然数量多，但可以按语义分成几组，便于理解和制定监控策略。

5.1 读取路径类（Reads）

  • Fast Reads（*_fast_reads_total）：绕过已安装文件系统驱动、直接从缓存取数的读取，是缓存收益最直接的体现；
  • Copy Reads（*_copy_reads_total）：需要把缓存页数据复制到应用程序缓冲区的读取；
  • MDL Reads（*_mdl_reads_total）：通过 Memory Descriptor List（内存描述符列表）访问缓存页的读取；
  • Pin Reads（*_pin_reads_total）：为回写磁盘做准备的读取，读取完成后页会被固定在内存中（pinned），固定期间其物理地址不会被改变；
  • Read Aheads（read_aheads_total）：缓存检测到顺序访问时进行的预读，允许以大于应用请求的块传输数据，降低单次访问开销。

以上几类读取又都分为async（异步）与sync（同步）两种变体：异步变体（如async_fast_reads_total）表示调用方不等待磁盘取页；同步变体（如sync_fast_reads_total）表示若数据不在缓存中，调用会阻塞等待从磁盘取回。

5.2 命中率类（Hits）

  • copy_read_hits_total、mdl_read_hits_total、pin_read_hits_total：分别对应 Copy Read、MDL Read、Pin Read 请求中**命中缓存（无需磁盘读取）**的次数，用于计算缓存命中率；
  • fast_read_resource_misses_total：因资源不足导致的缓存未命中次数，可用于发现缓存服务因内存或资源紧张而失效的情况。

5.3 数据映射类（Data Maps）

  • data_maps_total：文件系统（如 NTFS）将文件页映射进缓存以读取页的次数；
  • data_map_pins_total：映射过程中把页固定在内存中的次数（通常是为写回磁盘做准备）；
  • data_map_hits_total：页已在物理内存中、无需从磁盘取页即可完成解析的映射次数。

5.4 脏页与写回类（Dirty Pages / Flushes / Lazy Write）

  • dirty_pages（gauge）：系统缓存中脏页（已被修改、尚未写回磁盘的页）的当前数量；
  • dirty_page_threshold（gauge）：脏页数量的阈值，可据此评估脏页是否逼近上限；
  • data_flushes_total/data_flush_pages_total：因 flush 请求或 write-through 写请求而刷盘的总次数 / 总页数；
  • lazy_write_flushes_total/lazy_write_pages_total：Lazy Writer 线程延迟写回的刷新次数 / 页数。延迟写（Lazy Writing）允许修改文件的应用不必等待磁盘写完成即可继续执行。

六、示例查询：在 Prometheus 中使用这些指标

6.1 官方示例：Copy Read 命中率

文档给出的示例是计算"Copy Read 命中缓存的比例（百分比）"：

windows_cache_copy_read_hits_total / windows_cache_copy_reads_total * 100

6.2 基于指标语义扩展的查询

虽然官方文档目前标注 "Useful queries" 为空（欢迎社区贡献），但根据上述指标定义，可以安全地构建以下常用查询：

  • Copy Read 命中率（按时间速率，更接近实时状态）：
rate(windows_cache_copy_read_hits_total[5m]) / rate(windows_cache_copy_reads_total[5m]) * 100
  • MDL Read 命中率：
rate(windows_cache_mdl_read_hits_total[5m]) / rate(windows_cache_mdl_reads_total[5m]) * 100
  • Pin Read 命中率：
rate(windows_cache_pin_read_hits_total[5m]) / rate(windows_cache_pin_reads_total[5m]) * 100
  • Fast Read 速率（观察缓存旁路读取的吞吐）：
rate(windows_cache_fast_reads_total[5m])
  • 脏页占比（相对阈值）：
windows_cache_dirty_pages / windows_cache_dirty_page_threshold * 100
  • Lazy Write 刷盘速率（观察后台写回压力）：
rate(windows_cache_lazy_write_flushes_total[5m])

需要注意的是：由于这些指标均为无标签的全局计数器/计量器，查询时无需按实例或标签过滤；*_total结尾的 counter 指标在绘图时建议使用rate()或increase()，两个 gauge 指标（dirty_pages、dirty_page_threshold）则可以直接取值或求比值。

6.3 告警示例现状

官方文档明确标注 Alerting examples 目前为空（"This collector does not yet have alerting examples, we would appreciate your help adding them!"）。若你需要配置告警，可基于上面 6.2 的命中率与脏页占比表达式自行设置阈值规则，例如"Copy Read 命中率低于某阈值持续 10 分钟"。

七、实现细节核对：文档与源码的两处差异

在对照 docs/collector.cache.md 与源码时，可以发现两处值得注意的差异（均以当前仓库源码为准）：

  1. windows_cache_copy_read_hits_total的指标类型：文档将其标注为counter，但 cache.go 的Collect方法中以prometheus.GaugeValue输出该指标。其对应 Perflib 计数器名是 "Copy Read Hits %"（百分比值，见 types.go），因此按 gauge 输出在语义上更合理。
  2. data_map_hits相关指标名：文档表格列出的是windows_cache_data_map_hits_total，而当前源码实际暴露的是windows_cache_data_map_hits_percent（同样对应 Perflib 的 "Data Map Hits %"，以GaugeValue输出）。从 types.go 中的DataMapHitsPercent float64 \perfdata:"Data Map Hits %"`` 字段可以确认这一点。

这两处差异说明文档可能滞后于实现；实际部署与查询时，请以 exporter 输出的指标名为准（curl /metrics | grep "^windows_cache"即可核对）。

八、测试与质量保障

cache collector 的测试位于 internal/collector/cache/cache_test.go，包含两类用例：

  • TestCollector：通过 internal/utils/testutils 中的testutils.TestCollector在 Windows 上验证 collector 能正常构建并采集到指标；
  • BenchmarkCollector：通过testutils.FuncBenchmarkCollector对采集路径做性能基准测试。

测试文件带有//go:build windows构建约束（cache.go 亦然），说明该 collector 仅面向 Windows 平台运行，这也与它依赖 Perflib 的事实吻合。

九、总结

cache collector 是 windows_exporter 中面向 Windows 文件系统缓存的一组轻量指标源：它默认不启用、无任何配置参数，通过 pdh 库直接读取 PerflibCache对象，输出 29 个无标签指标，涵盖异步/同步读取、Fast/Copy/MDL/Pin 读取、命中率、数据映射、脏页、刷盘与延迟写等维度。开启方式简单（--collectors.enabled=cache或配置文件collectors.enabled: cache），配合本文给出的命中率、脏页占比等 PromQL，即可在 Prometheus 中构建一套完整的文件系统缓存可观测方案。

延伸阅读：所有 collector 的文档索引见 docs/README.md，启用方式的完整说明见 README.md，全局配置示例见 docs/example_config.yml。

  • 可观测性
  • 指标监控

【免费下载链接】windows_exporter

Prometheus exporter for Windows machines

项目地址：https://gitcode.com/gh_mirrors/wi/windows_exporter
点击查看免费下载

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

标签： 网站建设 企业官网 项目流程 UI设计 前端开发

热门文章

文章分类

标签云

网站建设 响应式设计 用户体验 SEO优化 前端开发 小程序 电商平台 性能优化

相关文章

您可能感兴趣的其他内容

从Claude Code到pi：四个工具打造可审查的AI编程Agent
2026/10/14 18:15:08 网站建设

从Claude Code到pi：四个工具打造可审查的AI编程Agent

1. 当"全能"变成负担：我为什么从 Claude Code 切到 pi1.1 Claude Code 的强与重Claude Code 刚推出的时候我就开始用了，第一印象确实是"无所不能"——能直接改代码、能跑终端命令、能查文档、能关联各种外部工具，甚至还能…...

阅读更多 →
Qt日历控件与日期格式化：从官方示例到实战落地
2026/10/14 18:15:07 网站建设

Qt日历控件与日期格式化：从官方示例到实战落地

如果你在 Qt 安装目录里翻过自带 Examples，大概会看到一个叫 Calendar Widget 的入口。它不像图像处理示例那样花哨，也没有网络通信那种工程复杂度，就是一个日历控件配合日期编辑框的小对话框。但我想认真地说一句：这个例子是理解…...

阅读更多 →
2026企业微信费用，不同规模企业成本参考指南
2026/10/14 18:14:12 网站建设

2026企业微信费用，不同规模企业成本参考指南

企业微信的基础通讯、考勤、审批等能力可直接使用,认证、外部联系人扩容、会话存档及各类高级增值模块则按需付费。许多企业在选型阶段容易混淆基础功能与增值服务,导致预算估算出现偏差。本文结合2026年收费逻辑,从微型、小型、中型、大型企业四个维度拆解成本构成,梳理各项付…...

阅读更多 →

需要专业的网站建设服务？

联系我们获取免费的网站建设咨询和方案报价，让我们帮助您实现业务目标

立即咨询