Clarify the use of use_api in docs.

grafana · Mar 5, 2024 · cef9703 · cef9703
1 parent 1a642cf
commit cef9703
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 4 deletions.
diff --git a/docs/sources/flow/reference/components/prometheus.exporter.windows.md b/docs/sources/flow/reference/components/prometheus.exporter.windows.md
@@ -172,14 +172,19 @@ For a server name to be included, it must match the regular expression specified
 
 ### service block
 
-Name           | Type     | Description                                           | Default | Required
----------------|----------|-------------------------------------------------------|---------|---------
-`use_api`      | `string` | Use API calls to collect service data instead of WMI. | `false` | no
-`where_clause` | `string` | WQL 'where' clause to use in WMI metrics query.       | `""`    | no
+Name           | Type     | Description                                                 | Default | Required
+---------------|----------|-------------------------------------------------------------|---------|---------
+`use_api`      | `string` | Use the Windows API to collect service data instead of WMI. | `false` | no
+`where_clause` | `string` | WQL 'where' clause to use in WMI metrics query.             | `""`    | no
 
 The `where_clause` argument can be used to limit the response to the services you specify, reducing the size of the response.
 If `use_api` is enabled, 'where_clause' won't be effective.
 
+The Windows API is more performant than WMI. Set `use_api` to `true` in situations when the WMI takes too long to get the service information.
+Setting `use_api` to `true` does have a few disadvantages compared to using WMI:
+* WMI queries in `where_clause` won't work.
+* The `status` field of the service won't be reported. Instead, use the `state` property. It has the same information, albeit formatted differently.
+
 
 ### smtp block
 

diff --git a/docs/sources/static/configuration/integrations/windows-exporter-config.md b/docs/sources/static/configuration/integrations/windows-exporter-config.md
@@ -113,6 +113,15 @@ Full reference of options:
     # "WQL 'where' clause to use in WMI metrics query. Limits the response to the services you specify and reduces the size of the response.
     # Maps to collector.service.services-where in windows_exporter
     [where_clause: <string> | default=""]
+    # If "use_api" is set to "true", service data will be collected via the Windows API.
+    # If "use_api" is set to "false", service data will be collected via WMI.
+    # When "use_api" is set to "true", "where_clause" will be ignored and will not take effect.
+    # The Windows API is more performant than WMI. Set `use_api` to `true` in situations when the WMI takes too long to get the service information.
+    # Setting `use_api` to `true` does have a few disadvantages compared to using WMI:
+    # * WMI queries in `where_clause` won't work.
+    # * The `status` field of the service won't be reported. Instead, use the `state` property. 
+    #   It has the same information, albeit formatted differently.
+    [use_api: <boolean> | default = false]
 
   # Configuration for physical disk on Windows 
   physical_disk: