From 3436b785fdde9ce80b1dbf73d55daa7db27e0da8 Mon Sep 17 00:00:00 2001 From: Dominik Eisenberg <64131471+Dominik-esb@users.noreply.github.com> Date: Thu, 15 Oct 2026 16:45:22 +0200 Subject: [PATCH] docs: clarify Hyper-V DataStore, Cluster Shared Volumes and storage pools (#2711) Signed-off-by: EisenbergD Co-authored-by: EisenbergD Co-authored-by: Claude Opus 5.5 --- docs/collector.hyperv.md | 16 ++++++++++++++-- docs/collector.mscluster.md | 15 +++++++++++++++ docs/collector.storage_spaces.md | 7 +++++++ 3 files changed, 36 insertions(+), 2 deletions(-) diff --git a/docs/collector.hyperv.md b/docs/collector.hyperv.md index 0e5d1ea6..82762d7c 100644 --- a/docs/collector.hyperv.md +++ b/docs/collector.hyperv.md @@ -21,9 +21,21 @@ Scrapes publish the values of the last refresh. Default: `5m`. ## Metrics ### Hyper-V Datastore -### Hyper-V Datastore Metrics Documentation -This documentation outlines the available metrics for monitoring Hyper-V Datastore performance and resource usage using Prometheus. All metrics are prefixed with `windows_hyperv_datastore`. +Sub-collector `datastore`. It reads the `Hyper-V DataStore` performance counter set. Each virtual machine has its own +instances, named after the VM GUID, for example ` configuration file` and ` runtime file`. They +describe the files in which Hyper-V keeps the configuration and runtime state of the virtual machine (`.vmcx`, +`.vmrs`, see [virtual machine file types](https://learn.microsoft.com/en-us/windows-server/virtualization/hyper-v/deploy/upgrade-virtual-machine-version-in-hyper-v-on-windows-or-windows-server)), for example their fragmentation, free space in their tables and the reads and writes to them. All metrics are +prefixed with `windows_hyperv_datastore`. + +> [!NOTE] +> A Hyper-V DataStore is not a storage volume, unlike a datastore in VMware vSphere. These metrics don't report the +> capacity or usage of the volumes that hold the virtual machines. For Cluster Shared Volumes, use the `shared_volumes` +> sub-collector of the [`mscluster`](collector.mscluster.md) collector. For volumes of a single host, use the +> [`logical_disk`](collector.logical_disk.md) collector. +> +> The counter set has no instances on a host without virtual machines. The sub-collector then exports no +> `windows_hyperv_datastore_*` series and doesn't report an error. | Metric Name | Description | Type | Labels | |------------------------------------------------------------------------|---------------------------------------------------------------------------------|---------|-----------| diff --git a/docs/collector.mscluster.md b/docs/collector.mscluster.md index 6feee3e8..c3586d13 100644 --- a/docs/collector.mscluster.md +++ b/docs/collector.mscluster.md @@ -180,6 +180,21 @@ Matching is case-sensitive. All of these subcollectors are enabled by default. ### Shared Volumes +Sub-collector `shared_volumes`, available since v0.32.0. It reports the size and free space of the partitions of the +cluster's disk resources. This includes the Cluster Shared Volumes (CSV): a clustered file system that all nodes can +read and write at the same time, mounted under `C:\ClusterStorage` on every node. One node at a time coordinates a +CSV, and coordination moves between nodes, for example on failover or rebalancing. See +[Cluster Shared Volumes overview](https://learn.microsoft.com/en-us/windows-server/failover-clustering/failover-cluster-csvs). + +A CSV can be backed by Storage Spaces Direct (the local drives of the nodes, usually ReFS) or by SAN storage such as +Fibre Channel, iSCSI or SAS LUNs (usually NTFS), see +[failover cluster storage architectures](https://learn.microsoft.com/en-us/windows-server/failover-clustering/storage-architectures). The sub-collector reports both. Pool and virtual disk metrics, which +only exist for Storage Spaces Direct, are in the [`storage_spaces`](collector.storage_spaces.md) collector. + +> [!NOTE] +> Releases before v0.32.0 don't have this sub-collector and silently ignore `shared_volumes` in +> `--collector.mscluster.enabled`. + | Name | Description | Type | Labels | |------------------------------------------|----------------------------------------------------------------|-------|-----------------------------| | `windows_mscluster_shared_volumes_info` | Cluster Shared Volumes information (value is always 1) | gauge | `name`,`path`,`volume_guid` | diff --git a/docs/collector.storage_spaces.md b/docs/collector.storage_spaces.md index 03505bcf..a05b0587 100644 --- a/docs/collector.storage_spaces.md +++ b/docs/collector.storage_spaces.md @@ -3,6 +3,13 @@ The storage_spaces collector exposes metrics about Storage Spaces storage pools and virtual disks. It works on standalone hosts as well as on failover clusters using Storage Spaces Direct. +Storage pools and virtual disks only exist for Storage Spaces, for example the pool that Storage Spaces Direct builds +from the local drives of the cluster nodes. A failover cluster whose Cluster Shared Volumes are SAN LUNs (Fibre +Channel, iSCSI, SAS) has no storage pool, so this collector reports nothing there (see +[failover cluster storage architectures](https://learn.microsoft.com/en-us/windows-server/failover-clustering/storage-architectures)). The size and free space of Cluster +Shared Volumes are reported for both setups by the `shared_volumes` sub-collector of the +[`mscluster`](collector.mscluster.md) collector. + ||| -|- Metric name prefix | `storage_spaces`