[receiver/hostmetrics/processscraper] Introduce renamed process memor…

…y metrics

Fixes open-telemetry#14327

.chloggen/rename-process-memory-metrics.yaml

@@ -0,0 +1,28 @@
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: deprecation
+
+# 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: Introduce renamed process memory metrics
+
+# One or more tracking issues related to the change
+issues: [14327]
+
+# (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: |
+  This starts the process of phasing out incorrect metric names:
+
+  - `process.memory.physical_usage`
+  - `process.memory.virtual_usage`
+
+  and replacing them with the names adhering to the semantic conventions:
+
+  - `process.memory.usage`
+  - `process.memory.virtual`
+
+  At this stage, the new metrics are added, but they are disabled by default.
+  See the "Deprecations" section of the Host Metrics receiver's README for details.

receiver/hostmetricsreceiver/README.md

@@ -149,7 +149,53 @@ Currently, the hostmetrics receiver does not set any Resource attributes on the
 export OTEL_RESOURCE_ATTRIBUTES="service.name=<the name of your service>,service.namespace=<the namespace of your service>,service.instance.id=<uuid of the instance>"
 ```
 
+## Deprecations
+
+### Transition to process memory metric names aligned with OpenTelemetry specification
+
+The Host Metrics receiver has been emitting the following process memory metrics:
+
+- [process.memory.physical_usage] for the amount of physical memory used by the process,
+- [process.memory.virtual_usage] for the amount of virtual memory used by the process.
+
+This is in conflict with the OpenTelemetry specification,
+which defines [process.memory.usage] and [process.memory.virtual] as the names for these metrics.
+
+To align the emitted metric names with the OpenTelemetry specification,
+the following process will be followed to phase out the old metrics:
+
+- Until and including `v0.63.0`, only the old metrics `process.memory.physical_usage` and `process.memory.virtual_usage` are emitted.
+  You can use the [Metrics Transform processor][metricstransformprocessor_docs] to rename them.
+- Between `v0.64.0` and `v0.66.0`, the new metrics are introduced and the old metrics are marked as deprecated.
+  Both the new and the old metrics are emitted by default.
+- Between `v0.67.0` and `v0.69.0`, the old metrics are disabled by default.
+- In `v0.70.0` and up, the old metrics are removed.
+
+To change the enabled state for the specific metrics, use the standard configuration options that are available for all metrics.
+
+Here's an example configuration to disable the old metrics and enable the new metrics:
+
+```yaml
+receivers:
+  hostmetrics:
+    scrapers:
+      process:
+        metrics:
+          process.memory.physical_usage:
+            enabled: false
+          process.memory.virtual_usage:
+            enabled: false
+          process.memory.usage:
+            enabled: true
+          process.memory.virtual:
+            enabled: true
+```
+
 [beta]: https://github.com/open-telemetry/opentelemetry-collector#beta
 [contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib
 [core]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol
-
+[process.memory.physical_usage]: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.63.0/receiver/hostmetricsreceiver/internal/scraper/processscraper/metadata.yaml#L61
+[process.memory.virtual_usage]: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.63.0/receiver/hostmetricsreceiver/internal/scraper/processscraper/metadata.yaml#L70
+[process.memory.usage]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.14.0/specification/metrics/semantic_conventions/process-metrics.md?plain=1#L38
+[process.memory.virtual]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.14.0/specification/metrics/semantic_conventions/process-metrics.md?plain=1#L39
+[metricstransformprocessor_docs]: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.63.0/processor/metricstransformprocessor/README.md

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

@@ -11,8 +11,10 @@ These are the metrics available for this scraper.
 | process.context_switches | Number of times the process has been context switched. | {count} | Sum(Int) | <ul> <li>context_switch_type</li> </ul> |
 | **process.cpu.time** | Total CPU seconds broken down by different states. | s | Sum(Double) | <ul> <li>state</li> </ul> |
 | **process.disk.io** | Disk bytes transferred. | By | Sum(Int) | <ul> <li>direction</li> </ul> |
-| **process.memory.physical_usage** | The amount of physical memory in use | By | Sum(Int) | <ul> </ul> |
-| **process.memory.virtual_usage** | Virtual memory size. | By | Sum(Int) | <ul> </ul> |
+| **process.memory.physical_usage** | Deprecated: use `process.memory.usage` metric instead. The amount of physical memory in use. | By | Sum(Int) | <ul> </ul> |
+| process.memory.usage | The amount of physical memory in use. | By | Sum(Int) | <ul> </ul> |
+| process.memory.virtual | Virtual memory size. | By | Sum(Int) | <ul> </ul> |
+| **process.memory.virtual_usage** | Deprecated: Use `process.memory.virtual` metric instead. Virtual memory size. | By | Sum(Int) | <ul> </ul> |
 | process.open_file_descriptors | Number of file descriptors in use by the process. | {count} | Sum(Int) | <ul> </ul> |
 | process.paging.faults | Number of page faults the process has made. This metric is only available on Linux. | {faults} | Sum(Int) | <ul> <li>paging_fault_type</li> </ul> |
 | process.threads | Process threads count. | {threads} | Sum(Int) | <ul> </ul> |

receiver/hostmetricsreceiver/internal/scraper/processscraper/metadata.yaml

@@ -70,7 +70,16 @@ metrics:
 
   process.memory.physical_usage:
     enabled: true
-    description: The amount of physical memory in use
+    description: "Deprecated: use `process.memory.usage` metric instead. The amount of physical memory in use."
+    unit: By
+    sum:
+      value_type: int
+      aggregation: cumulative
+      monotonic: false
+
+  process.memory.usage:
+    enabled: false
+    description: The amount of physical memory in use.
     unit: By
     sum:
       value_type: int
@@ -79,6 +88,15 @@ metrics:
 
   process.memory.virtual_usage:
     enabled: true
+    description: "Deprecated: Use `process.memory.virtual` metric instead. Virtual memory size."
+    unit: By
+    sum:
+      value_type: int
+      aggregation: cumulative
+      monotonic: false
+
+  process.memory.virtual:
+    enabled: false
     description: Virtual memory size.
     unit: By
     sum:

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

@@ -237,6 +237,8 @@ func (s *scraper) scrapeAndAppendMemoryUsageMetrics(now pcommon.Timestamp, handl
 
 	s.mb.RecordProcessMemoryPhysicalUsageDataPoint(now, int64(mem.RSS))
 	s.mb.RecordProcessMemoryVirtualUsageDataPoint(now, int64(mem.VMS))
+	s.mb.RecordProcessMemoryUsageDataPoint(now, int64(mem.RSS))
+	s.mb.RecordProcessMemoryVirtualDataPoint(now, int64(mem.VMS))
 	return nil
 }
 

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

@@ -63,7 +63,7 @@ func TestScrape(t *testing.T) {
 	}
 	testCases := []testCase{
 		{
-			name: "Standard",
+			name: "Default set of metrics",
 		},
 		{
 			name: "Enable Linux-only metrics",