Windows wmi metricset

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Windows wmi metricset

This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.

The wmi metricset of the Windows module collects 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. This allows invoking the Scripting API for WMI.

WMI Query Language (WQL) Support

edit

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.

WMI Arbitrator and Query Execution

edit

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.

Configuration

edit

- module: windows
  metricsets: ["wmi"]
  period: 10m
  wmi:
    namespace: "root\\cimv2" # Default Namespace
    warning_threshold: 10m
    include_queries: true
    include_null_properties: false
    include_empty_strings_properties: false
    queries:
    - class: Win32_OperatingSystem
      properties:
      - FreePhysicalMemory
      - FreeSpaceInPagingFiles
      - NumberOfUsers
      where: ""
    - class: Win32_PowerPlan
      properties: []
      where: "IsActive = True"
      namespace: "root\\cimv2\\power" # 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 period. See WMI Arbitrator and Query Execution for more details.
wmi.include_query_class: If set to true the metricset include the queried class. 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. properties that have a 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.queries: The list of queries to execute. The list cannot be empty. See Query Configuration for the format of the queries.

Query Configuration

edit

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

edit

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"

Best Practices

edit

Test your queries in isolation using the Get-CimInstance PowerShell cmdlet or the WMI Explorer.
Ensure that wmi.warning_threshold is less than or equal to the module’s period. This prevents starting intentionally multiple executions of the same query.
Set up alerts in Metricbeat logs for timeouts and empty query results. If a query frequently times out or returns no data, investigate the cause to prevent missing critical information.
[Advanced] Collect WMI-Activity Operational Logs to correlate with Metricbeat WMI warnings.

Compatibility

edit

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.

Fields

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"
        }
    }
}

« Windows service metricset ZooKeeper module »