windows_exporter/docs/collector.mscluster.md

mscluster_cluster collector

The collector exposes Windows failover cluster metrics. All subcollectors read through the read-only Windows Cluster API (ClusAPI) instead of the root\MSCluster WMI provider. shared_volumes reads the partitions of every storage class resource with CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO_EX, the source of the former MSCluster_DiskPartition class, and keeps its whole-megabyte resolution. Metric names, types, labels and units are unchanged.

Each subcollector opens its cluster handle on its first scrape so a transient cluster-service failure is reported during collection; a handle whose RPC binding broke (for example after a cluster service restart) is reopened on the next scrape. ClusAPI calls cannot be cancelled while they are running. The subcollectors check the remaining scrape budget before starting each native call and stop waiting when the budget is spent. A call that is still running then makes the next scrapes of the same subcollector fail fast until it returns, while the other subcollectors keep publishing.

If a property of the cluster or of a network, node, resource or group cannot be read, its sample is omitted and the scrape reports an error; valid properties and other objects are retained. Invalid resource identities are not published. Missing native values are not substituted with zero. Objects deleted during a scrape are skipped. Names decode like the WMI strings did: up to the first NUL, with invalid UTF-16 replaced by U+FFFD. Values that the WMI provider synthesized are reproduced, so the series stay unchanged: for example mscluster_resource_subclass is always 0, because MSCluster_Resource.Subclass is NULL for every resource.

The ClusAPI functions in use are available since Windows Server 2008 R2. The cold_start_setting and resiliency_period group properties and the status_information node property exist since Windows Server 2016; on older versions these samples are omitted without an error. Cluster properties that Microsoft documents as added in Windows Server 2016 (for example s2d_enabled or cluster_functional_level) are omitted the same way. As before, mscluster_node_detected_cloud_platform is 0 before Windows Server 2022 unless the node reports the property, and the cluster metrics detect_managed_events, detect_managed_events_threshold, security_level_for_storage, max_number_of_nodes and detected_cloud_platform are published only on Windows Server 2022 and newer.

Metric name prefix	mscluster
Windows API	ClusAPI (clusapi.dll)
Enabled by default?	No

Storage pool and virtual disk metrics (for example of Storage Spaces Direct) are exposed by the storage_spaces collector.

Flags

--collector.mscluster.enabled

Comma-separated list of collectors to use, for example: --collector.mscluster.enabled=cluster,network,node,resource,resourcegroup,shared_volumes. Matching is case-sensitive. All of these subcollectors are enabled by default.

Metrics

Cluster

