[receiver/hostmetrics] Use native API instead of WMI to get process.handles on Windows (open-telemetry#38886)

Using the native
[`GetProcessHandleCount`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getprocesshandlecount)
Win32 API via `NumFDsWithContext` already implemented by `gopsutil`
gives a noticeable performance improvement over the current version
using WMI.

* For non-Windows OSes the same behavior is kept for the metric
`process.handles`: it returns a not supported platform error.
* Corrected the documentation of `process.open_file_descriptors` with
the actual behavior - as future breaking change we can consider return
not supported for this metric on Windows.

Expected performance improvement is shown on the image below. On the
image the red line is the new implementation, the green the current one
using WMI, and in blue is the WMI service handling the query made by the
current implementation of the scraper.


![image](https://github.com/user-attachments/assets/4db79415-9e38-4c7f-a27c-99c24ffb24ed)

Author: pjanotti

.chloggen/optimizing-process-handles-metric-on-windows.yaml

@@ -0,0 +1,30 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: hostmetricsreceiver
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Reduced the CPU cost of collecting the `process.handles` metric on Windows.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [38886]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  Instead of using WMI to retrieve the number of opened handles by each process
+  the scraper now uses the GetProcessHandleCount Win32 API which results in
+  reduced CPU usage when the metric `process.handles` is enabled.
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user]

receiver/hostmetricsreceiver/go.mod

@@ -13,7 +13,6 @@ require (
 	github.com/shirou/gopsutil/v4 v4.25.2
 	github.com/stretchr/testify v1.10.0
 	github.com/tilinna/clock v1.1.0
-	github.com/yusufpapurcu/wmi v1.2.4
 	go.opentelemetry.io/collector/component v1.28.2-0.20250319144947-41a9ea7f7402
 	go.opentelemetry.io/collector/component/componenttest v0.122.2-0.20250319144947-41a9ea7f7402
 	go.opentelemetry.io/collector/confmap v1.28.2-0.20250319144947-41a9ea7f7402
@@ -95,6 +94,7 @@ require (
 	github.com/testcontainers/testcontainers-go v0.35.0 // indirect
 	github.com/tklauser/go-sysconf v0.3.12 // indirect
 	github.com/tklauser/numcpus v0.6.1 // indirect
+	github.com/yusufpapurcu/wmi v1.2.4 // indirect
 	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
 	go.opentelemetry.io/collector/consumer/consumererror v0.122.2-0.20250319144947-41a9ea7f7402 // indirect
 	go.opentelemetry.io/collector/consumer/xconsumer v0.122.2-0.20250319144947-41a9ea7f7402 // indirect

receiver/hostmetricsreceiver/internal/scraper/processscraper/documentation.md

@@ -112,7 +112,7 @@ Number of disk operations performed by the process.
 
 ### process.handles
 
-Number of handles held by the process.
+Number of open handles held by the process.
 
 This metric is only available on Windows.
 
@@ -132,7 +132,7 @@ Percentage of total physical memory that is used by the process.
 
 Number of file descriptors in use by the process.
 
-This metric is only available on Linux.
+On Windows this metric captures the number of open handles currently held by the process. If you want to capture this data on Windows use the `process.handles` metric instead to avoid any confusion.
 
 | Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic |
 | ---- | ----------- | ---------- | ----------------------- | --------- |

receiver/hostmetricsreceiver/internal/scraper/processscraper/get_process_handle_count_others.go

@@ -0,0 +1,19 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build !windows
+
+package processscraper // import "github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver/internal/scraper/processscraper"
+
+import (
+	"context"
+	"errors"
+)
+
+const handleCountMetricsLen = 0
+
+var ErrHandlesPlatformSupport = errors.New("process handle collection is only supported on Windows")
+
+func (p *wrappedProcessHandle) GetProcessHandleCountWithContext(_ context.Context) (int64, error) {
+	return 0, ErrHandlesPlatformSupport
+}

receiver/hostmetricsreceiver/internal/scraper/processscraper/get_process_handle_count_windows.go

@@ -0,0 +1,19 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build windows
+
+package processscraper // import "github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver/internal/scraper/processscraper"
+
+import (
+	"context"
+)
+
+const handleCountMetricsLen = 1
+
+func (p *wrappedProcessHandle) GetProcessHandleCountWithContext(ctx context.Context) (int64, error) {
+	// On Windows NumFDsWithContext returns the number of open handles, since it uses the
+	// GetProcessHandleCount API.
+	fds, err := p.Process.NumFDsWithContext(ctx)
+	return int64(fds), err
+}

receiver/hostmetricsreceiver/internal/scraper/processscraper/internal/handlecount/handles.go

@@ -170,7 +170,10 @@ metrics:
   process.open_file_descriptors:
     enabled: false
     description: Number of file descriptors in use by the process.
-    extended_documentation: This metric is only available on Linux.
+    extended_documentation: >-
+      On Windows this metric captures the number of open handles currently held
+      by the process. If you want to capture this data on Windows use the
+      `process.handles` metric instead to avoid any confusion.
     unit: '{count}'
     sum:
       value_type: int
@@ -179,7 +182,7 @@ metrics:
 
   process.handles:
     enabled: false
-    description: Number of handles held by the process.
+    description: Number of open handles held by the process.
     extended_documentation: This metric is only available on Windows.
     unit: '{count}'
     sum:

receiver/hostmetricsreceiver/internal/scraper/processscraper/internal/handlecount/handles_others.go

@@ -95,6 +95,7 @@ type processHandle interface {
 	PageFaultsWithContext(context.Context) (*process.PageFaultsStat, error)
 	NumCtxSwitchesWithContext(context.Context) (*process.NumCtxSwitchesStat, error)
 	NumFDsWithContext(context.Context) (int32, error)
+	GetProcessHandleCountWithContext(context.Context) (int64, error)
 	// If gatherUsed is true, the currently used value will be gathered and added to the resulting RlimitStat.
 	RlimitUsageWithContext(ctx context.Context, gatherUsed bool) ([]process.RlimitStat, error)
 	CgroupWithContext(ctx context.Context) (string, error)