You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Add windows 11 to compatibility section
* WIP: Improve documentation after support feedback + Improve cache explanation
* Use tag note instead of info
* Improve wording
* Make sure the warning is marked as such, use a more precise link
* Fix comma
* Fix some wording
* Update docs/reference/metricbeat/metricbeat-metricset-windows-wmi.md
* Update docs/reference/metricbeat/metricbeat-metricset-windows-wmi.md
* Update docs/reference/metricbeat/metricbeat-metricset-windows-wmi.md
* Update docs/reference/metricbeat/metricbeat-metricset-windows-wmi.md
* Update docs/reference/metricbeat/metricbeat-metricset-windows-wmi.md
* Update docs/reference/metricbeat/metricbeat-metricset-windows-wmi.md
* Clarify the wmi.schema_cache_size based on the comments
* Make sure to update docs.md as well
* Remove erronously added line
---------
(cherry picked from commit f23a53a)
Co-authored-by: Mirko Bez <[email protected]>
Co-authored-by: Visha Angelova <[email protected]>
Copy file name to clipboardExpand all lines: docs/reference/metricbeat/metricbeat-metricset-windows-wmi.md
+28-18Lines changed: 28 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,12 +13,11 @@ applies_to:
13
13
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.
14
14
::::
15
15
16
-
17
-
The `wmi` metricset of the Windows module reads metrics via Windows Management Instrumentation [(WMI)](https://learn.microsoft.com/en-us/windows/win32/wmisdk/about-wmi), a core management technology in the Windows Operating system.
16
+
The `wmi` metricset of the Windows module reads metrics via [Windows Management Instrumentation](https://learn.microsoft.com/en-us/windows/win32/wmisdk/about-wmi) (WMI), a core management technology in the Windows Operating system.
18
17
19
18
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.
20
19
21
-
This metricset leverages the [Microsoft WMI](https://github.com/microsoft/wmi), library a convenient wrapper around the [GO-OLE](https://github.com/go-ole) library which allows to invoke the WMI Api.
20
+
This metricset leverages the [Microsoft WMI](https://github.com/microsoft/wmi) library, a convenient wrapper around the [GO-OLE](https://github.com/go-ole) library which allows to invoke the WMI API.
22
21
23
22
## WMI Query Language (WQL) Support
24
23
@@ -30,11 +29,14 @@ namespaces.
30
29
Currently, the metricset supports queries with `SELECT`, `FROM` and
31
30
`WHERE` clauses.
32
31
33
-
When working with WMI queries, it is the user’s responsibility to ensure
32
+
::::{warning}
33
+
When working with WMI queries, it is the user's responsibility to ensure
34
34
that queries are safe, efficient, and do not cause unintended side
35
35
effects. A notorious example of a problematic WMI class is
does not provide direct type conversion for `uint64`, `sint64`, and `datetime` CIM types;
68
+
does not provide direct type conversion for `uint64`, `sint64`, and `datetime`
69
+
[Common Information Model](https://learn.microsoft.com/en-us/windows/win32/wmisdk/common-information-model) (CIM) types;
65
70
instead, these values are returned as strings.
66
71
67
72
To ensure the correct data type is reported, Metricbeat dynamically fetches the
68
-
CIM type definitions for the properties of the WMI instance classes involved in the query,
73
+
CIM type definitions for the properties of the WMI instance classes returned by the query,
69
74
and then performs the necessary data type conversions.
70
75
71
76
To optimize performance and avoid repeatedly fetching these schema definitions
72
77
for every row and every request, an LRU cache is utilized. This cache stores
73
-
the schema definition for each unique WMI class encountered. For queries involving
78
+
the schema definition for each WMI class-property pair encountered. For queries involving
74
79
superclasses, such as `CIM_LogicalDevice`, the cache will populate with individual entries
75
80
for each specific derived class (leaf of the class hierarchy) whose instances are returned by the query (for example, `Win32_DiskDrive` or `Win32_NetworkAdapter`).
76
81
77
82
::::{note}
78
83
The properties of type `CIM_Object` (embedded objects) are not yet supported and are ignored.
79
84
::::
80
85
86
+
::::{note}
87
+
Properties of type `CIM_Reference` (references), which are used in [WMI Association Classes](https://learn.microsoft.com/en-us/windows/win32/wmisdk/declaring-an-association-class), are currently returned as string values exactly as reported by the [Microsoft WMI](https://github.com/microsoft/wmi) library.
88
+
::::
89
+
81
90
## Configuration
82
91
83
92
```yaml
@@ -107,7 +116,7 @@ The properties of type `CIM_Object` (embedded objects) are not yet supported and
107
116
108
117
**`wmi.namespace`**
109
118
: The default WMI namespace used for queries. This can be overridden per
110
-
query. The default is `root\cimv2`.
119
+
query. The default is `"root\\cimv2"`.
111
120
112
121
**`wmi.warning_threshold`**
113
122
: The time threshold after which Metricbeat will stop waiting for the
@@ -138,9 +147,8 @@ The default value is `0`, which is a special value indicating that all fetched
138
147
results should be returned without a row limit.
139
148
140
149
**`wmi.schema_cache_size`**
141
-
: 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](#wmi-type-support).
142
-
For example, if a superclass is queried, the cache
143
-
might store all its derived classes (leaves of the class hierarchy) to optimize subsequent operations.
150
+
: The maximum number of WMI class-property pairs that can be cached per single query. Every query keeps its own separate cache.
151
+
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`).
- 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.
199
207
200
-
- Set up alerts in Metricbeat for documents with the `error.message` field set.
208
+
- Set up Kibana Alerts for documents generated by this metricset with the `error.message` field.
201
209
202
-
- [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`.
210
+
- 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`.
203
211
204
212
## Compatibility
205
213
206
-
This module has been tested on the following platform:
214
+
This module has been tested on the following platforms:
207
215
208
-
- Operating System: Microsoft Windows Server 2019 Datacenter
Copy file name to clipboardExpand all lines: metricbeat/module/windows/wmi/_meta/docs.md
+29-18Lines changed: 29 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,12 +2,11 @@
2
2
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.
3
3
::::
4
4
5
-
6
-
The `wmi` metricset of the Windows module reads metrics via Windows Management Instrumentation [(WMI)](https://learn.microsoft.com/en-us/windows/win32/wmisdk/about-wmi), a core management technology in the Windows Operating system.
5
+
The `wmi` metricset of the Windows module reads metrics via [Windows Management Instrumentation](https://learn.microsoft.com/en-us/windows/win32/wmisdk/about-wmi) (WMI), a core management technology in the Windows Operating system.
7
6
8
7
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.
9
8
10
-
This metricset leverages the [Microsoft WMI](https://github.com/microsoft/wmi), library a convenient wrapper around the [GO-OLE](https://github.com/go-ole) library which allows to invoke the WMI Api.
9
+
This metricset leverages the [Microsoft WMI](https://github.com/microsoft/wmi) library, a convenient wrapper around the [GO-OLE](https://github.com/go-ole) library which allows to invoke the WMI API.
11
10
12
11
## WMI Query Language (WQL) Support
13
12
@@ -19,11 +18,14 @@ namespaces.
19
18
Currently, the metricset supports queries with `SELECT`, `FROM` and
20
19
`WHERE` clauses.
21
20
22
-
When working with WMI queries, it is the user’s responsibility to ensure
21
+
::::{warning}
22
+
When working with WMI queries, it is the user's responsibility to ensure
23
23
that queries are safe, efficient, and do not cause unintended side
24
24
effects. A notorious example of a problematic WMI class is
does not provide direct type conversion for `uint64`, `sint64`, and `datetime` CIM types;
57
+
does not provide direct type conversion for `uint64`, `sint64`, and `datetime`
58
+
[Common Information Model](https://learn.microsoft.com/en-us/windows/win32/wmisdk/common-information-model) (CIM) types;
54
59
instead, these values are returned as strings.
55
60
56
61
To ensure the correct data type is reported, Metricbeat dynamically fetches the
57
-
CIM type definitions for the properties of the WMI instance classes involved in the query,
62
+
CIM type definitions for the properties of the WMI instance classes returned by the query,
58
63
and then performs the necessary data type conversions.
59
64
60
65
To optimize performance and avoid repeatedly fetching these schema definitions
61
66
for every row and every request, an LRU cache is utilized. This cache stores
62
-
the schema definition for each unique WMI class encountered. For queries involving
67
+
the schema definition for each WMI class-property pair encountered. For queries involving
63
68
superclasses, such as `CIM_LogicalDevice`, the cache will populate with individual entries
64
69
for each specific derived class (leaf of the class hierarchy) whose instances are returned by the query (for example, `Win32_DiskDrive` or `Win32_NetworkAdapter`).
65
70
66
71
::::{note}
67
72
The properties of type `CIM_Object` (embedded objects) are not yet supported and are ignored.
68
73
::::
69
74
75
+
::::{note}
76
+
Properties of type `CIM_Reference` (references), which are used in [WMI Association Classes](https://learn.microsoft.com/en-us/windows/win32/wmisdk/declaring-an-association-class), are currently returned as string values exactly as reported by the [Microsoft WMI](https://github.com/microsoft/wmi) library.
77
+
::::
78
+
70
79
## Configuration
71
80
72
81
```yaml
@@ -96,7 +105,7 @@ The properties of type `CIM_Object` (embedded objects) are not yet supported and
96
105
97
106
**`wmi.namespace`**
98
107
: The default WMI namespace used for queries. This can be overridden per
99
-
query. The default is `root\cimv2`.
108
+
query. The default is `"root\\cimv2"`.
100
109
101
110
**`wmi.warning_threshold`**
102
111
: The time threshold after which Metricbeat will stop waiting for the
@@ -127,9 +136,8 @@ The default value is `0`, which is a special value indicating that all fetched
127
136
results should be returned without a row limit.
128
137
129
138
**`wmi.schema_cache_size`**
130
-
: 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](#wmi-type-support).
131
-
For example, if a superclass is queried, the cache
132
-
might store all its derived classes (leaves of the class hierarchy) to optimize subsequent operations.
139
+
: The maximum number of WMI class-property pairs that can be cached per single query. Every query keeps its own separate cache.
140
+
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`).
- 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.
188
196
189
-
- Set up alerts in Metricbeat for documents with the `error.message` field set.
197
+
- Set up Kibana Alerts for documents generated by this metricset with the `error.message` field.
190
198
191
-
- [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`.
199
+
- 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`.
192
200
193
201
## Compatibility
194
202
195
-
This module has been tested on the following platform:
203
+
This module has been tested on the following platforms:
196
204
197
-
- Operating System: Microsoft Windows Server 2019 Datacenter
![mergify[bot]](https://avatars.githubusercontent.com/in/10562?v=4&size=40){kind=avatar}
0 commit comments