Name	Description	Type	Labels
windows_mscluster_cluster_add_evict_delay_seconds	Provides access to the cluster's AddEvictDelay property, which is the number of seconds that a new node is delayed after an eviction of another node.	gauge	cluster
windows_mscluster_cluster_admin_access_point	The type of the cluster administrative access point.	gauge	cluster
windows_mscluster_cluster_auto_assign_node_site	Determines whether or not the cluster will attempt to automatically assign nodes to sites based on networks and Active Directory Site information.	gauge	cluster
windows_mscluster_cluster_auto_balancer_level	Determines the level of aggressiveness of AutoBalancer.	gauge	cluster
windows_mscluster_cluster_auto_balancer_mode	Determines whether or not the auto balancer is enabled.	gauge	cluster
windows_mscluster_cluster_backup_in_progress	Indicates whether a backup is in progress.	gauge	cluster
windows_mscluster_cluster_block_cache_size_bytes	CSV BlockCache size in bytes.	gauge	cluster
windows_mscluster_cluster_clus_svc_hang_timeout_seconds	Controls how long, in seconds, the cluster network driver waits between Failover Cluster Service heartbeats before it determines that the Failover Cluster Service has stopped responding.	gauge	cluster
windows_mscluster_cluster_clus_svc_regroup_opening_timeout_seconds	Controls how long, in seconds, a node will wait on other nodes in the opening stage before deciding that they failed.	gauge	cluster
windows_mscluster_cluster_clus_svc_regroup_pruning_timeout_seconds	Controls how long, in seconds, the membership leader will wait to reach full connectivity between cluster nodes.	gauge	cluster
windows_mscluster_cluster_clus_svc_regroup_stage_timeout_seconds	Controls how long, in seconds, a node will wait on other nodes in a membership stage before deciding that they failed.	gauge	cluster
windows_mscluster_cluster_clus_svc_regroup_tick_seconds	Controls how frequently, in seconds, the membership algorithm is sending periodic membership messages.	gauge	cluster
windows_mscluster_cluster_cluster_enforced_anti_affinity	Enables or disables hard enforcement of group anti-affinity classes.	gauge	cluster
windows_mscluster_cluster_cluster_functional_level	The functional level the cluster is currently running in.	gauge	cluster
windows_mscluster_cluster_cluster_group_wait_delay_seconds	Maximum time in seconds that a group waits for its preferred node to come online during cluster startup before coming online on a different node.	gauge	cluster
windows_mscluster_cluster_cluster_log_level	Controls the level of cluster logging.	gauge	cluster
windows_mscluster_cluster_cluster_log_size_bytes	Controls the maximum size, in bytes, of the cluster log files on each of the nodes.	gauge	cluster
windows_mscluster_cluster_cluster_upgrade_version	Specifies the upgrade version the cluster is currently running in.	gauge	cluster
windows_mscluster_cluster_cross_site_delay_seconds	Controls how long the cluster network driver waits in seconds between sending Cluster Service heartbeats across sites.	gauge	cluster
windows_mscluster_cluster_cross_site_threshold	Controls how many Cluster Service heartbeats can be missed across sites before it determines that Cluster Service has stopped responding.	gauge	cluster
windows_mscluster_cluster_cross_subnet_delay_seconds	Controls how long the cluster network driver waits in seconds between sending Cluster Service heartbeats across subnets.	gauge	cluster
windows_mscluster_cluster_cross_subnet_threshold	Controls how many Cluster Service heartbeats can be missed across subnets before it determines that Cluster Service has stopped responding.	gauge	cluster
windows_mscluster_cluster_csv_balancer	Whether automatic balancing for CSV is enabled.	gauge	cluster
windows_mscluster_cluster_database_read_write_mode	Sets the database read and write mode.	gauge	cluster
windows_mscluster_cluster_default_network_role	Provides access to the cluster's DefaultNetworkRole property.	gauge	cluster
windows_mscluster_cluster_detected_cloud_platform	(DetectedCloudPlatform)	gauge	cluster
windows_mscluster_cluster_detect_managed_events	(DetectManagedEvents)	gauge	cluster
windows_mscluster_cluster_detect_managed_events_threshold	(DetectManagedEventsThreshold)	gauge	cluster
windows_mscluster_cluster_disable_group_preferred_owner_randomization	(DisableGroupPreferredOwnerRandomization)	gauge	cluster
windows_mscluster_cluster_drain_on_shutdown	Whether to drain the node when cluster service is being stopped.	gauge	cluster
windows_mscluster_cluster_dynamic_quorum_enabled	Allows cluster service to adjust node weights as needed to increase availability.	gauge	cluster
windows_mscluster_cluster_enable_shared_volumes	Enables or disables cluster shared volumes on this cluster.	gauge	cluster
windows_mscluster_cluster_fix_quorum	Provides access to the cluster's FixQuorum property, which specifies if the cluster is in a fix quorum state.	gauge	cluster
windows_mscluster_cluster_grace_period_enabled	Whether the node grace period feature of this cluster is enabled.	gauge	cluster
windows_mscluster_cluster_grace_period_timeout_seconds	The grace period timeout in seconds.	gauge	cluster
windows_mscluster_cluster_group_dependency_timeout_seconds	The timeout in seconds after which a group will be brought online despite unsatisfied dependencies	gauge	cluster
windows_mscluster_cluster_hang_recovery_action	Controls the action to take if the user-mode processes have stopped responding.	gauge	cluster
windows_mscluster_cluster_ignore_persistent_state_on_startup	Provides access to the cluster's IgnorePersistentStateOnStartup property, which specifies whether the cluster will bring online groups that were online when the cluster was shut down.	gauge	cluster
windows_mscluster_cluster_log_resource_controls	Controls the logging of resource controls.	gauge	cluster
windows_mscluster_cluster_lower_quorum_priority_node_id	Specifies the Node ID that has a lower priority when voting for quorum is performed. If the quorum vote is split 50/50%, the specified node's vote would be ignored to break the tie. If this is not set then the cluster will pick a node at random to break the tie.	gauge	cluster
windows_mscluster_cluster_max_number_of_nodes	Indicates the maximum number of nodes that may participate in the Cluster.	gauge	cluster
windows_mscluster_cluster_message_buffer_length	The maximum unacknowledged message count for GEM.	gauge	cluster
windows_mscluster_cluster_minimum_never_preempt_priority	Groups with this priority or higher cannot be preempted.	gauge	cluster
windows_mscluster_cluster_minimum_preemptor_priority	Minimum priority a cluster group must have to be able to preempt another group.	gauge	cluster
windows_mscluster_cluster_netft_ip_sec_enabled	Whether IPSec is enabled for cluster internal traffic.	gauge	cluster
windows_mscluster_cluster_placement_options	Various option flags to modify default placement behavior.	gauge	cluster
windows_mscluster_cluster_plumb_all_cross_subnet_routes	Plumbs all possible cross subnet routes to all nodes.	gauge	cluster
windows_mscluster_cluster_prevent_quorum	Whether the cluster will ignore group persistent state on startup.	gauge	cluster
windows_mscluster_cluster_quarantine_duration_seconds	The quarantine period timeout in seconds.	gauge	cluster
windows_mscluster_cluster_quarantine_threshold	Number of node failures before it will be quarantined.	gauge	cluster
windows_mscluster_cluster_quorum_arbitration_time_max_seconds	Controls the maximum time, in seconds, necessary to decide the Quorum owner node.	gauge	cluster
windows_mscluster_cluster_quorum_arbitration_time_min_seconds	Controls the minimum time, in seconds, necessary to decide the Quorum owner node.	gauge	cluster
windows_mscluster_cluster_quorum_type_value	Get the current quorum type value. -1: Unknown; 1: Node; 2: FileShareWitness; 3: Storage; 4: None	gauge	cluster
windows_mscluster_cluster_request_reply_timeout_seconds	Controls the request reply time-out period in seconds.	gauge	cluster
windows_mscluster_cluster_resiliency_default_period_seconds	The default resiliency period, in seconds, for the cluster.	gauge	cluster
windows_mscluster_cluster_resiliency_level	The resiliency level for the cluster.	gauge	cluster
windows_mscluster_cluster_root_memory_reserved_bytes	Controls the amount of memory, in bytes, reserved for the parent partition on all cluster nodes.	gauge	cluster
windows_mscluster_cluster_route_history_length	The history length for routes to help finding network issues.	gauge	cluster
windows_mscluster_cluster_s2d_bus_types	Bus types for storage spaces direct.	gauge	cluster
windows_mscluster_cluster_s2d_cache_desired_state	Desired state of the storage spaces direct cache.	gauge	cluster
windows_mscluster_cluster_s2d_cache_flash_reserve_ratio	Ratio (0-1) of allocated flash space to utilize when caching.	gauge	cluster
windows_mscluster_cluster_s2d_cache_page_size_bytes	Page size in bytes used by S2D cache.	gauge	cluster
windows_mscluster_cluster_s2d_enabled	Whether direct attached storage (DAS) is enabled.	gauge	cluster
windows_mscluster_cluster_s2dio_latency_threshold_seconds	The I/O latency threshold in seconds for storage spaces direct.	gauge	cluster
windows_mscluster_cluster_s2d_optimizations	Optimization flags for storage spaces direct.	gauge	cluster
windows_mscluster_cluster_same_subnet_delay_seconds	Controls how long the cluster network driver waits in seconds between sending Cluster Service heartbeats on the same subnet.	gauge	cluster
windows_mscluster_cluster_same_subnet_threshold	Controls how many Cluster Service heartbeats can be missed on the same subnet before it determines that Cluster Service has stopped responding.	gauge	cluster
windows_mscluster_cluster_security_level	Controls the level of security that should apply to intracluster messages. 0: Clear Text; 1: Sign; 2: Encrypt	gauge	cluster
windows_mscluster_cluster_security_level_for_storage	(SecurityLevelForStorage)	gauge	cluster
windows_mscluster_cluster_shared_volume_vss_writer_operation_timeout_seconds	CSV VSS Writer operation timeout in seconds.	gauge	cluster
windows_mscluster_cluster_shutdown_timeout_seconds	The maximum time in seconds allowed for cluster resources to come offline during cluster service shutdown.	gauge	cluster
windows_mscluster_cluster_use_client_access_networks_for_shared_volumes	Whether the use of client access networks for cluster shared volumes feature of this cluster is enabled. 0: Disabled; 1: Enabled; 2: Auto	gauge	cluster
windows_mscluster_cluster_witness_database_write_timeout_seconds	Controls the maximum time in seconds that a cluster database write to a witness can take before the write is abandoned.	gauge	cluster
windows_mscluster_cluster_witness_dynamic_weight	The weight of the configured witness.	gauge	cluster
windows_mscluster_cluster_witness_restart_interval_seconds	Controls the witness restart interval in seconds.	gauge	cluster

