Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[windows exporter] Clarify the use of use_api in docs. #6603

Merged
merged 3 commits into from
Oct 16, 2024
Merged

[windows exporter] Clarify the use of use_api in docs. #6603

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
da7bb0f
Clarify the use of use_api in docs.
ptodev Mar 5, 2024
f028491
Apply suggestions from code review
ptodev Jun 4, 2024
1cefbe9
Merge branch 'main' into ptodev/clarify-use-api
clayton-cornell Oct 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions docs/sources/flow/reference/components/prometheus.exporter.windows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
The WMI is slow to query data, but it provides detailed results. The Windows API is fast but you must make several API calls to get the same amount of information. If speed is important and the WMI takes too long to retrieve information, you can set `use_api` to `true` to use the API to query your data.

I gave it a go at tweaking the text here a little to add a little more contextual info and details. Just saying the API is more performant doesn't tell you very much.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TBH I think the extra text feels a bit vague and creates more questions than answers.

The WMI is slow to query data, but it provides detailed results.

Why is it more detailed?

The Windows API is fast but you must make several API calls to get the same amount of information.

Do the number of API calls matter? And I'm not sure where we got this information from?

I'm personally not an expert on this exporter so I'd prefer not to add too much information that I'm not sure about 😅

Setting `use_api` to `true` does have a few disadvantages compared to using WMI:
* WMI queries in `where_clause` won't work.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any alternative here? The second bullet provides an alternate solution.. so I'm wondering what happens in this case.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think there are alternatives. But I also don't think it's worth elaborating too much on this, since it seems natural that the "WMI queries" feature won't work when "WMI" is disabled.

The second bullet point is not related to WMI queries IIUC.

* The `status` field of the service is not available. You can use the `state` property to retrieve status information. This property provides the same information, but it is formatted differently.


### smtp block

Expand Down
9 changes: 9 additions & 0 deletions docs/sources/static/configuration/integrations/windows-exporter-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading