Avoid new CPU logical metadata attribute

Use the existing cpu metadata attribute as opt-in instead of introducing cpu.logical_number. Add a changelog entry with config to restore per-CPU output and update frequency tests for the shared opt-in CPU attribute.

Assisted-by: GPT-5

Author: dmitryax

.chloggen/49161-hostmetrics-cpu-attribute-opt-in.yaml

@@ -0,0 +1,29 @@
+change_type: breaking
+component: receiver/host_metrics
+note: Make the `cpu` attribute opt-in for hostmetrics CPU scraper metrics.
+issues: [49161]
+subtext: |
+  By default, `system.cpu.time` and `system.cpu.utilization` are now aggregated across logical CPUs and no longer include the `cpu` attribute.
+  To restore the previous per-logical-CPU output, configure:
+  ```yaml
+  receivers:
+    hostmetrics:
+      scrapers:
+        cpu:
+          metrics:
+            system.cpu.time:
+              attributes: [cpu, state]
+            system.cpu.utilization:
+              attributes: [cpu, state]
+  ```
+  If `system.cpu.frequency` is enabled and the per-CPU label is required, also configure:
+  ```yaml
+  receivers:
+    hostmetrics:
+      scrapers:
+        cpu:
+          metrics:
+            system.cpu.frequency:
+              attributes: [cpu]
+  ```
+change_logs: [user]

receiver/hostmetricsreceiver/internal/scraper/cpuscraper/cpu_scraper_linux_test.go