Network

Name	Description	Type	Labels
windows_mscluster_network_characteristics	Provides the characteristics of the network. The cluster defines characteristics only for resources. For a description of these characteristics, see CLUSCTL_RESOURCE_GET_CHARACTERISTICS.	gauge	network
windows_mscluster_network_flags	Provides access to the flags set for the network. The cluster defines flags only for resources. For a description of these flags, see CLUSCTL_RESOURCE_GET_FLAGS.	gauge	network
windows_mscluster_network_metric	The metric of a cluster network (networks with lower values are used first). If this value is set, then the AutoMetric property is set to false.	gauge	network
windows_mscluster_network_role	Provides access to the network's Role property. The Role property describes the role of the network in the cluster. 0: None; 1: Cluster; 2: Client; 3: Both	gauge	network
windows_mscluster_network_state	Provides the current state of the network. 1-1: Unknown; 0: Unavailable; 1: Down; 2: Partitioned; 3: Up	gauge	network

Node

Name	Description	Type	Labels
windows_mscluster_node_build_number	Provides access to the node's BuildNumber property.	gauge	node
windows_mscluster_node_characteristics	Provides access to the characteristics set for the node. For a list of possible characteristics, see CLUSCTL_NODE_GET_CHARACTERISTICS.	gauge	node
windows_mscluster_node_detected_cloud_platform	(DetectedCloudPlatform)	gauge	node
windows_mscluster_node_dynamic_weight	The dynamic vote weight of the node adjusted by dynamic quorum feature.	gauge	node
windows_mscluster_node_flags	Provides access to the flags set for the node. For a list of possible characteristics, see CLUSCTL_NODE_GET_FLAGS.	gauge	node
windows_mscluster_node_major_version	Provides access to the node's MajorVersion property, which specifies the major portion of the Windows version installed.	gauge	node
windows_mscluster_node_minor_version	Provides access to the node's MinorVersion property, which specifies the minor portion of the Windows version installed.	gauge	node
windows_mscluster_node_needs_prevent_quorum	Whether the cluster service on that node should be started with prevent quorum flag.	gauge	node
windows_mscluster_node_node_drain_status	The current node drain status of a node. 0: Not Initiated; 1: In Progress; 2: Completed; 3: Failed	gauge	node
windows_mscluster_node_node_highest_version	Provides access to the node's NodeHighestVersion property, which specifies the highest possible version of the cluster service with which the node can join or communicate.	gauge	node
windows_mscluster_node_node_lowest_version	Provides access to the node's NodeLowestVersion property, which specifies the lowest possible version of the cluster service with which the node can join or communicate.	gauge	node
windows_mscluster_node_node_weight	The vote weight of the node.	gauge	node
windows_mscluster_node_state	Returns the current state of a node. -1: Unknown; 0: Up; 1: Down; 2: Paused; 3: Joining	gauge	node
windows_mscluster_node_status_information	The isolation or quarantine status of the node.	gauge	node

