[receiver/hostmetrics] Use native API instead of WMI to get process.handles on Windows

.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/metadata.yaml

@@ -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/process.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)