@@ -20,15 +20,25 @@ import (
 
 func TestScrape_CpuFrequency(t *testing.T) {
 	type testCase struct {
-		name             string
-		enabledFrequency bool
+		name              string
+		enabledFrequency  bool
+		enabledAttributes []metadata.SystemCPUFrequencyMetricAttributeKey
+		expectCPUAttr     bool
 	}
 
 	testCases := []testCase{
 		{
 			name:             "System CPU Frequency enabled",
 			enabledFrequency: true,
 		},
+		{
+			name:             "System CPU Frequency enabled with CPU attribute",
+			enabledFrequency: true,
+			enabledAttributes: []metadata.SystemCPUFrequencyMetricAttributeKey{
+				metadata.SystemCPUFrequencyMetricAttributeKeyCPU,
+			},
+			expectCPUAttr: true,
+		},
 		{
 			name:             "System CPU Frequency disabled",
 			enabledFrequency: false,
@@ -42,6 +52,7 @@ func TestScrape_CpuFrequency(t *testing.T) {
 			cfg := metadata.NewDefaultMetricsBuilderConfig()
 			cfg.Metrics.SystemCPUTime.Enabled = false
 			cfg.Metrics.SystemCPUFrequency.Enabled = test.enabledFrequency
+			cfg.Metrics.SystemCPUFrequency.EnabledAttributes = test.enabledAttributes
 
 			scraper := newCPUScraper(t.Context(), scrapertest.NewNopSettings(metadata.Type),
 				&Config{MetricsBuilderConfig: cfg})
@@ -66,12 +77,12 @@ func TestScrape_CpuFrequency(t *testing.T) {
 
 			metrics := md.ResourceMetrics().At(0).ScopeMetrics().At(0).Metrics()
 			metric := metrics.At(0)
-			assertCPUFrequencyMetricValid(t, metric)
+			assertCPUFrequencyMetricValid(t, metric, test.expectCPUAttr)
 		})
 	}
 }
 
-func assertCPUFrequencyMetricValid(t *testing.T, metric pmetric.Metric) {
+func assertCPUFrequencyMetricValid(t *testing.T, metric pmetric.Metric, expectCPUAttr bool) {
 	expected := pmetric.NewMetric()
 	expected.SetName("system.cpu.frequency")
 	expected.SetDescription("Current frequency of the CPU core in Hz.")
@@ -80,15 +91,24 @@ func assertCPUFrequencyMetricValid(t *testing.T, metric pmetric.Metric) {
 	internal.AssertDescriptorEqual(t, expected, metric)
 
 	numCPUs := runtime.NumCPU()
-	require.GreaterOrEqual(t, metric.Gauge().DataPoints().Len(), numCPUs,
-		"Should have at least one frequency data point per CPU")
+	if expectCPUAttr {
+		require.GreaterOrEqual(t, metric.Gauge().DataPoints().Len(), numCPUs,
+			"Should have at least one frequency data point per CPU")
+	} else {
+		require.Equal(t, 1, metric.Gauge().DataPoints().Len(),
+			"Should aggregate frequency data points across CPUs by default")
+	}
 
 	if metric.Gauge().DataPoints().Len() > 0 {
 		dp := metric.Gauge().DataPoints().At(0)
 
 		cpuAttr, exists := dp.Attributes().Get("cpu")
-		require.True(t, exists, "Data point should have 'cpu' attribute")
-		require.Contains(t, cpuAttr.Str(), "cpu", "CPU attribute should contain 'cpu' prefix")
+		if expectCPUAttr {
+			require.True(t, exists, "Data point should have 'cpu' attribute")
+			require.Contains(t, cpuAttr.Str(), "cpu", "CPU attribute should contain 'cpu' prefix")
+		} else {
+			require.False(t, exists, "Data point should not have 'cpu' attribute by default")
+		}
 
 		require.GreaterOrEqual(t, dp.DoubleValue(), 0.0, "CPU frequency should be non-negative")
 	}

receiver/hostmetricsreceiver/internal/scraper/cpuscraper/cpu_scraper_test.go

@@ -355,7 +355,7 @@ func TestScrape_CPUTimeAttributeConfiguration(t *testing.T) {
 			metricsConfig: func() metadata.MetricsBuilderConfig {
 				cfg := metadata.NewDefaultMetricsBuilderConfig()
 				cfg.Metrics.SystemCPUTime.EnabledAttributes = []metadata.SystemCPUTimeMetricAttributeKey{
-					metadata.SystemCPUTimeMetricAttributeKeyCPULogicalNumber,
+					metadata.SystemCPUTimeMetricAttributeKeyCPU,
 					metadata.SystemCPUTimeMetricAttributeKeyState,
 				}
 				return cfg
@@ -460,7 +460,7 @@ func TestScrape_CpuUtilizationStandard(t *testing.T) {
 				cfg.Metrics.SystemCPUUtilization.Enabled = true
 				cfg.Metrics.SystemCPUTime.Enabled = false
 				cfg.Metrics.SystemCPUUtilization.EnabledAttributes = []metadata.SystemCPUUtilizationMetricAttributeKey{
-					metadata.SystemCPUUtilizationMetricAttributeKeyCPULogicalNumber,
+					metadata.SystemCPUUtilizationMetricAttributeKeyCPU,
 					metadata.SystemCPUUtilizationMetricAttributeKeyState,
 				}
 				return cfg

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

@@ -49,7 +49,7 @@ Current frequency of the CPU core in Hz.
 
 | Name | Description | Values | Requirement Level | Semantic Convention |
 | ---- | ----------- | ------ | ----------------- | ------------------- |
-| cpu | Logical CPU number starting at 0. | Any Str | Recommended | - |
+| cpu | Logical CPU number starting at 0. | Any Str | Opt-In | - |
 
 ### system.cpu.logical.count
 

receiver/hostmetricsreceiver/internal/scraper/cpuscraper/internal/metadata/generated_config.go

@@ -12,12 +12,6 @@ sem_conv_version: 1.9.0
 
 attributes:
   cpu:
-    description: Logical CPU number starting at 0.
-    type: string
-    requirement_level: recommended
-
-  cpu.logical_number:
-    name_override: cpu
     description: Logical CPU number starting at 0.
     type: string
     requirement_level: opt_in
@@ -67,7 +61,7 @@ metrics:
       value_type: double
       aggregation_temporality: cumulative
       monotonic: true
-    attributes: [cpu.logical_number, state]
+    attributes: [cpu, state]
 
   system.cpu.utilization:
     enabled: false
@@ -76,4 +70,4 @@ metrics:
     stability: development
     gauge:
       value_type: double
-    attributes: [cpu.logical_number, state]
+    attributes: [cpu, state]