Windows wmi metricset

Stack Beta 9.1.0

The wmi metricset of the Windows module reads metrics via Windows Management Instrumentation (WMI), a core management technology in the Windows Operating system.

By leveraging WMI Query Language (WQL), this metricset allows you to extract detailed system information and metrics to monitor the health and performance of Windows Systems.

This metricset leverages the Microsoft WMI, library a convenient wrapper around the GO-OLE library which allows to invoke the WMI Api.

This metricset supports the execution of WQL queries, a SQL-like query language for retrieving information from WMI namespaces.

Currently, the metricset supports queries with SELECT, FROM and WHERE clauses.

When working with WMI queries, it is the user’s responsibility to ensure that queries are safe, efficient, and do not cause unintended side effects. A notorious example of a problematic WMI class is Win32_Product. Read more in Windows Documentation.

Query execution is managed by the underlying WMI Framework, specifically the WMI Arbitrator. The Arbitrator is responsible for:

• Scheduling and controlling query execution

• Throttling or stopping queries based on system resource availability and conditions

There is no way to directly stop a query once it has started. To prevent Metricbeat from waiting indefinitely for a query to return a result or fail, Metricbeat has a timeout mechanism that stops waiting for query results after a specified timeout. This is controlled by the wmi.warning_threshold setting.

While Metricbeat stops waiting for the result, the underlying WMI query may continue running until the WMI Arbitrator decides to stop execution.

The microsoft/wmi library internally uses the WMI Scripting API. This API, as per the official WMI Documentation, does not provide direct type conversion for uint64, sint64, and datetime CIM types; instead, these values are returned as strings.

To ensure the correct data type is reported, Metricbeat dynamically fetches the CIM type definitions for the properties of the WMI instance classes involved in the query, and then performs the necessary data type conversions.

To optimize performance and avoid repeatedly fetching these schema definitions for every row and every request, an LRU cache is utilized. This cache stores the schema definition for each unique WMI class encountered. For queries involving superclasses, such as CIM_LogicalDevice, the cache will populate with individual entries for each specific derived class (leaf of the class hierarchy) whose instances are returned by the query (for example, Win32_DiskDrive or Win32_NetworkAdapter).

- module: windows
  metricsets: ["wmi"]
  period: 10m
  wmi:
    namespace: "root\\cimv2"
    warning_threshold: 10m
    include_queries: true
    include_null_properties: false
    include_empty_strings_properties: false
    max_rows_per_query: 100
    queries:
    - class: Win32_OperatingSystem
      properties:
      - FreePhysicalMemory
      - FreeSpaceInPagingFiles
      - NumberOfUsers
      where: ""
    - class: Win32_PowerPlan
      properties: []
      where: "IsActive = True"
      namespace: "root\\cimv2\\power"
		

1. Default Namespace
2. Overwrites the module namespace in this query

wmi.namespace

The default WMI namespace used for queries. This can be overridden per query. The default is root\cimv2.

wmi.warning_threshold

The time threshold after which Metricbeat will stop waiting for the query result and return control to the main flow of the program. A warning is logged indicating that the query execution has exceeded the threshold. The default is equal to the module's period. See WMI Arbitrator and Query Execution for more details.

wmi.include_query_class

If set to true the metricset includes the queried class. This is useful if superclasses are queried. The default value is false.

wmi.include_queries

If set to true the metricset includes the query in the output document. The default value is false.

wmi.include_null_properties

If set to true the metricset includes the properties that have null value in the output document. The default value is false.

wmi.include_empty_string_properties

A boolean option that causes the metricset to include the properties that are empty string. The default value is false.

wmi.max_rows_per_query

Limits the number of rows returned by a single WMI query. The default value is 0, which is a special value indicating that all fetched results should be returned without a row limit.

wmi.schema_cache_size

The maximum number of WMI class definitions that can be cached per single query. Every query keeps its own separate cache. This cache helps improve performance when dealing with queries that involve inheritance hierarchies. Read more in WMI Type Support. For example, if a superclass is queried, the cache might store all its derived classes (leaves of the class hierarchy) to optimize subsequent operations. The default value is 1000.

wmi.queries

The list of queries to execute. The list cannot be empty. See Query Configuration for the format of the queries.

Each item in the queries list specifies a WMI query to perform.

class

The WMI class. In the query it specifies the FROM clause. Required

properties

List of properties to return. In the query it specifies the SELECT clause. Set it to the empty list (default value) to retrieve all available properties.

where

The where clause. In the query it specifies the WHERE clause. Read more about the format in the Windows Documentation.

namespace

The WMI Namespace for this particular query (it overwrites the metricset’s namespace value)

Example WQL Query:

SELECT Name, ProcessId, WorkingSetSize
FROM Win32_Process
WHERE Name = 'lsass.exe' AND WorkingSetSize > 104857600
		

Equivalent YAML Configuration:

- class: Win32_Process
  properties:
  - Name
  - ProcessId
  - WorkingSetSize
  where: "Name = 'lsass.exe' AND WorkingSetSize > 104857600"
		

• Test your WMI queries in isolation using the Get-CimInstance PowerShell cmdlet or the WMI Explorer tool.

• Ensure that wmi.warning_threshold is less than or equal to the module's period. This configuration prevents Metricbeat from attempting to start multiple concurrent executions of the same query if a previous one is running slowly.

• When possible, try querying concrete (leaf) classes or classes closer to the leaves of the WMI inheritance hierarchy. Querying abstract superclasses may require fetching and caching the schema definitions for numerous derived classes, which can lead to increased memory usage and potential performance penalties due to cache misses.

• Set up alerts in Metricbeat for documents with the error.message field set.

• [Advanced] Configure collection of WMI-Activity Operational Logs (found in Event Viewer under Applications and Services Logs/Microsoft/Windows/WMI-Activity/Operational). These logs can be invaluable for correlating issues with Metricbeat WMI warnings or documents containing error.message.

This module has been tested on the following platform:

• Operating System: Microsoft Windows Server 2019 Datacenter

• Architecture: x64

Other Windows versions and architectures may also work but have not been explicitly tested.

For a description of each field in the metricset, see the exported fields section.

Here is an example document generated by this metricset:

{
    "@timestamp": "2024-12-12T15:46:39.622Z",
    "event": {
        "dataset": "windows.wmi",
        "duration": 58982500,
        "module": "windows"
    },
    "metricset": {
        "name": "wmi",
        "period": 10000
    },
    "service": {
        "type": "windows"
    },
    "windows": {
        "wmi": {
            "FreePhysicalMemory": 7537796,
            "FreeSpaceInPagingFiles": 2257908,
            "FreeVirtualMemory": 9694064,
            "LocalDateTime": "2024-12-12T15:46:39.62Z",
            "NumberOfUsers": 1,
            "class": "Win32_OperatingSystem",
            "namespace": "root\\cimv2"
        }
    }
}