Resource

Name	Description	Type	Labels
windows_mscluster_resource_characteristics	Provides the characteristics of the object. The cluster defines characteristics only for resources. For a description of these characteristics, see CLUSCTL_RESOURCE_GET_CHARACTERISTICS.	gauge	type, resource_group, resource
windows_mscluster_resource_deadlock_timeout_seconds	Indicates the length of time to wait, in seconds, before declaring a deadlock in any call into a resource.	gauge	type, resource_group, resource
windows_mscluster_resource_embedded_failure_action	The time, in milliseconds, that a resource should remain in a failed state before the Cluster service attempts to restart it.	gauge	type, resource_group, resource
windows_mscluster_resource_flags	Provides access to the flags set for the object. The cluster defines flags only for resources. For a description of these flags, see CLUSCTL_RESOURCE_GET_FLAGS.	gauge	type, resource_group, resource
windows_mscluster_resource_is_alive_poll_interval_seconds	Provides access to the resource's IsAlivePollInterval property, which is the recommended interval in seconds at which the Cluster Service should poll the resource to determine whether it is operational. The series is omitted while the resource uses the interval of its resource type (0xFFFFFFFF).	gauge	type, resource_group, resource
windows_mscluster_resource_looks_alive_poll_interval_seconds	Provides access to the resource's LooksAlivePollInterval property, which is the recommended interval in seconds at which the Cluster Service should poll the resource to determine whether it appears operational. The series is omitted while the resource uses the interval of its resource type (0xFFFFFFFF).	gauge	type, resource_group, resource
windows_mscluster_resource_monitor_process_id	Provides the process ID of the resource host service that is currently hosting the resource.	gauge	type, resource_group, resource
windows_mscluster_resource_owner_node	The node hosting the resource. 0: Not hosted; 1: Hosted	gauge	type, resource_group, node, resource
windows_mscluster_resource_pending_timeout_seconds	Provides access to the resource's PendingTimeout property. If a resource cannot be brought online or taken offline in the number of seconds specified by the PendingTimeout property, the resource is forcibly terminated.	gauge	type, resource_group, resource
windows_mscluster_resource_resource_class	Gets or sets the resource class of a resource. 0: Unknown; 1: Storage; 2: Network; 32768: Unknown	gauge	type, resource_group, resource
windows_mscluster_resource_restart_action	Provides access to the resource's RestartAction property, which is the action to be taken by the Cluster Service if the resource fails.	gauge	type, resource_group, resource
windows_mscluster_resource_restart_delay_seconds	Indicates the time delay in seconds before a failed resource is restarted.	gauge	type, resource_group, resource
windows_mscluster_resource_restart_period_seconds	Provides access to the resource's RestartPeriod property, which is interval of time, in seconds, during which a specified number of restart attempts can be made on a nonresponsive resource.	gauge	type, resource_group, resource
windows_mscluster_resource_restart_threshold	Provides access to the resource's RestartThreshold property which is the maximum number of restart attempts that can be made on a resource within an interval defined by the RestartPeriod property before the Cluster Service initiates the action specified by the RestartAction property.	gauge	type, resource_group, resource
windows_mscluster_resource_retry_period_on_failure_seconds	Provides access to the resource's RetryPeriodOnFailure property, which is the interval of time (in seconds) that a resource should remain in a failed state before the Cluster service attempts to restart it.	gauge	type, resource_group, resource
windows_mscluster_resource_state	The current state of the resource. -1: Unknown; 0: Inherited; 1: Initializing; 2: Online; 3: Offline; 4: Failed; 128: Pending; 129: Online Pending; 130: Offline Pending	gauge	type, resource_group, resource
windows_mscluster_resource_subclass	Provides the list of references to nodes that can be the owner of this resource.	gauge	type, resource_group, resource

