elastic
diff --git a/‎docs/reference/metricbeat/metricbeat-metricset-windows-wmi.md‎
Lines changed: 0 additions & 210 deletions b/‎docs/reference/metricbeat/metricbeat-metricset-windows-wmi.md‎
Lines changed: 0 additions & 210 deletions
diff --git a/‎metricbeat/module/windows/wmi/_meta/docs.asciidoc‎
Lines changed: 51 additions & 10 deletions b/‎metricbeat/module/windows/wmi/_meta/docs.asciidoc‎
Lines changed: 51 additions & 10 deletions
@@ -1,11 +1,11 @@
-The `wmi` metricset of the Windows module collects metrics via link:https://learn.microsoft.com/en-us/windows/win32/wmisdk/about-wmi[Windows Management Instrumentation (WMI)], a core management technology in the Windows Operating system.
+The `wmi` metricset of the Windows module collects metrics via link:https://learn.microsoft.com/en-us/windows/win32/wmisdk/about-wmi[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 link:https://github.com/microsoft/wmi[Microsoft WMI] library, a
-convenient wrapper around the link:https://github.com/go-ole[Go-OLE] library. This allows invoking the
+convenient wrapper around the link:https://github.com/go-ole[Go-OLE] library, which allows to invoke the
 link:https://learn.microsoft.com/en-us/windows/win32/wmisdk/scripting-api-for-wmi[Scripting API for WMI].
 
 [float]
@@ -15,7 +15,7 @@ This metricset supports the execution of link:https://learn.microsoft.com/en-us/
 
 Currently, the metricset supports queries with `SELECT`, `FROM` and `WHERE` clauses.
 
-NOTE: 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 link:https://support.microsoft.com/kb/974524[Windows Documentation].
+NOTE: 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 link:https://learn.microsoft.com/en-us/troubleshoot/windows-server/admin-development/windows-installer-reconfigured-all-applications#more-information[Windows Documentation].
 
 [float]
 [[wmi-arbitrator-and-query-execution]]
@@ -31,6 +31,32 @@ There is no way to directly stop a query once it has started. To prevent Metricb
 
 NOTE: While Metricbeat stops waiting for the result, the underlying WMI query may continue running until the WMI Arbitrator decides to stop execution.
 
+[float]
+[[wmi-type-support]]
+==== WMI type support
+
+The `microsoft/wmi` library internally uses the WMI Scripting API. This API, as per the
+link:https://learn.microsoft.com/en-us/windows/win32/wmisdk/querying-wmi[official WMI Documentation],
+does not provide direct type conversion for `uint64`, `sint64`, and `datetime`
+link:https://learn.microsoft.com/en-us/windows/win32/wmisdk/common-information-model[Common Information Model] (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 returned by 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 WMI class-property pair 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`).
+
+NOTE: The properties of type `CIM_Object` (embedded objects) are not yet supported and are ignored.
+
+
+NOTE: Properties of type `CIM_Reference` (references), which are used in link:https://learn.microsoft.com/en-us/windows/win32/wmisdk/declaring-an-association-class[WMI Association Classes], are currently returned as string values exactly as reported by the 
+link:https://github.com/microsoft/wmi[Microsoft WMI] library.
+
 
 [float]
 === Configuration
@@ -79,6 +105,14 @@ properties that have a `null` value in the output document. The default value is
 *`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-property pairs 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,  WMI Type Support>>. For example, if a superclass is queried, the cache stores entries for each WMI concrete instance class (the leaves of the class hierarchy) and their associated properties. Therefore, querying a superclass that returns a result set containing instances of `10` different classes, each with `50` properties, will result in a cache size of `500` entries (`10×50`).
+The default value is `1000`.
+
 *`wmi.queries`*:: The list of queries to execute. The list cannot be empty. See <<query-configuration, Query Configuration>> for the format of the queries.
 
 [float]
@@ -123,23 +157,30 @@ Equivalent YAML Configuration:
 [float]
 === Best Practices
 
-- Test your queries in isolation using the `Get-CimInstance` PowerShell cmdlet or the WMI Explorer.
+- Test your queries in isolation using the link:https://learn.microsoft.com/en-us/powershell/module/cimcmdlets/get-ciminstance[`Get-CimInstance`] PowerShell cmdlet or link:https://github.com/vinaypamnani/wmie2[the WMI Explorer tool].
+
+- Ensure that `wmi.warning_threshold` is less than or equal to the module's `period`.
+  This configuration prevents Metricbeat from starting multiple concurrent executions of the same query.
 
-- 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.
+- 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 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.
+- Set up Kibana Alerts for documents generated by this metricset with the `error.message` field.
 
-- [Advanced] Collect WMI-Activity Operational Logs to correlate with Metricbeat WMI warnings.
+- 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`.
 
 
 [float]
 === Compatibility
 
 This module has been tested on the following platform:
 
-- Operating System: Microsoft Windows Server 2019 Datacenter
-- Architecture: x64
+[options="header"]
+|===
+| Operating System | Architecture
+
+| Microsoft Windows Server 2019 Datacenter | x64
+| Microsoft Windows 11 Pro | x64
+|===
 
 Other Windows versions and architectures may also work but have not been explicitly tested.