ResourceGroup

Name	Description	Type	Labels
windows_mscluster_resourcegroup_auto_failback_type	Provides access to the group's AutoFailbackType property.	gauge	resource_group
windows_mscluster_resourcegroup_characteristics	Provides the characteristics of the group. The cluster defines characteristics only for resources. For a description of these characteristics, see CLUSCTL_RESOURCE_GET_CHARACTERISTICS.	gauge	resource_group
windows_mscluster_resourcegroup_cold_start_setting	Indicates whether a group can start after a cluster cold start.	gauge	resource_group
windows_mscluster_resourcegroup_default_owner	Number of the last node the resource group was activated on or explicitly moved to.	gauge	resource_group
windows_mscluster_resourcegroup_failback_window_end	The FailbackWindowEnd property provides the latest time that the group can be moved back to the node identified as its preferred node.	gauge	resource_group
windows_mscluster_resourcegroup_failback_window_start	The FailbackWindowStart property provides the earliest time (that is, local time as kept by the cluster) that the group can be moved back to the node identified as its preferred node.	gauge	resource_group
windows_mscluster_resourcegroup_failover_period_seconds	The FailoverPeriod property specifies a number of seconds during which a maximum number of failover attempts, specified by the FailoverThreshold property, can occur. Windows stores it in hours.	gauge	resource_group
windows_mscluster_resourcegroup_failover_threshold	The FailoverThreshold property specifies the maximum number of failover attempts.	gauge	resource_group
windows_mscluster_resourcegroup_flags	Provides access to the flags set for the group. The cluster defines flags only for resources. For a description of these flags, see CLUSCTL_RESOURCE_GET_FLAGS.	gauge	resource_group
windows_mscluster_resourcegroup_group_type	The Type of the resource group.	gauge	resource_group
windows_mscluster_resourcegroup_owner_node	The node hosting the resource group. 0: Not hosted; 1: Hosted	gauge	node, resource_group
windows_mscluster_resourcegroup_priority	Priority value of the resource group	gauge	resource_group
windows_mscluster_resourcegroup_resiliency_period_seconds	The resiliency period for this group, in seconds.	gauge	resource_group
windows_mscluster_resourcegroup_state	The current state of the resource group. -1: Unknown; 0: Online; 1: Offline; 2: Failed; 3: Partial Online; 4: Pending	gauge	resource_group

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.

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. The sub-collector reports both. Pool and virtual disk metrics, which only exist for Storage Spaces Direct, are in the storage_spaces 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	shared_volume,path,volume_guid
windows_mscluster_shared_volumes_total_bytes	Total size of the Cluster Shared Volume in bytes	gauge	shared_volume,volume_guid
windows_mscluster_shared_volumes_free_bytes	Free space on the Cluster Shared Volume in bytes	gauge	shared_volume,volume_guid

Example metric

Query the state of all cluster resource owned by node1

windows_mscluster_resource_owner_node{node="node1"}

Useful queries

Counts the number of Network Name cluster resource

count(windows_mscluster_resource_state{type="Network Name"})

Alerting examples

Low free space on cluster shared volume

# Alerts if volume has less then 20% free space
- alert: LowCSVFreeSpace
    expr: |
        (
        max by (shared_volume, cluster) (windows_mscluster_shared_volumes_free_bytes{shared_volume!="ClusterPerformanceHistory"})
        /
        max by (shared_volume, cluster) (windows_mscluster_shared_volumes_total_bytes{shared_volume!="ClusterPerformanceHistory"})
        ) * 100 < 20
    for: 10m
    labels:
        severity: warning
    annotations:
        summary: "Low CSV free space on {{ $labels.shared_volume }}"
        description: |
        Cluster Shared Volume {{ $labels.shared_volume }} on cluster {{ $labels.cluster }} has less than 20% free space (current: {{ printf "%.2f" $value }}%)